Instrumentation coverage

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?

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:

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:

{
  "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.

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

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.

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.

{
  "instrumentation": { "verbose": true }
}

Or override for one run:

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.

Overview

Getting started

Guides

Integrations

AI agents

Reference

Troubleshooting

Security and privacy

Instrumentation coverage

Run coverage

Sample window

Statuses

Why there is no coverage percentage

What is checked

Reading common results

`next.request-root` is not observed

`database.drizzle` is unknown

`custom.server-actions` is not observed

`next.verbose-spans` is not observed

An item is `unsupported`

Verbose tracing

Limits

​Run coverage

​Sample window

​Statuses

​Why there is no coverage percentage

​What is checked

​Reading common results

​next.request-root is not observed

​database.drizzle is unknown

​custom.server-actions is not observed

​next.verbose-spans is not observed

​An item is unsupported

​Verbose tracing

​Limits

​Related

Run coverage

Sample window

Statuses

Why there is no coverage percentage

What is checked

Reading common results

`next.request-root` is not observed

`database.drizzle` is unknown

`custom.server-actions` is not observed

`next.verbose-spans` is not observed

An item is `unsupported`

Verbose tracing

Limits

Related