Awesome

seqcli

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.

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.

Environment variable overrides

Each setting value can be overridden at runtime by specifying an environment variable of the form SEQCLI_<setting path>, where <setting path> contains one element for each dotted segment of the setting name, separated by underscores.

For example the setting connection.serverUrl can overridden with the SEQCLI_CONNECTION_SERVERURL variable.

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.

Permissions

When connecting with an API key the allowed operations are determined by the permissions assigned to that API key.

To determine the permission required for a command check the 'Permission demand' column of the equivalent server API operation. For example, the command apikey create uses the POST api/apikeys endpoint, which requires the Write permission.

Usage

All seqcli commands follow the same pattern:

seqcli <command> [<args>]

Command help

The complete list of supported commands can be viewed by running:

seqcli help

To show usage information for a specific command, run seqcli help <command>, for example:

seqcli help apikey create

This also works for command groups; to list all apikey sub-commands, run:

seqcli help apikey

Available commands

• apikey
  • apikey create — Create an API key for automation or ingestion.
  • apikey list — List available API keys.
  • apikey remove — Remove an API key from the server.
  • apikey update — Update an existing API key.
• app
  • app define — Generate an app definition for a .NET [SeqApp] plug-in.
  • app install — Install an app package.
  • app list — List installed app packages.
  • app run — Host a .NET [SeqApp] plug-in.
  • app uninstall — Uninstall an app package.
  • app update — Update an installed app package.
• appinstance
  • appinstance create — Create an instance of an installed app.
  • appinstance list — List instances of installed apps.
  • appinstance remove — Remove an app instance from the server.
  • appinstance update — Update an existing app instance.
• bench — Measure query performance.
• config — View and set fields in the SeqCli.json file; run with no arguments to list all fields.
• dashboard
  • dashboard list — List dashboards.
  • dashboard remove — Remove a dashboard from the server.
  • dashboard render — Produce a CSV or JSON result set from a dashboard chart.
• expressionindex
  • expressionindex create — Create an expression index.
  • expressionindex list — List expression indexes.
  • expressionindex remove — Remove an expression index from the server.
• feed
  • feed create — Create a NuGet feed.
  • feed list — List NuGet feeds.
  • feed remove — Remove a NuGet feed from the server.
  • feed update — Update an existing NuGet feed.
• help — Show information about available commands.
• index
  • index list — List indexes.
  • index suppress — Suppress an index.
• 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
  • profile create — Create or replace a connection profile.
  • profile list — List connection profiles.
  • profile remove — Remove a connection profile.
• query — Execute an SQL query and receive results in CSV format.
• retention
  • retention create — Create a retention policy.
  • retention list — List retention policies.
  • retention remove — Remove a retention policy from the server.
  • retention update — Update an existing retention policy.
• 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.
• setting
  • setting clear — Clear a runtime-configurable server setting.
  • setting names — Print the names of all supported settings.
  • setting set — Change a runtime-configurable server setting.
  • setting show — Print the current value of a runtime-configurable server setting.
• signal
  • signal create — Create a signal.
  • signal import — Import signals in newline-delimited JSON format.
  • signal list — List available signals.
  • signal remove — Remove a signal from the server.
  • signal update — Update an existing signal.
• tail — Stream log events matching a filter.
• template
  • template export — Export entities into template files.
  • template import — Import entities from template files.
• user
  • user create — Create a user.
  • user list — List users.
  • user remove — Remove a user from the server.
  • user update — Update an existing user.
• version — Print the current executable version.
• workspace
  • workspace create — Create a workspace.
  • workspace list — List available workspaces.
  • workspace remove — Remove a workspace from the server.
  • workspace update — Update an existing workspace.

apikey create

Create an API key for automation or ingestion.

Example:

seqcli apikey create -t 'Test API Key' -p Environment=Test

apikey list

List available API keys.

Example:

seqcli apikey list

apikey remove

Remove an API key from the server.

Example:

seqcli apikey remove -t 'Test API Key'

apikey update

Update an existing API key.

Example:

seqcli apikey update --json '{...}'

app define

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

Example:

seqcli app define -d "./bin/Debug/netstandard2.2"

app install

Install an app package.

Example:

seqcli app install --package-id 'Seq.App.JsonArchive'

app list

List installed app packages.

Example:

seqcli app list

app run

Host a .NET [SeqApp] plug-in.

Example:

seqcli tail --json | seqcli app run -d "./bin/Debug/netstandard2.2" -p ToAddress=example@example.com

app uninstall

Uninstall an app package.

Example:

seqcli app uninstall --package-id 'Seq.App.JsonArchive'

app update

Update an installed app package.

Example:

seqcli app update -n 'HTML Email'

appinstance create

Create an instance of an installed app.

Example:

seqcli appinstance create -t 'Email Ops' --app hostedapp-314159 -p To=ops@example.com

appinstance list

List instances of installed apps.

Example:

seqcli appinstance list

appinstance remove

Remove an app instance from the server.

Example:

seqcli appinstance remove -t 'Email Ops'

appinstance update

Update an existing app instance.

Example:

seqcli appinstance update --json '{...}'

bench

Measure query performance.

config

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

dashboard list

List dashboards.

Example:

seqcli dashboard list

dashboard remove

Remove a dashboard from the server.

Example:

seqcli dashboard remove -i dashboard-159

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

expressionindex create

Create an expression index.

Example:

seqcli expressionindex create --expression "ServerName"

expressionindex list

List expression indexes.

Example:

seqcli expressionindex list

expressionindex remove

Remove an expression index from the server.

Example:

seqcli expressionindex -i expressionindex-2529

feed create

Create a NuGet feed.

Example:

seqcli feed create -n 'CI' --location="https://f.feedz.io/example/ci" -u Seq --password-stdin

feed list

List NuGet feeds.

Example:

seqcli feed list

feed remove

Remove a NuGet feed from the server.

Example:

seqcli feed remove -n CI

feed update

Update an existing NuGet feed.

Example:

seqcli feed update --json '{...}'

help

Show information about available commands.

Example:

seqcli help search

index list

List indexes.

Example:

seqcli index list

index suppress

Suppress an index.

Example:

seqcli index suppress -i index-2191448f1d9b4f22bd32c6edef752748

ingest

Send log events from a file or STDIN.

Example:

seqcli ingest -i log-*.txt --json --filter="@Level <> 'Debug'" -p Environment=Test

license apply

Apply a license to the Seq server.

Example:

seqcli license apply --certificate="license.txt"

log

Send a structured log event to the server.

Example:

seqcli log -m 'Hello, {Name}!' -p Name=World -p App=Test

node demote

Begin demotion of the current leader node.

Example:

seqcli node demote --verbose --wait

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

node list

List nodes in the Seq cluster.

Example:

seqcli node list --json

print

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

Example:

seqcli print -i log-20201028.clef

profile create

Create or replace a connection profile.

Example:

seqcli profile create -n Production -s https://seq.example.com -a th15ISanAPIk3y

profile list

List connection profiles.

Example:

seqcli profile list

profile remove

Remove a connection profile.

Example:

seqcli profile remove -n Production

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"

retention create

Create a retention policy.

Example:

seqcli retention create --after 30d --delete-all-events

retention list

List retention policies.

Example:

seqcli retention list

retention remove

Remove a retention policy from the server.

Example:

seqcli retention remove -i retentionpolicy-17

retention update

Update an existing retention policy.

Example:

seqcli retention update --json '{...}'

sample ingest

Log sample events into a Seq instance.

Example:

seqcli sample ingest

sample setup

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

Example:

seqcli sample setup

search

Retrieve log events that match a given filter.

Example:

seqcli search -f "@Exception like '%TimeoutException%'" -c 30

setting clear

Clear a runtime-configurable server setting.

setting names

Print the names of all supported settings.

setting set

Change a runtime-configurable server setting.

setting show

Print the current value of a runtime-configurable server setting.

signal create

Create a signal.

Example:

seqcli signal create -t 'Exceptions' -f "@Exception is not null"

signal import

Import signals in newline-delimited JSON format.

Example:

seqcli signal import -i ./Exceptions.json

signal list

List available signals.

Example:

seqcli signal list

signal remove

Remove a signal from the server.

Example:

seqcli signal remove -t 'Test Signal'

signal update

Update an existing signal.

Example:

seqcli signal update --json '{...}'

tail

Stream log events matching a filter.

template export

Export entities into template files.

Example:

seqcli template export -o ./Templates

template import

Import entities from template files.

Example:

seqcli template import -i ./Templates

user create

Create a user.

Example:

seqcli user create -n alice -d 'Alice Example' -r 'User (read/write)' --password-stdin

user list

List users.

Example:

seqcli user list

user remove

Remove a user from the server.

Example:

seqcli user remove -n alice

user update

Update an existing user.

Example:

seqcli user update --json '{...}'

version

Print the current executable version.

workspace create

Create a workspace.

Example:

seqcli workspace create -t 'My Workspace' -c signal-314159 -c dashboard-628318

workspace list

List available workspaces.

Example:

seqcli workspace list

workspace remove

Remove a workspace from the server.

Example:

seqcli workspace remove -t 'My Workspace'

workspace update

Update an existing workspace.

Example:

seqcli workspace update --json '{...}'

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.

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.

Updating entities

The seqcli * update family of commands make it possible to perform arbitrary updates to many complex entity types.

The update commands, like seqcli signal update shown in the example below, receive an updated JSON representation of an entity via STDIN.

This works particularly well with tools like jq and modern shells with native JSON support, such as PowerShell:

PS > $warnings = (seqcli signal list -i signal-m33302 --json | ConvertFrom-Json)

PS > $warnings.Title                                                                                                                
Warnings

PS > $warnings.Title = "Alarms"

PS > (echo $warnings | ConvertTo-Json) | seqcli signal update --json-stdin        

PS > seqcli signal list -i signal-m33302 --json                                 
{"Title": "Alarms", "Description": "Automatically created", "Filters": [{"De...