> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fjall.io/llms.txt
> Use this file to discover all available pages before exploring further.
# fjall metrics
> View application performance metrics for your AWS resources with the Fjall CLI, as JSON or agent-readable output.
`fjall metrics` reads application performance metrics from the Fjall control plane. It calls `GET /api/app-metrics` and prints the rows. It never calls AWS directly.
| Requirement | How to satisfy it |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authenticated CLI | Run `fjall login`, or set `FJALL_API_KEY` for CI. Credentials live at `~/.fjall/auth.json` (or `$FJALL_CONFIG_DIR/auth.json`). |
| Token with `read` scope | Personal tokens from `fjall token create` and CI tokens minted in the web app under Settings, CI/CD Tokens both carry scopes. The route rejects a token without `read`. |
| At least one application | Metrics rows are keyed by application. Create one with `fjall create application` and deploy it with `fjall deploy `. |
| Node 22 or later | The `fjall` package declares `"node": ">=22.0.0"`. |
Metrics come from Fjall's monitoring pipeline, so an application that has never been deployed returns no rows.
## View application metrics
```bash theme={null}
fjall metrics [subcommand] [options]
```
`show` is the only subcommand, and it is also the fallback when the positional is omitted. `fjall metrics` and `fjall metrics show` run the same code path.
```bash theme={null}
# Current sample for every application in the organisation
fjall metrics show --mode latest
# Hourly request, error and latency buckets for the last 24 hours
fjall metrics show --mode sparklines --hours 24
# Every sample across the organisation for the last week
fjall metrics show --mode org_summary --hours 168 --limit 500
```
Any other positional is rejected:
```text theme={null}
Error: Unknown subcommand 'requests'
Available subcommands: show
```
### metrics show
```bash theme={null}
fjall metrics show [options]
```
`--mode` selects which query runs on the server. The four accepted values behave differently:
| Mode | Returns | Uses `--app` | Uses `--hours` | Uses `--limit` |
| ------------- | ------------------------------------------------------------------------- | --------------- | -------------- | -------------- |
| `latest` | The most recent sample per application, taken from a fixed 48 hour window | Optional filter | No | No |
| `time_series` | Per-sample rows for one application, oldest first | Required | Yes | Yes |
| `sparklines` | Hourly request, error and latency buckets per application | Optional filter | Yes | No |
| `org_summary` | Every sample across the organisation, newest first | No | Yes | Yes |
The CLI forwards `--mode` to the metrics API unchanged, and the API accepts only `time_series`, `latest`, `sparklines` and `org_summary`. The values printed in `fjall metrics --help` (`summary`, `requests`, `errors`, `latency`) and the CLI default of `summary` are rejected by the API with `400 Invalid query parameters`. Pass one of the four API modes explicitly on every invocation.
`-a, --app ` is sent verbatim as the `applicationId` query parameter. The server treats it as an application ID, not a name. Read the ID from `fjall apps describe `, which returns `name`, `health` and `id`.
```bash theme={null}
# Read the application id for the `api` app
fjall apps describe api
# Per-sample series for that application over the last 6 hours
fjall metrics show --mode time_series --app cm4x9j1of0003abcd7q2wlp8z --hours 6 --limit 200
```
`time_series` without `--app` returns `400 applicationId is required for time_series mode`.
## What Happens
1. The CLI checks stored credentials. Missing or rejected credentials stop the command with `Authentication required.` before any request goes out.
2. The subcommand resolves to `show`, and any unrecognised positional exits with the unknown-subcommand error above.
3. The CLI issues `GET /api/app-metrics` with `mode`, `applicationId`, `hours` and `limit` as query parameters. Absent flags are omitted from the query string, and the server applies its own defaults.
4. On success, the CLI prints the response as pretty-printed JSON on stdout. Every string is passed through credential masking first.
5. On failure, the CLI prints `Error: ` on stderr and exits non-zero.
The command is read-only. It creates nothing, changes nothing, and has no dry-run mode.
### Output shapes
The response body is a bare array of rows, with no envelope. `time_series`, `latest` and `org_summary` return metric rows carrying `application_id`, `resource_name`, `resource_type`, `timestamp`, `cpu_utilisation`, `memory_utilisation`, `request_count`, `error_count`, `target_response_time`, `error_rate`, `health_status` and the per-service counters for databases, storage, Lambda, queues, cache, DynamoDB and CDN. `sparklines` returns `application_id`, `hour`, `requests`, `errors` and `response_time_ms`.
`target_response_time` is recorded in seconds. Multiply by 1000 to compare it against millisecond latency figures.
### Agent mode
With `--agent`, or on an auto-detected agent host, the result renders as a TOON block on stdout instead of JSON, and failures render as a structured TOON error block rather than a stderr line. `--no-agent` forces the human path.
`metrics show` renders its payload without a field schema, so `--budget` and `--full` shape the block while `--fields` is accepted and has no effect on the rows. Filter the JSON with `jq` when you want a subset.
### Scale and failure responses
| Condition | Response |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| More than 60 requests per minute for one organisation | `429` with `Retry-After: 60` |
| Metrics store unreadable | `503 Could not read metrics ()`, so a broken read never reads as "no traffic" |
| Organisation has no applications, `latest` or `sparklines` | `[]` |
| No `--app` filter | `latest` and `sparklines` cover the first 100 applications in the organisation |
## Options
| Flag | Description | Default |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `--mode ` | Metrics view mode. Help text reads `summary \| requests \| errors \| latency`, the API accepts `time_series \| latest \| sparklines \| org_summary` | `summary` (rejected by the API) |
| `-a, --app ` | Filter by application. Sent as `applicationId`, so pass the ID | None, all applications |
| `--hours ` | Hours of history to include. Parsed as a decimal integer, server range 1 to 168 | `24` |
| `--limit ` | Max rows to return. Parsed as a decimal integer, server range 1 to 500 | `100` |
| `--non-interactive` | Force plain CLI output (no UI) | Off |
| `-v, --verbose` | Enable verbose output | Off |
| `--agent` | Enable agent output mode | Auto-detected |
| `--budget ` | Output budget: minimal, compact, or token count | None |
| `--fields ` | Select exactly these output fields. No effect on `metrics show`, which renders without a field schema | All fields |
| `--full` | Disable content truncation | Off |
`--agent`, `--no-agent`, `--budget`, `--fields`, `--full`, `--non-interactive` and `-v, --verbose` are also root-level options, so `fjall --agent metrics show --mode latest` works too.
## Next Steps
Ship a new version of the application whose metrics you just read.
Correlate a metric change with the release that landed.
Detect and repair infrastructure that has moved away from your definition.
Read metrics as TOON blocks from an AI agent or a script.