> ## 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.

# Instrumentation coverage

> Read evidence-based coverage statuses without turning them into a score.

StackNext can tell you what it actually observed in the current telemetry
sample, not just whether the collector is running. Coverage answers questions
such as:

* Did Next.js send request-root and route-handler spans?
* Were Drizzle or Prisma query events captured?
* Did the sample exercise fetch spans, middleware, page renders or Server
  Actions?
* Is verbose Next.js tracing enabled, and did verbose span types arrive?
* Which parts are unsupported by design?

> [!WARNING]
>
> Coverage is **evidence from the current in-memory sample**, not a percentage or
> an audit of your application. A missing item means the sample did not prove the
> feature was active. It does not prove that the feature is broken.

## Run coverage

With `stacknext dev` running:

```bash theme={null}
stacknext coverage
stacknext coverage --json
```

The human-readable view groups items by status and prints the sample window,
connection state, status counts and limitations. `--json` prints the same report
as machine-readable JSON. The dashboard shows a compact version on **Overview**
under **Instrumentation coverage**.

The collector exposes the full report at `GET /api/coverage`, and
`GET /api/summary` includes an optional `coverage` object. The read-only MCP
tool `get_project_summary` returns the report plus a compact summary in
`meta.coverage`:

```json theme={null}
{
  "meta": {
    "coverage": {
      "observed": 5,
      "active": 1,
      "configured": 0,
      "notObserved": 4,
      "unsupported": 3,
      "unknown": 1,
      "requestsInSample": 12
    }
  }
}
```

Coverage is additive response data; existing MCP tool names and arguments are
unchanged.

## Sample window

Every report includes:

| Field | Meaning |
| - | - |
| `sample.requests` | Requests derived from request-root spans in the store |
| `sample.spans` | Spans currently retained |
| `sample.errors` | Errors currently retained |
| `sample.databaseQueries` | Query events currently retained |
| `sample.firstEventTime` / `lastEventTime` | Oldest and newest event time in the sample |
| `sample.retentionMs` | Configured retention window |
| `sample.connected` / `connectedInstances` | Whether an app instance is connected now |

The store is bounded and retention-pruned. Coverage never reads a historical
database because there is no database: it is computed from the records still in
memory when you ask. Restarting `stacknext dev`, letting data age out, or
exceeding capacity changes the sample.

If no app is connected, the report says so. Configured items then describe
setup, not runtime evidence.

## Statuses

Each item has exactly one status:

| Status | Meaning |
| - | - |
| `observed` | At least one matching span, error or query was found in the sample |
| `active` | The app is connected but the sample has no requests yet, so the feature has not had an opportunity to appear |
| `configured` | No app is connected, but the collector configuration suggests the feature is enabled. A setup signal, not runtime proof |
| `not-observed` | The app connected and requests were captured, but no matching evidence appeared; or the feature is explicitly disabled by configuration |
| `unknown` | StackNext cannot determine the state from telemetry and configuration |
| `unsupported` | The feature is outside StackNext's supported surface by design |

`statusCounts` counts the items in each status and always adds up to
`items.length`. The counts are not weighted into a score.

### Why there is no coverage percentage

A single number would imply that unrelated features are interchangeable and that
absence is failure. Both are false:

* API-only traffic does not exercise page rendering.
* A healthy app can legitimately produce zero errors.
* Middleware may not exist or may not run for a given route.
* A fetch span only exists if the request made a fetch.
* Drizzle and Prisma are independent adapters.
* Server Actions are only visible when explicitly wrapped.

Use the statuses to decide what to inspect next, not as a quality score.

## What is checked

| Item | Category | Evidence source |
| - | - | - |
| HTTP request root spans | Next.js framework | `BaseServer.handleRequest` and `Next.request` span types |
| App Router page renders | Next.js framework | `AppRender.getBodyResult` and documented render span types |
| Route handlers | Next.js framework | `AppRouteRouteHandlers.runHandler` and `Node.runHandler` |
| Middleware | Next.js framework | `Middleware.execute` |
| Fetch calls | Next.js framework | `AppRender.fetch` or client fetch spans, subject to `captureFetch` |
| Request error hook | Errors | Errors stored through `onRequestError` |
| Drizzle queries | Database | Drizzle adapter query events |
| Prisma queries | Database | Prisma `$on('query')` events |
| Server Actions | Custom instrumentation | Spans created by `withStackNextAction` |
| Custom application spans | Custom instrumentation | Spans created by `withStackNextSpan` or `withStackNextSpanSync` |
| Verbose Next.js spans | Runtime boundary | Non-standard span types observed while `NEXT_OTEL_VERBOSE=1` |
| Individual Server Components | Runtime boundary | Unsupported: no documented per-component hook |
| Edge runtime | Runtime boundary | Unsupported: Node.js only |
| Automatic Server Action tracing | Runtime boundary | Unsupported: use the explicit action helper |

Each item carries `id`, `label`, `category`, `configured`, `observed`,
`description`, `evidence` and `limitations`. `evidence` contains the matching
span types, event count and last-seen time. Use `stacknext coverage --json` for
the raw shape.

## Reading common results

### `next.request-root` is not observed

The collector connected and received spans, but none had a documented
request-root type. This can happen if:

* the trace starts below the HTTP layer;
* the app is on an unsupported Next.js version; or
* another instrumentation layer is emitting spans without Next.js request-root
  metadata.

Check `evidence.spanTypes`, `stacknext doctor` and the installed Next.js version
before changing application code.

### `database.drizzle` is unknown

`database.drizzle` is `false` in `stacknext.config.json`, so StackNext cannot tell
whether the Drizzle logger is registered. Set the flag when you add the adapter,
and make a request that runs a query. Registration is still explicit code; the
config flag only helps `init`, `doctor` and coverage describe intent.

### `custom.server-actions` is not observed

Successful Server Actions do not reach `onRequestError`, and StackNext does not
invent action names from Next.js internals. Wrap exported actions with
`withStackNextAction` and exercise one. See
[Server Actions](https://docs.stacknext.space/custom-instrumentation.md#server-actions).

### `next.verbose-spans` is not observed

Either verbose tracing is disabled, or the sample contains no verbose-only span
types. Check the health/config output for the effective `NEXT_OTEL_VERBOSE`
source. See [verbose tracing](#verbose-tracing).

### An item is `unsupported`

Unsupported is not a bug report. Edge runtime, individual Server Components and
automatic Server Action names are documented boundaries. See
[limitations](https://docs.stacknext.space/limitations.md).

## Verbose tracing

Next.js exposes additional span types when the documented
`NEXT_OTEL_VERBOSE=1` environment variable is set. StackNext does not patch
Next.js internals or use `NEXT_PRIVATE_*` variables.

```json theme={null}
{
  "instrumentation": { "verbose": true }
}
```

Or override for one run:

```bash theme={null}
NEXT_OTEL_VERBOSE=1 stacknext dev
```

`stacknext dev` propagates the setting to the Next.js child process. An explicit
inherited value wins over the config file, including `NEXT_OTEL_VERBOSE=0`.
Next.js only treats the literal value `1` as enabled; other non-empty values are
reported as an unrecognized override rather than silently claimed as active.

The dashboard settings page, `stacknext status`, `stacknext dev` startup output
and the collector health/config endpoints report whether verbose tracing is
enabled and where the setting came from. `stacknext coverage` reports whether
verbose span types were actually observed.

Verbose tracing is for targeted investigations. It increases the number of spans
Next.js creates and exports, which increases dev-server work, collector volume
and the chance of hitting retention or capacity limits.

## Limits

* Coverage is a snapshot of the retention window, not a historical score.
* Evidence is inferred from redacted telemetry. It never includes query values,
  bodies, headers, cookies or SQL parameters.
* Configuration flags describe intent. Adapter code still has to be registered.
* `not-observed` and `unknown` can be correct on a healthy app.
* StackNext does not patch Next.js internals, so unknown framework span types are
  retained and labelled rather than mapped to a guessed feature.

## Related

* [Configuration](https://docs.stacknext.space/reference/configuration.md)
* [Diagnostics](https://docs.stacknext.space/guides/diagnostics.md)
* [Limitations](https://docs.stacknext.space/limitations.md)


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