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

> ## Agent Instructions
> StackNext documentation is written for developers using StackNext in a Next.js App Router project. Use the getting-started and guides sections to install and operate the product, and the reference section for CLI, configuration, MCP and package surfaces. Version-matched package API reference ships inside each npm package under node_modules/@stacknext/<package>/docs/ and is preferred over this site for installed-version APIs. Diagnostic findings are evidence, not confirmed root causes; regression comparisons are deterministic and report-only. Contributor and repository-maintenance documentation is not part of this site.

# Runtime evidence

> Investigate requests, traces, errors and database activity with the dashboard, CLI and read-only MCP tools.

StackNext is an evidence source, not an answer generator. Every claim about
runtime behavior should point to a route, trace id, error id, span, duration,
status code, query or finding id.

## Start with the sample

```bash theme={null}
pnpm exec stacknext status
pnpm exec stacknext coverage
```

In the dashboard, the Overview page shows the sample window and what the current
sample observed. In an MCP client, call `get_project_summary` first. Check
`meta.connection.instrumentation`: `waiting` means no app is connected. Read
`meta.completeness` and the sample window before drawing conclusions.

## Explore the dashboard

| Route | What it shows |
| - | - |
| `/` | Counts, latency, database activity, errors, coverage and findings |
| `/requests` | Request list with route, status, duration and trace id |
| `/requests/:traceId` | Span timeline, correlated errors and queries for one request |
| `/traces` | Span trees with missing-parent information |
| `/database` | Redacted query events, route and optional duration |
| `/errors` | Redacted errors, fingerprints and correlated traces |
| `/diagnostics` | Deterministic findings and their evidence |
| `/snapshots` | Frozen samples saved under `.stacknext/snapshots` |
| `/runs`, `/baselines`, `/comparisons` | Playwright-linked regression records |

![HTTP requests view listing routes with status, duration, error and database query counts](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/requests.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=bb1f6ed027bfd28d2d80ef5504841388)

![HTTP requests view listing routes with status, duration, error and database query counts](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/requests-dark.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=6ee43d9a0a7e85dc2fedf1897f40330d)

## Investigate an error

1. Open **Errors** or call `list_errors` with a route, name or query filter.
2. Read the latest matching error and its redacted stack.
3. If `resolvedTraceId` is present, inspect the request timeline and the
   failing span.
4. Check `stacknext_list_diagnostics` with `category: "errors"` for a repeated
   fingerprint or a 5xx response without a correlated error.
5. Report what is proven, what is correlated by the route/time fallback, and
   what remains unknown.

An error grouped by fingerprint shares a normalized signature, not necessarily
a cause. A missing trace link means the correlation is approximate or absent;
it is not proof that the error happened outside a request.

![Server errors view grouping one error by fingerprint with its route and correlated trace id](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/errors.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=e688f3ff98d620abbe00ec5c0446ecc8)

![Server errors view grouping one error by fingerprint with its route and correlated trace id](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/errors-dark.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=5518b5a1f356c130cff95b56d9917d71)

## Investigate a slow request

1. Use **Requests** sorted by duration, `find_slow_requests`, or
   `list_requests` with `sort: "slowest"`.
2. Open the request and compare self time across spans.
3. Inspect database queries inside the trace. Drizzle durations are `null`;
   never treat them as zero.
4. Check `slow-request` and `slow-span` findings. A slow child span may be
   suppressed when the whole request is already reported.
5. Test whether the pattern is isolated by filtering the same route or method.

> [!WARNING]
>
> A parent span includes its children. Never add parent and child durations
> together.

![Trace detail for a slow route showing the span waterfall, the selected span and its attributes](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/request-detail.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=4b1efe4a755e415421bf163278bfe599)

![Trace detail for a slow route showing the span waterfall, the selected span and its attributes](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/request-detail-dark.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=538a8788c10806657596fa2afba654b6)

## Inspect a trace

`get_trace` returns the span tree, missing parent ids, errors and associated
queries. A missing parent is a completeness gap, not proof that the span is
unrelated. Use exact span ids when describing a link.

Unknown or verbose-only span types are retained and labelled rather than mapped
to a guessed feature. See [instrumentation coverage](https://docs.stacknext.space/instrumentation-coverage.md).

![Traces view listing captured traces with status, service, duration, error and span counts](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/traces.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=29a42f75c86dda8325359de4603f78e2)

![Traces view listing captured traces with status, service, duration, error and span counts](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/traces-dark.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=c3d539206576f32c2450892735dc0902)

## Use the CLI

```bash theme={null}
pnpm exec stacknext coverage
pnpm exec stacknext diagnose
pnpm exec stacknext diagnose --trace-id <trace-id>
pnpm exec stacknext export --stdout
pnpm exec stacknext snapshot save --label "before change"
```

The dashboard, CLI, export and MCP all read the same collector sample. A
snapshot is frozen and cannot answer questions about current behavior.

## Related

* [Diagnostics](https://docs.stacknext.space/guides/diagnostics.md)
* [Instrumentation coverage](https://docs.stacknext.space/instrumentation-coverage.md)
* [Snapshots](https://docs.stacknext.space/guides/snapshots.md)
* [MCP server](https://docs.stacknext.space/mcp.md)
* [Agent workflows](https://docs.stacknext.space/ai-agents/workflows.md)


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