[10/10] Warn when sample timeline is truncated

.changesets/add-samples-command.md

@@ -0,0 +1,6 @@
+---
+bump: minor
+type: add
+---
+
+Added a `samples` command to fetch the underlying transaction samples behind an incident, which `incidents show` does not expose. `samples show` fetches a single sample — the latest, one by id (`--sample-id`), or the one closest to a timestamp (`--at`) — and `samples list` returns an incident's samples, optionally narrowed with `--start`/`--end`/`--limit`. Both accept an AppSignal incident or sample URL (or a bare sample id) as a positional argument, or the explicit `--incident` plus the usual `--app-id`/`--app`/`--environment`/`--org` flags, and both support `--output json`.

.changesets/digest-truncation-note.md

@@ -0,0 +1,12 @@
+---
+bump: minor
+type: change
+---
+
+The `samples show` performance digest now warns when the API truncated the
+sample's timeline. AppSignal drops timeline events for very large samples, which
+silently understated the performance breakdown and slowest-events lists. When
+this happens the digest now prints `⚠ N timeline event(s) truncated by the API
+— the breakdown and slowest-events below are understated.`, and `--output json`
+includes a `truncated_events` count on the performance analysis. Samples whose
+timeline was not truncated are unaffected.

.changesets/headless-token-auth.md

@@ -0,0 +1,6 @@
+---
+bump: minor
+type: add
+---
+
+Added headless authentication with a personal API token, for CI and other non-interactive environments where the OAuth browser flow is impractical. Provide a token with the global `--api-token` flag or the `APPSIGNAL_API_TOKEN` environment variable and the CLI sends it as a `?token=` query parameter instead of running OAuth. A token supplied this way takes precedence over any stored OAuth credentials and is never written to disk; OAuth remains the default when no token is given. `appsignal-cli auth status` (and `about`) now report which authentication method is active.

.changesets/metrics-command.md

@@ -0,0 +1,6 @@
+---
+bump: minor
+type: add
+---
+
+Added a `metrics` command for working with an app's metrics directly from the terminal, served by the public GraphQL API. `metrics list` discovers the metric keys an app reports (name, type, fields, and tags), optionally filtered by `--name` fragment and capped with `--limit`. `metrics timeseries --metric <name>` fetches a metric's values over time, narrowed by `--field` and `--tag key=value` and windowed with either `--timeframe` (e.g. `R1H`) or both `--start` and `--end`. `metrics history --start <ISO> --end <ISO>` reports per-action error and performance throughput over an arbitrary window, scoped with `--namespaces`. All subcommands accept the usual `--app-id`/`--app`/`--environment`/`--org` flags and render as a table or, with `--output json`, as machine-readable JSON.

.changesets/performance-command.md

@@ -0,0 +1,6 @@
+---
+bump: minor
+type: add
+---
+
+Added a `performance` command for ranking slow work in an app. `performance actions` ranks the recent performance incidents by mean request duration (the default), total duration, or throughput, scoped with `--namespaces`, `--action`, and `--state`. `performance queries` takes the slowest actions, fetches the latest sample for each, and surfaces the slow database queries and N+1 suspects behind them — answering "why is this action slow?" without leaving the terminal. Both render as a table or, with `--output json`, as machine-readable JSON. Because the public API exposes performance data at the action level rather than per-SQL, the query view is derived from the latest sampled request for each action rather than a full aggregate, and the output states this.

.changesets/samples-cache-show.md

@@ -0,0 +1,6 @@
+---
+bump: minor
+type: add
+---
+
+Added `samples cache show <sample-id>`, which re-renders the full investigator digest of a previously cached sample entirely offline — no API call. The local cache already stores complete samples, so this surfaces the same analysed digest (or, with `--raw`, the unprocessed sample) that `samples show` produces, even when the incident is closed or you have no network access. Scope the lookup to one application with `--app-id`, and use `--output json` for the digest plus the cached sample and the time it was cached.

.changesets/samples-cache.md

@@ -0,0 +1,6 @@
+---
+bump: minor
+type: add
+---
+
+Fetched transaction samples are now cached locally so they can be re-inspected offline. `samples show` and `samples list` write each sample they fetch to a per-sample JSON file under the platform cache directory (best-effort — caching never blocks or fails a fetch, and it does not change their output). A new `samples cache` command works with that cache without touching the API: `samples cache list` shows recently cached samples newest-first (filterable by `--app-id`), `samples cache search <query>` finds cached samples by their contents (action, user, query bodies, exceptions, and more), `samples cache clear` deletes them all, and `samples cache path` prints the cache directory. Because samples can contain request parameters and session data, caching can be disabled per call with `--no-cache` or globally with the `APPSIGNAL_NO_CACHE` environment variable.

.changesets/samples-digest-output.md

@@ -0,0 +1,6 @@
+---
+bump: minor
+type: add
+---
+
+`samples show` now prints an analysed digest of the sample by default instead of a flat field dump: a request overview with the acting user, a performance breakdown by event group, the slowest events and queries, N+1 query detection, and — for error samples — the exception, backtrace, error causes, and breadcrumbs. `--output json` returns this as a structured `analysis` object alongside the raw `sample`, and `--raw` prints the unprocessed sample instead of the digest.

.changesets/samples-window-and-user.md

@@ -0,0 +1,6 @@
+---
+bump: minor
+type: add
+---
+
+`samples list` can now scan a time window across incidents instead of requiring a single incident. Omit `--incident` and pass `--start`/`--end` to collect the samples recorded in that window across recent incidents — answering "what happened between T1 and T2" rather than "show me this one incident". `--namespaces` narrows which incidents are scanned and `--user` keeps only samples whose user identity (matched against the sample's overview, attributes, and session data) contains the given id, email, or substring. In window mode `--limit` caps how many recent incidents are scanned (default 20). `--user` also works in single-incident mode.

.changesets/verbose-graphql.md

@@ -0,0 +1,6 @@
+---
+bump: minor
+type: add
+---
+
+Added a global `--verbose` (`-v`) flag that prints each outgoing GraphQL request — its URL, query, and variables — to stderr before it is sent. This makes it easy to see exactly what the CLI asks the API for when debugging, and because the dump goes to stderr it never mixes with `--output json` on stdout.