• Stars
    star
    112
  • Rank 312,160 (Top 7 %)
  • Language
    C#
  • License
    Apache License 2.0
  • Created over 6 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The Seq command-line client. Administer, log, ingest, search, from any OS.

seqcli Build status GitHub release

The Seq client command-line app. Supports logging (seqcli log), searching (search), tailing (tail), querying (query) and JSON or plain-text log file ingestion (ingest), and much more.

SeqCli Screenshot

Getting started

The Seq installer for Windows includes seqcli. Otherwise, download the release for your operating system. Or, if you have dotnet installed, seqcli can be installed as a global tool using:

dotnet tool install --global seqcli

To set a default server URL and API key, run:

seqcli config -k connection.serverUrl -v https://your-seq-server
seqcli config -k connection.apiKey -v your-api-key

The API key will be stored in your SeqCli.json configuration file; on Windows, this is encrypted using DPAPI; on Mac/Linux the key is currently stored in plain text. As an alternative to storing the API key in configuration, it can be passed to each command via the --apikey= argument.

seqcli is also available as a Docker container under datalust/seqcli:

docker run --rm datalust/seqcli:latest <command> [<args>]

To connect to Seq in a docker container on the local machine use the machine's IP address (not localhost) or specify docker host networking with --net host.

Use Docker networks and volumes to make local files and other containers accessible to seqcli within its container.

Connecting without an API key

If you're automating Seq setup, chances are you won't have an API key yet for seqcli to use. During the initial Seq server configuration, you can specify firstRun.adminUsername and firstRun.adminPasswordHash (or the equivalent environment variables SEQ_FIRSTRUN_ADMINUSERNAME and SEQ_FIRSTRUN_ADMINPASSWORDHASH) to set an initial username and password for the administrator account. You can use these to create an API key, and then use the API key token with the remaining seqcli commands.

The seqcli apikey create command accepts --connect-username and --connect-password-stdin, and prints the new API key token to STDOUT (PowerShell syntax is used below):

$user = "admin"
$pw = "thepassword"
$token = (
  echo $pw |
  seqcli apikey create `
    -t CLI `
    --permissions="read,write,project,organization,system" `
    --connect-username $user --connect-password-stdin
)

Contributing

See CONTRIBUTING.md.

Commands

Usage:

seqcli <command> [<args>]

Available commands:

  • apikey
  • app
    • app define β€” Generate an app definition for a .NET [SeqApp] plug-in.
    • app install β€” Install an app package.
    • app run β€” Host a .NET [SeqApp] plug-in.
    • app update β€” Update an installed app package.
  • bench β€” Measure query performance.
  • config β€” View and set fields in the SeqCli.json file; run with no arguments to list all fields.
  • dashboard
  • feed
  • help β€” Show information about available commands.
  • ingest β€” Send log events from a file or STDIN.
  • license apply β€” Apply a license to the Seq server.
  • log β€” Send a structured log event to the server.
  • node
    • node demote β€” Begin demotion of the current leader node.
    • node health β€” Probe a Seq node's /health endpoint, and print the returned HTTP status code, or 'Unreachable' if the endpoint could not be queried.
    • node list β€” List nodes in the Seq cluster.
  • print β€” Pretty-print events in CLEF/JSON format, from a file or STDIN.
  • profile
  • query β€” Execute an SQL query and receive results in CSV format.
  • retention
  • sample
    • sample ingest β€” Log sample events into a Seq instance.
    • sample setup β€” Configure a Seq instance with sample dashboards, signals, users, and so on.
  • search β€” Retrieve log events that match a given filter.
  • signal
  • tail β€” Stream log events matching a filter.
  • template
  • user
  • version β€” Print the current executable version.
  • workspace

apikey create

Create an API key for automation or ingestion.

Example:

seqcli apikey create -t 'Test API Key' -p Environment=Test
Option Description
-t, --title=VALUE A title for the API key
--token=VALUE A pre-allocated API key token; by default, a new token will be generated and written to STDOUT
-p, --property=NAME=VALUE Specify name/value properties, e.g. -p Customer=C123 -p Environment=Production
--filter=VALUE A filter to apply to incoming events
--minimum-level=VALUE The minimum event level/severity to accept; the default is to accept all events
--use-server-timestamps Discard client-supplied timestamps and use server clock values
--permissions=VALUE A comma-separated list of permissions to delegate to the API key; valid permissions are Ingest (default), Read, Write, Project and System
--connect-username=VALUE A username to connect with, useful primarily when setting up the first API key
--connect-password=VALUE When connect-username is specified, a corresponding password
--connect-password-stdin When connect-username is specified, read the corresponding password from STDIN
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)

apikey list

List available API keys.

Example:

seqcli apikey list
Option Description
-t, --title=VALUE The title of the API key(s) to list
-i, --id=VALUE The id of a single API key to list
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

apikey remove

Remove an API key from the server.

Example:

seqcli apikey remove -t 'Test API Key'
Option Description
-t, --title=VALUE The title of the API key(s) to remove
-i, --id=VALUE The id of a single API key to remove
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

app define

Generate an app definition for a .NET [SeqApp] plug-in.

Example:

seqcli app define -d "./bin/Debug/netstandard2.2"
Option Description
-d, --directory=VALUE The directory containing .NET Standard assemblies; defaults to the current directory
--type=VALUE The [SeqApp] plug-in type name; defaults to scanning assemblies for a single type marked with this attribute
--indented Format the definition over multiple lines with indentation

app install

Install an app package.

Example:

seqcli app install --package-id 'Seq.App.JsonArchive'
Option Description
--package-id=VALUE The package id of the app to install
--version=VALUE The package version to install; the default is to install the latest version
--feed-id=VALUE The id of the NuGet feed to install the package from; may be omitted if only one feed is configured
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)

app run

Host a .NET [SeqApp] plug-in.

Example:

seqcli tail --json | seqcli app run -d "./bin/Debug/netstandard2.2" -p [email protected]
Option Description
-d, --directory=VALUE The directory containing .NET Standard assemblies; defaults to the current directory
--type=VALUE The [SeqApp] plug-in type name; defaults to scanning assemblies for a single type marked with this attribute
-p, --property=NAME=VALUE Specify name/value settings for the app, e.g. -p [email protected] -p Subject="Alert!"
--storage=VALUE A directory in which app-specific data can be stored; defaults to the current directory
-s, --server=VALUE The URL of the Seq server, used only for app configuration (no connection is made to the server); by default the connection.serverUrl value will be used
--server-instance=VALUE The instance name of the Seq server, used only for app configuration; defaults to no instance name
-t, --title=VALUE The app instance title, used only for app configuration; defaults to a placeholder title.
--id=VALUE The app instance id, used only for app configuration; defaults to a placeholder id.
--read-env Read app configuration and settings from environment variables, as specified in https://docs.datalust.co/docs/seq-apps-in-other-languages; ignores all options except --directory and --type

app update

Update an installed app package.

Example:

seqcli app update -n 'HTML Email'
Option Description
-i, --id=VALUE The id of a single installed app to update
-n, --name=VALUE The name of the installed app to update
--all Update all installed apps; not compatible with -i or -n
--version=VALUE The package version to update to; the default is to update to the latest version in the associated feed
--force Update the app even if the target version is already installed
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)

bench

Measure query performance.

Option Description
-r, --runs=VALUE The number of runs to execute
-c, --cases=VALUE A JSON file containing the set of cases to run. Defaults to a standard set of cases.
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used
--start=VALUE ISO 8601 date/time to query from
--end=VALUE ISO 8601 date/time to query to
--reporting-server=VALUE The address of a Seq server to send bench results to
--reporting-apikey=VALUE The API key to use when connecting to the reporting server

config

View and set fields in the SeqCli.json file; run with no arguments to list all fields.

Option Description
-k, --key=VALUE The field, for example connection.serverUrl
-v, --value=VALUE The field value; if not specified, the command will print the current value
-c, --clear Clear the field

dashboard list

List dashboards.

Example:

seqcli dashboard list
Option Description
-t, --title=VALUE The title of the dashboard(s) to list
-i, --id=VALUE The id of a single dashboard to list
-o, --owner=VALUE The id of the user to list dashboards for; by default, shared dashboards are listd
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

dashboard remove

Remove a dashboard from the server.

Example:

seqcli dashboard remove -i dashboard-159
Option Description
-t, --title=VALUE The title of the dashboard(s) to remove
-i, --id=VALUE The id of a single dashboard to remove
-o, --owner=VALUE The id of the user to remove dashboards for; by default, shared dashboards are removd
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

dashboard render

Produce a CSV or JSON result set from a dashboard chart.

Example:

seqcli dashboard render -i dashboard-159 -c 'Response Time (ms)' --last 7d --by 1h
Option Description
-i, --id=VALUE The id of a single dashboard to render
-c, --chart=VALUE The title of a chart on the dashboard to render
--last=VALUE A duration over which the chart should be rendered, e.g. 7d; this will be aligned to an interval boundary; either --last or --start and --end must be specified
--by=VALUE The time-slice interval for the chart data, as a duration, e.g. 1h
--start=VALUE ISO 8601 date/time to query from
--end=VALUE ISO 8601 date/time to query to
--signal=VALUE A signal expression or list of intersected signal ids to apply, for example signal-1,signal-2
--timeout=VALUE The execution timeout in milliseconds
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

feed create

Create a NuGet feed.

Example:

seqcli feed create -n 'CI' --location="https://f.feedz.io/example/ci" -u Seq --password-stdin
Option Description
-n, --name=VALUE A unique name for the feed
-l, --location=VALUE The feed location; this may be a NuGet v2 or v3 feed URL, or a local filesystem path on the Seq server
-u, --username=VALUE The username Seq should supply when connecting to the feed, if authentication is required
-p, --password=VALUE A feed password, if authentication is required; note that --password-stdin is more secure
--password-stdin Read the feed password from STDIN
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)

feed list

List NuGet feeds.

Example:

seqcli feed list
Option Description
-n, --name=VALUE The name of the feed to list
-i, --id=VALUE The id of a single feed to list
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

feed remove

Remove a NuGet feed from the server.

Example:

seqcli feed remove -n CI
Option Description
-n, --name=VALUE The name of the feed to remove
-i, --id=VALUE The id of a single feed to remove
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

help

Show information about available commands.

Example:

seqcli help search
Option Description
-m, --markdown Generate markdown for use in documentation

ingest

Send log events from a file or STDIN.

Example:

seqcli ingest -i log-*.txt --json --filter="@Level <> 'Debug'" -p Environment=Test
Option Description
-i, --input=VALUE File(s) to ingest, including the * wildcard; if not specified, STDIN will be used
--invalid-data=VALUE Specify how invalid data is handled: fail (default) or ignore
-p, --property=NAME=VALUE Specify name/value properties, e.g. -p Customer=C123 -p Environment=Production
-x, --extract=VALUE An extraction pattern to apply to plain-text logs (ignored when --json is specified)
--json Read the events as JSON (the default assumes plain text)
-f, --filter=VALUE Filter expression to select a subset of events
-m, --message=VALUE A message to associate with the ingested events; https://messagetemplates.org syntax is supported
-l, --level=VALUE The level or severity to associate with the ingested events; this will override any level information present in the events themselves
--send-failure=VALUE Specify how connection failures are handled: fail (default), retry, continue, or ignore
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used
--batch-size=VALUE The maximum number of events to send in each request to the ingestion endpoint; if not specified a value of 100 will be used

license apply

Apply a license to the Seq server.

Example:

seqcli license apply --certificate="license.txt"
Option Description
-c, --certificate=VALUE Certificate file; the file must be UTF-8 text
--certificate-stdin Read the license certificate from STDIN
--automatically-refresh If the license is for a subscription, periodically check datalust.co and automatically refresh the certificate when the subscription is changed or renewed
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

log

Send a structured log event to the server.

Example:

seqcli log -m 'Hello, {Name}!' -p Name=World -p App=Test
Option Description
-m, --message=VALUE A message to associate with the event (the default is to send no message); https://messagetemplates.org syntax is supported
-l, --level=VALUE The level or severity of the event (the default is Information)
-t, --timestamp=VALUE The event timestamp as ISO-8601 (the current UTC timestamp will be used by default)
-x, --exception=VALUE Additional exception or error information to send, if any
-p, --property=NAME=VALUE Specify name/value properties, e.g. -p Customer=C123 -p Environment=Production
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

node demote

Begin demotion of the current leader node.

Example:

seqcli node demote --verbose --wait
Option Description
--wait Wait for the leader to be demoted before exiting
-y, --confirm Answer [y]es when prompted to continue
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

node health

Probe a Seq node's /health endpoint, and print the returned HTTP status code, or 'Unreachable' if the endpoint could not be queried.

Example:

seqcli node health -s https://seq-2.example.com
Option Description
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

node list

List nodes in the Seq cluster.

Example:

seqcli node list --json
Option Description
-n, --name=VALUE The name of the cluster node to list
-i, --id=VALUE The id of a single cluster node to list
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

print

Pretty-print events in CLEF/JSON format, from a file or STDIN.

Example:

seqcli print -i log-20201028.clef
Option Description
-i, --input=VALUE CLEF file to read, including the * wildcard; if not specified, STDIN will be used
-f, --filter=VALUE Filter expression to select a subset of events
--template=VALUE Specify an output template to control plain text formatting
--invalid-data=VALUE Specify how invalid data is handled: fail (default) or ignore
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)

profile create

Create or replace a connection profile.

Example:

seqcli profile create -n Production -s https://seq.example.com -a th15ISanAPIk3y
Option Description
-n, --name=VALUE The name of the connection profile
-s, --server=VALUE The URL of the Seq server
-a, --apikey=VALUE The API key to use when connecting to the server, if required

profile list

List connection profiles.

Example:

seqcli profile list

profile remove

Remove a connection profile.

Example:

seqcli profile remove -n Production
Option Description
-n, --name=VALUE The name of the connection profile to remove

query

Execute an SQL query and receive results in CSV format.

Example:

seqcli query -q "select count(*) from stream group by @Level" --start="2018-02-28T13:00Z"
Option Description
-q, --query=VALUE The query to execute
--start=VALUE ISO 8601 date/time to query from
--end=VALUE ISO 8601 date/time to query to
--signal=VALUE A signal expression or list of intersected signal ids to apply, for example signal-1,signal-2
--timeout=VALUE The execution timeout in milliseconds
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

retention create

Create a retention policy.

Example:

seqcli retention create --after 30d --delete-all-events
Option Description
--after=VALUE A duration after which the policy will delete events, e.g. 7d
--delete-all-events The policy should delete all events (currently the only supported option)
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)

retention list

List retention policies.

Example:

seqcli retention list
Option Description
-i, --id=VALUE The id of a single retention policy to list
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

retention remove

Remove a retention policy from the server.

Example:

seqcli retention remove -i retentionpolicy-17
Option Description
-i, --id=VALUE The id of a single retention policy to remove
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

sample ingest

Log sample events into a Seq instance.

Example:

seqcli sample ingest
Option Description
-y, --confirm Answer [y]es when prompted to continue
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used
--quiet Don't echo ingested events to STDOUT
--batch-size=VALUE The maximum number of events to send in each request to the ingestion endpoint; if not specified a value of 100 will be used

sample setup

Configure a Seq instance with sample dashboards, signals, users, and so on.

Example:

seqcli sample setup
Option Description
-y, --confirm Answer [y]es when prompted to continue
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

search

Retrieve log events that match a given filter.

Example:

seqcli search -f "@Exception like '%TimeoutException%'" -c 30
Option Description
-f, --filter=VALUE A filter to apply to the search, for example Host = 'xmpweb-01.example.com'
-c, --count=VALUE The maximum number of events to retrieve; the default is 1
--start=VALUE ISO 8601 date/time to query from
--end=VALUE ISO 8601 date/time to query to
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
--signal=VALUE A signal expression or list of intersected signal ids to apply, for example signal-1,signal-2
--request-timeout=VALUE The time allowed for retrieving each page of events, in milliseconds; the default is 100000
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

signal create

Create a signal.

Example:

seqcli signal create -t 'Exceptions' -f "@Exception is not null"
Option Description
-t, --title=VALUE A title for the signal
--description=VALUE A description for the signal
-f, --filter=VALUE Filter to associate with the signal
-c, --column=VALUE Column to associate with the signal; this argument can be used multiple times
--group=VALUE An explicit group name to associate with the signal; the default is to infer the group from the filter
--no-group Specify that no group should be inferred; the default is to infer the group from the filter
--protected Specify that the signal is editable only by administrators
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)

signal import

Import signals in newline-delimited JSON format.

Example:

seqcli signal import -i ./Exceptions.json
Option Description
--merge Update signals that have ids matching those in the imported data; the default is to always create new signals
-i, --input=VALUE File to import; if not specified, STDIN will be used
-o, --owner=VALUE The id of the user to import signals for; by default, shared signals are importd
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

signal list

List available signals.

Example:

seqcli signal list
Option Description
-t, --title=VALUE The title of the signal(s) to list
-i, --id=VALUE The id of a single signal to list
-o, --owner=VALUE The id of the user to list signals for; by default, shared signals are listd
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

signal remove

Remove a signal from the server.

Example:

seqcli signal remove -t 'Test Signal'
Option Description
-t, --title=VALUE The title of the signal(s) to remove
-i, --id=VALUE The id of a single signal to remove
-o, --owner=VALUE The id of the user to remove signals for; by default, shared signals are removd
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

tail

Stream log events matching a filter.

Option Description
-f, --filter=VALUE An optional server-side filter to apply to the stream, for example @Level = 'Error'
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
--signal=VALUE A signal expression or list of intersected signal ids to apply, for example signal-1,signal-2
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

template export

Export entities into template files.

Example:

seqcli template export -o ./Templates
Option Description
-o, --output=VALUE The directory in which to write template files; the directory must exist; any existing files with names matching the exported templates will be overwritten; the default is .
-i, --include=VALUE The id of a signal, dashboard, saved query, workspace, or retention policy to export; this argument may be specified multiple times; the default is to export all shared entities
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

template import

Import entities from template files.

Example:

seqcli template import -i ./Templates
Option Description
-i, --input=VALUE The directory from which to read the set of .template files; the default is .
--state=VALUE The path of a file which will persist a mapping of template names to the ids of the created entities on the target server, avoiding duplicates when multiple imports are performed; by default, import.state in the input directory will be used
--merge For templates with no entries in the .state file, first check for existing entities with matching names or titles; does not support merging of retention policies
-g, --arg=NAME=VALUE Template arguments, e.g. -g ownerId=user-314159
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

user create

Create a user.

Example:

seqcli user create -n alice -d 'Alice Example' -r 'User (read/write)' --password-stdin
Option Description
-n, --name=VALUE A unique username for the user
-d, --display-name=VALUE A long-form name to aid in identifying the user
-f, --filter=VALUE A view filter that limits the events visible to the user
-r, --role=VALUE The title of a role that grants the user permissions on the server; if not specified, the default new user role will be assigned
-e, --email=VALUE The user's email address (enables a Gravatar image for the user)
-p, --password=VALUE An initial password for the user, if username/password authentication is in use; note that --password-stdin is more secure
--password-stdin Read the initial password for the user from STDIN, if username/password authentication is in use
--no-password-change Don't force the user to change their password at next login
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)

user list

List users.

Example:

seqcli user list
Option Description
-n, --name=VALUE The username of the user(s) to list
-i, --id=VALUE The id of a single user to list
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

user remove

Remove a user from the server.

Example:

seqcli user remove -n alice
Option Description
-n, --name=VALUE The username of the user(s) to remove
-i, --id=VALUE The id of a single user to remove
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

version

Print the current executable version.

workspace create

Create a workspace.

Example:

seqcli workspace create -t 'My Workspace' -c signal-314159 -c dashboard-628318
Option Description
-t, --title=VALUE A title for the workspace
--description=VALUE A description for the workspace
-c, --content=VALUE The id of a dashboard, signal, or saved query to include in the workspace
--protected Specify that the workspace is editable only by administrators
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)

workspace list

List available workspaces.

Example:

seqcli workspace list
Option Description
-t, --title=VALUE The title of the workspace(s) to list
-i, --id=VALUE The id of a single workspace to list
-o, --owner=VALUE The id of the user to list workspaces for; by default, shared workspaces are listd
--json Print output in newline-delimited JSON (the default is plain text)
--no-color Don't colorize text output
--force-color Force redirected output to have ANSI color (unless --no-color is also specified)
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

workspace remove

Remove a workspace from the server.

Example:

seqcli workspace remove -t 'My Workspace'
Option Description
-t, --title=VALUE The title of the workspace(s) to remove
-i, --id=VALUE The id of a single workspace to remove
-o, --owner=VALUE The id of the user to remove workspaces for; by default, shared workspaces are removd
-s, --server=VALUE The URL of the Seq server; by default the connection.serverUrl config value will be used
-a, --apikey=VALUE The API key to use when connecting to the server; by default the connection.apiKey config value will be used
--profile=VALUE A connection profile to use; by default the connection.serverUrl and connection.apiKey config values will be used

Extraction patterns

The seqcli ingest command can be used for parsing plain text logs into structured log events.

seqcli ingest -x "{@t:timestamp} [{@l:level}] {@m:*}{:n}{@x:*}"

The -x argument above is an extraction pattern that will parse events like:

2018-02-21 13:29:00.123 +10:00 [ERR] The operation failed
System.DivideByZeroException: Attempt to divide by zero
  at SomeClass.SomeMethod()

Syntax

Extraction patterns have a simple high-level syntax:

  • Text that appears in the pattern is matched literally - so a pattern like Hello, world! will match logging statements that are made up of this greeting only,
  • Text between {curly braces} is a match expression that identifies a part of the event to be extracted, and
  • Literal curly braces are escaped by doubling, so {{ will match the literal text {, and }} matches }.

Match expressions have the form:

{name:matcher}

Both the name and matcher are optional, but either one or the other must be specified. Hence {@t:timestamp} specifies a name of @t and value timestamp, {IPAddress} specifies a name only, and {:n} a value only (in this case the built-in newline matcher).

The name is the property name to be extracted; there are four built-in property names that get special handling:

  • @t - the event's timestamp
  • @m - the textual message associated with the event
  • @l - the event's level
  • @x - the exception or backtrace associated with the event

Other property names are attached to the event payload, so {Elapsed:dec} will extract a property called Elapsed, using the dec decimal matcher.

Match expressions with no name are consumed from the input, but are not added to the event payload.

Matchers

Matchers identify chunks of the input event.

Different matchers are needed so that a piece of text like 200OK can be separated into separate properties, i.e. {StatusCode:nat}{Status:alpha}. Here, the nat (natural number) matcher also coerces the result into a numeric value, so that it is attached to the event payload numerically as 200 instead of as the text "200".

There are three kinds of matchers:

  • Matchers like alpha and nat are built-in named matchers.
  • The special matchers *, ** and so-on, are non-greedy content matchers; these will match any text up until the next pattern element matches (*), the next two elements match, and so-on. We saw this in action with the {@m:*}{:n} elements in the example - the message is all of the text up until the next newline.
  • More complex compound matchers are described using a sub-expression. These are prefixed with an equals sign =, like {Phone:={:nat}-{:nat}-{:nat}}. This will extract chunks of text like 123-456-7890 into the Phone property.
Matcher Description Example
*, **, ... Non-greedy content
alpha One or more letters Abc
alphanum One or more letters or numbers a1b2
dec A decimal number 12.345
ident A C-style identifier countOfMatches
int An integer -123
iso8601dt An ISO-8601 date-time 2020-01-28T13:50:01.123
level A logging level name INF
line Any single-line content one line!
n A newline character or sequence
nat A nonnegative number 123
s One or more space or tab characters
serilogdt A datetime in the default Serilog file logging format 2020-01-28 13:50:01.123 +10:00
syslogdt A datetime in syslog format Dec 8 09:12:13
t A single tab character
timestamp A datetime in any recognized format
token Any sequence of non-whitespace characters 1+x$3
trailingident Multiline content with indented trailing lines
unixdt A datetime in Unix time format supporting seconds (10-digit) or milliseconds (12-digit) 1608694199.999
w3cdt A W3C log format date/time pair 2019-04-02 05:18:01

Processing

Extraction patterns are processed from left to right. When the first non-matching pattern is encountered, extraction stops; any remaining text that couldn't be matched will be attached to the resulting event in an @unmatched property.

Multi-line events are handled by looking for lines that start with the first element of the extraction pattern to be used. This works well if the first line of each event begins with something unambiguous like an iso8601dt timestamp; if the lines begin with less specific syntax, the first few elements of the extraction pattern might be grouped to identify the start of events more accurately:

{:=[{@t} {@l}]} {@m:*}

Here the literal text [, a timestamp token, adjacent space , level and closing ] are all grouped so that they constitute a single logical pattern element to identify the start of events.

When logs are streamed into seqcli ingest in real time, a 10 ms deadline is applied, within which any trailing lines that make up the event must be received.

Examples

Tail systemd logs

journalctl -f -n 0 |
  seqcli ingest -x "{@t:syslogdt} {host} {ident:*}: {@m:*}{:n}" --invalid-data=ignore

Tail /var/log/syslog

tail -c 0 -F /var/log/syslog |
  seqcli ingest -x "{@t:syslogdt} {host} {ident:*}: {@m:*}{:n}"

Ingest an IIS/W3C web server log

This example ingests log files in the format:

#Fields: date time s-ip cs-method cs-uri-stem cs-uri-query s-port cs-username c-ip cs(User-Agent) 
cs(Referer) sc-status sc-substatus sc-win32-status sc-bytes cs-bytes time-taken

The extraction pattern is wrapped in the example for display purposes, and must appear all in one string argument when invoked.

seqcli ingest -i http.log --invalid-data=ignore -x "{@t:w3cdt} {ServerIP} {@m:={Method} {RequestPath}} 
{Query} {Port:nat} {Username} {ClientIP} {UserAgent} {Referer} {StatusCode:nat} {Substatus:nat} 
{Win32Status:nat} {ResponseBytes:nat} {RequestBytes:nat} {Elapsed}{:n}"

A nested {@m:= pattern is used to collect a substring of the log line for display as the event's message.

More Repositories

1

superpower

A C# parser construction toolkit with high-quality error reporting
C#
1,064
star
2

serilog-sinks-seq

A Serilog sink that writes events to the Seq structured log server
C#
185
star
3

dotnet6-serilog-example

A sample project showing Serilog configured in the default .NET 6 web application template
C#
182
star
4

clef-tool

A command-line tool for manipulating Compact Log Event Format files
C#
98
star
5

seq-tickets

Issues, design discussions and feature roadmap for the Seq log server
91
star
6

piggy

A friendly PostgreSQL script runner in the spirit of DbUp.
C#
75
star
7

seq-extensions-logging

Add centralized log collection to ASP.NET Core apps with one line of code.
C#
74
star
8

serilog-middleware-example

An example ASP.NET Core app with smart request logging middleware
C#
74
star
9

seq-api

HTTP API client for Seq
C#
71
star
10

squirrel-json

A vectorized JSON parser for pre-validated, minified documents
Rust
70
star
11

seq-cheat-sheets

Cheat sheets for Seq filtering and querying syntax
64
star
12

seq-forwarder

Local collection and reliable forwarding of log data to Seq
C#
52
star
13

seq-app-htmlemail

Plug-in apps that act on event streams in the Seq log server
C#
49
star
14

seq-input-healthcheck

Periodically GET an HTTP resource and write response metrics to Seq
C#
24
star
15

seq-client-log4net

A log4net appender that writes events to Seq
C#
24
star
16

seq-logging

A Node.js client for the Seq HTTP ingestion API
JavaScript
19
star
17

nlog-targets-seq

An NLog target that writes events to Seq. Built for NLog 4.5+.
C#
16
star
18

seq-input-gelf

Ingest GELF payloads into Seq
Rust
14
star
19

bunyan-seq

A Bunyan stream to send events to Seq
JavaScript
11
star
20

seq-import

A CLI tool for importing JSON-formatted log files directly into Seq
C#
10
star
21

winston-seq

A Winston v3 transport for Seq
TypeScript
10
star
22

pino-seq

A stream to send Pino events to Seq
JavaScript
9
star
23

squiflog

Ingest Syslog payloads into Seq
Rust
7
star
24

seq-input-rabbitmq

A Seq custom input that pulls events from RabbitMQ
C#
7
star
25

seq-docker-windows

Windows Dockerfile for Seq
PowerShell
6
star
26

seq-app-jsonarchive

Record events to a set of newline-delimited JSON streams
Rust
6
star
27

seq-app-httprequest

Send events and notifications to an HTTP/REST/WebHook endpoint.
C#
6
star
28

helm.datalust.co

Helm charts hosted on helm.datalust.co
Mustache
4
star
29

seq-client-portable

A portable (WP/iOS/Android) sink for Serilog that writes events over HTTP/S to Seq
C#
3
star
30

seq-app-opsgenie

Create Opsgenie alerts in response to events or notifications in Seq
C#
3
star
31

seq-app-digestemail

Batched HTML email integration
C#
2
star
32

seq-app-replication

Seq.App.Replication - forward incoming events to another Seq server
C#
2
star
33

express-pino-seq

An example Node.js Express app using `pino` logger together with `pino-seq`
JavaScript
2
star
34

seq-apps-runtime

The Seq app hosting interfaces published as the Seq.Apps NuGet package
C#
2
star
35

seq-app-valuelist

An example Seq app that tracks which values appear in a particular event property
C#
1
star
36

seq-app-thresholds

Seq.App.Thresholds
C#
1
star