> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Logs

> Tail and search application logs from the terminal, and manage log-derived metrics and log-based triggers.

The `logs` command 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.

<h2 id="common-options">
  Common options
</h2>

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) |

<h2 id="tail-logs">
  Tail logs
</h2>

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

```sh Shell theme={null}
appsignal-cli logs tail --app "MyApp" --environment production
```

<h2 id="search-logs">
  Search logs
</h2>

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

```sh Shell theme={null}
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:

```sh Shell theme={null}
appsignal-cli --output json logs search --app "MyApp" --environment production \
  --start "2025-01-01T00:00:00Z" --query "severity:error" --page-all
```

<h2 id="filters">
  Filters
</h2>

`tail` and `search` share these filters:

| Flag | Description |
| - | - |
| `--query <text>` | Log query filter, using AppSignal's [query syntax](/logging/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. Any other filters you add override the view's saved defaults. For example, apply a view but narrow it to critical lines:

```sh Shell theme={null}
appsignal-cli logs search --app "MyApp" --environment production \
  --view "Production errors" --severities CRITICAL
```

<h3 id="query-syntax">
  Query syntax
</h3>

The `--query` flag uses AppSignal's [log query syntax](/logging/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]"`.

<h2 id="saved-views-and-sources">
  Saved views and sources
</h2>

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

```sh Shell theme={null}
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`.

<h2 id="log-derived-metrics">
  Log-derived metrics
</h2>

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

```sh Shell theme={null}
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`.

<Note>
  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.
</Note>

<h2 id="log-based-triggers">
  Log-based triggers
</h2>

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

```sh Shell theme={null}
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) |
| `--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-severities` | Remove all severities |
| `--clear-sources` | Remove all source scoping |

`delete` takes only `--id`.

<Note>
  These are log-based triggers, built from log lines. For anomaly detection triggers on metrics, see [Triggers](/cli/triggers).
</Note>

<h2 id="next-steps">
  Next steps
</h2>

Found something in the logs? Open the related [incidents](/cli/incidents), or set up [anomaly detection triggers](/cli/triggers).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.