Logs - AppSignal Documentation

The logs commands bring your application logs into the terminal: tail them as they arrive, search across a time range, and manage the log-derived metrics and log-based triggers built from them.

Common options

Every logs command identifies one application, and uses your default organization unless you tell it otherwise:

Flag	Description
`--app <name>`	Application name (add `--environment` when more than one app shares the name)
`--environment <env>`	Environment, used with `--app`
`--app-id <id>`	The app’s ID (a long hexadecimal string from `appsignal-cli apps list`), instead of `--app` and `--environment`
`--org <slug>`	Organization slug (uses your default if omitted)

Tail logs

Stream log lines as they arrive (the CLI polls every second):

Shell

appsignal-cli logs tail --app "MyApp" --environment production

Search logs

Search past log lines and print the matches. For example, find recent error-level lines:

Shell

appsignal-cli logs search --app "MyApp" --environment production --query "severity:error"

By default, search returns up to 100 of the most recent matches. On top of the common options and filters, it adds:

Flag	Description
`--start <ISO8601>`	Start time, e.g. `2025-01-01T00:00:00Z`
`--end <ISO8601>`	End time
`--limit <N>`	Maximum lines to return (max 100, also the default)
`--order <ORDER>`	`ASC` (oldest first) or `DESC` (newest first, the default)
`--page-all`	Fetch every matching line in the range. Requires `--start`, and ignores `--limit` and `--order`

To pull every line in a window as JSON, for a script or agent:

Shell

appsignal-cli --output json logs search --app "MyApp" --environment production \
  --start "2025-01-01T00:00:00Z" --query "severity:error" --page-all

Filters

tail and search share these filters:

Flag	Description
`--query <text>`	Log query filter, using AppSignal’s query syntax
`--severities <list>`	Comma-separated severities, e.g. `ERROR,CRITICAL`
`--source-ids <list>`	Comma-separated source IDs
`--view <name-or-id>`	Apply a saved log view’s filters as defaults

List the views available for an app with appsignal-cli logs views, then pass one to --view by name or ID. --query and --source-ids replace the view’s saved values, and --severities narrows the view’s query. For example, apply a view but narrow it to critical lines:

Shell

appsignal-cli logs search --app "MyApp" --environment production \
  --view "Production errors" --severities CRITICAL

Query syntax

The --query flag uses AppSignal’s log query syntax. Common patterns:

severity=error: exact field match
message:timeout: message contains “timeout”
group=notifiers: exact group match
hostname:web-1: hostname contains “web-1”
Space-separated terms combine with AND; use OR for alternatives

Square brackets have special meaning in the parser, so quote them to match literally: message:"[Email]".

Structured metadata

tail and search include the structured metadata on each log line, such as a request ID or user ID:

Human-readable output adds the fields to the end of the line as [key=value ...].
JSON output puts them in a json object on each line, and each value keeps its JSON type. Metadata that a logger sends as plain text appears under a raw key.

Use JSON output when a script or agent needs to read the metadata. You can also filter on metadata fields in --query, including nested fields written with dots. See nested attributes in the query syntax reference.

Shell

appsignal-cli --output json logs search --app "MyApp" --environment production \
  --query "request_id=abc123 user.id=42"

Saved views and sources

List an app’s saved log views (filter presets) and its log sources:

Shell

appsignal-cli logs views --app "MyApp" --environment production
appsignal-cli logs sources --app "MyApp" --environment production

Pass a view’s name or ID to --view, and a source’s ID to --source-ids.

Log-derived metrics

logs metrics turns matching log lines into metrics, with list, create, update, and delete:

Shell

appsignal-cli logs metrics create --app "MyApp" --environment production \
  --name "Checkout latency" \
  --query "group:checkout" \
  --metric "name=log.checkout_duration_ms,type=distribution,field=duration_ms" \
  --source-id <SOURCE_ID>

create and update share these flags (create requires --name, --query, and at least one --metric):

Flag	Description
`--name <name>`	Metric configuration name
`--query <text>`	Query matching the log lines to measure
`--metric <def>`	Metric definition in `key=value` form (repeat for multiple), e.g. `name=log.error_count,type=counter`
`--source-id <id>`	Scope to a source ID (repeat for more)

update can take the following additional flags. The --clear-* flags empty fields instead of updating them.

Flag	Description
`--id <id>`	The metric to update, from `logs metrics list` (required)
`--clear-metrics`	Remove all metric definitions
`--clear-sources`	Remove all source scoping

delete takes only --id.

A log-derived metric only starts collecting data once it’s scoped to a log source, so pass --source-id (find IDs with appsignal-cli logs sources). The CLI can’t set a metric’s severity filter; if your metric needs one, set the Severity field in the AppSignal app UI after creating it.

Log-based triggers

logs triggers alerts on matching log lines, with list, create, update, and delete:

Shell

appsignal-cli logs triggers create --app "MyApp" --environment production \
  --name "Root login" \
  --query "message:root" \
  --severity ERROR \
  --notifier-id <NOTIFIER_ID>

create and update share these flags (create requires --name and --query):

Flag	Description
`--name <name>`	Trigger name
`--query <text>`	Query matching the log lines to alert on
`--severity <level>`	Match only these severities (repeat for more). Added to the query as `severity=[...]`. On `update`, requires `--query`
`--notifier-id <id>`	Attach a notifier (repeat for more)
`--source-id <id>`	Scope to a source ID (repeat for more)
`--description <text>`	Trigger description

update can take the following additional flags. The --clear-* flags empty fields instead of updating them.

Flag	Description
`--id <id>`	The trigger to update, from `logs triggers list` (required)
`--clear-description`	Remove the description
`--clear-notifiers`	Remove all notifiers
`--clear-sources`	Remove all source scoping

delete takes only --id.

These are log-based triggers, built from log lines. For anomaly detection triggers on metrics, see Triggers.

Next steps

Found something in the logs? Open the related incidents, or set up anomaly detection triggers.

​Common options

​Tail logs

​Search logs

​Filters

​Query syntax

​Structured metadata

​Saved views and sources

​Log-derived metrics

​Log-based triggers

​Next steps

Common options

Tail logs

Search logs

Filters

Query syntax

Structured metadata

Saved views and sources

Log-derived metrics

Log-based triggers

Next steps