@stacknext/next 0.9.0 → 0.11.0

package/docs/configuration.md

@@ -0,0 +1,88 @@
+---
+title: Configuration
+description: Environment variables and verbose tracing behavior for @stacknext/next.
+---
+
+# Configuration
+
+`@stacknext/next` reads environment variables supplied by `stacknext dev`. The
+application does not import `stacknext.config.json` directly; the CLI resolves
+the config and exports the relevant values to the child process.
+
+## Environment variables
+
+| Variable | Default | Behavior |
+| --- | --- | --- |
+| `STACKNEXT_COLLECTOR_URL` | none | Required for tracing. Must be loopback. |
+| `STACKNEXT_TOKEN` | none | Required for tracing. At least 16 characters. |
+| `STACKNEXT_PROJECT_NAME` | project name | Reported to the collector. |
+| `STACKNEXT_SERVICE_NAME` | project or `next-app` | OTel service name. |
+| `STACKNEXT_NEXT_VERSION` | none | Used for environment checks. |
+| `STACKNEXT_CAPTURE_FETCH` | `1` | `0` drops `AppRender.fetch` spans. |
+| `STACKNEXT_CAPTURE_ERRORS` | `1` | `0` makes `onRequestError` a no-op. |
+| `STACKNEXT_DEBUG` | unset | `1` enables debug logs. |
+| `NEXT_OTEL_VERBOSE` | unset | `1` enables the documented Next.js verbose span set. |
+
+`stacknext dev` sets these from `stacknext.config.json`:
+`instrumentation.captureFetch` → `STACKNEXT_CAPTURE_FETCH`,
+`instrumentation.captureErrors` → `STACKNEXT_CAPTURE_ERRORS`,
+`instrumentation.verbose` → `NEXT_OTEL_VERBOSE`.
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:e042398001c539a0b51d0ae05cbcd223e5aa7ce932217b716003cea788939d36 -->
+
+An explicit `NEXT_OTEL_VERBOSE` environment value wins. For example,
+`NEXT_OTEL_VERBOSE=0` disables verbose tracing even when the config says
+`"verbose": true`. `stacknext dev` overwrites `STACKNEXT_CAPTURE_FETCH`,
+`STACKNEXT_CAPTURE_ERRORS` and `STACKNEXT_DEBUG` from configuration (with the
+CLI debug flag also affecting `STACKNEXT_DEBUG`); inherited values for these
+variables do not take precedence.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+## Register options vs environment
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:8045c991239c9f407c0469ae1416579f2a27d6f781161eb4253fee1480f382cf -->
+
+`enabled`, `captureFetch`, `serviceName` and `nextVersion` control registration
+and instrumentation for that call. When `transport` is omitted,
+`resolveTransport()` uses the environment directly: `projectName` does not
+override the project reported by that transport, and `collectorUrl` only changes
+the self-instrumentation filter. Provide an explicit `transport` override to
+control the collector or project used for telemetry. With that override,
+`serviceName`, `projectName` and `nextVersion` also override its corresponding
+transport values. The transport requires a valid token and loopback URL.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+## Verbose tracing
+
+`NEXT_OTEL_VERBOSE=1` adds documented Next.js span types. It:
+
+- increases stored span volume and dev-server work;
+- can shorten the effective retention of older events when capacity is reached;
+- does **not** enable body, header, cookie, query-value or SQL-parameter
+  capture.
+
+Use `stacknext coverage` or `get_project_summary` to see whether verbose
+evidence is present. Unknown span types are retained as evidence instead of
+being mapped to a guessed feature.
+
+## What cannot be enabled
+
+The config schema rejects:
+
+- `privacy.captureHeaders`;
+- `privacy.captureRequestBodies`;
+- `privacy.captureSqlParameters`;
+- `privacy.redactSensitiveData: false`.
+
+There are no environment variables that bypass these rules.
+
+## Related
+
+- [@stacknext/core configuration](../../core/docs/configuration.md)
+- the repository `docs/benchmark.md`

package/docs/custom-spans.md

@@ -0,0 +1,105 @@
+---
+title: Custom spans
+description: Add application and Server Action spans with withStackNextSpan, withStackNextSpanSync and withStackNextAction.
+---
+
+# Custom spans
+
+StackNext exports three optional helpers from `@stacknext/next`. They use the
+existing OpenTelemetry context/provider and do **not** create a second SDK.
+
+## Async work
+
+```ts
+import { withStackNextSpan } from '@stacknext/next'
+
+const project = await withStackNextSpan(
+  'load project',
+  { attributes: { 'project.id': id } },
+  async (span) => {
+    const project = await loadProject(id)
+    span.setAttribute('project.found', project !== null)
+    return project
+  },
+)
+```
+
+Supported signatures:
+
+```ts
+withStackNextSpan(name, fn, options?)
+withStackNextSpan(name, options, fn)
+```
+
+The callback receives the active OTel `Span`. Return values and thrown errors
+are preserved. By default a thrown exception is recorded unless it is a Next.js
+control-flow error (`NEXT_NOT_FOUND`, `NEXT_REDIRECT*` or
+`NEXT_HTTP_ERROR_FALLBACK*`). Set `recordException: false` to disable recording.
+
+## Synchronous work
+
+```ts
+import { withStackNextSpanSync } from '@stacknext/next'
+
+const rows = withStackNextSpanSync(
+  'sqlite batch',
+  { attributes: { 'batch.size': 25 } },
+  () => runBatch(),
+)
+```
+
+Same argument forms and error behavior as the async helper.
+
+## Server Actions
+
+Successful Server Actions do not reach `onRequestError`, so StackNext cannot see
+them automatically. Wrap the action explicitly:
+
+```ts
+'use server'
+
+import { withStackNextAction } from '@stacknext/next'
+
+export async function updateProject(formData: FormData) {
+  return withStackNextAction(
+    'action updateProject',
+    { attributes: { 'project.id': String(formData.get('id') ?? '') } },
+    async () => {
+      // Action body.
+    },
+  )
+}
+```
+
+`withStackNextAction` sets `stacknext.span.kind = "action"`. It records only the
+span name and attributes you pass; action arguments, `FormData` values and return
+values are never captured automatically.
+
+## Options
+
+`StackNextManualSpanOptions`:
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `attributes` | `Record<string, unknown>` | none | Sanitized before enqueueing. |
+| `kind` | OTel `SpanKind` | `INTERNAL` | Span kind. |
+| `recordException` | boolean | `true` | Record non-control-flow errors. |
+
+The helpers add `stacknext.manual = true` and `stacknext.span.kind` after caller
+attributes so coverage cannot be spoofed.
+
+## Attribute safety
+
+Attributes pass through `sanitizeAttributes`: sensitive keys, headers and URL
+query values are redacted. The collector applies a second pass. Do not put large
+payloads or secrets in attribute values.
+
+## What the helpers do not do
+
+- They do not automatically trace every Server Component or Server Action.
+- They do not measure work you did not wrap.
+- They do not create a new provider or exporter.
+- They do not capture arguments, return values or bodies.
+
+For broader guidance see the repository's `docs/custom-instrumentation.md`
+and `docs/server-actions.md`.

package/docs/index.md

@@ -0,0 +1,92 @@
+---
+title: "@stacknext/next"
+description: Next.js instrumentation, OpenTelemetry export, request errors and manual spans for StackNext.
+---
+
+# @stacknext/next
+
+`@stacknext/next` connects a Next.js App Router application to a local
+StackNext collector. It registers an OpenTelemetry `NodeTracerProvider`, converts
+spans to the StackNext wire format, installs a W3C propagator, forwards
+`onRequestError` hooks and exports optional manual span helpers.
+
+## Who should read this
+
+Application developers installing StackNext. This is a **public integration
+package** and the only instrumentation package a normal project needs.
+
+## Installation
+
+```bash
+pnpm add -D @stacknext/cli @stacknext/next
+```
+
+`@stacknext/next` declares `next >=15.0.0 <17` as a peer dependency. It requires
+the Node.js runtime; the `edge` export exists only to keep Edge bundling safe and
+returns an inert module.
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@stacknext/next` | `register`, `registerStackNext`, `shutdownStackNext`, `getStackNextRegistration`, `onRequestError`, manual span helpers and exporter utilities. |
+| `@stacknext/next` with the `edge` condition | `./dist/edge.js`, an inert module for Edge bundles. |
+
+## Quick start
+
+`stacknext init` creates `instrumentation.ts` (or `.js`) that guards on
+`NEXT_RUNTIME === 'nodejs'` and imports StackNext dynamically:
+
+```ts
+export async function register(): Promise<void> {
+  if (process.env.NEXT_RUNTIME !== 'nodejs') return
+  const stacknext = await import('@stacknext/next')
+  await stacknext.register()
+}
+
+export async function onRequestError(
+  error: unknown,
+  request: unknown,
+  context: unknown,
+): Promise<void> {
+  if (process.env.NEXT_RUNTIME !== 'nodejs') return
+  const stacknext = await import('@stacknext/next')
+  stacknext.onRequestError(
+    error,
+    request as Parameters<typeof stacknext.onRequestError>[1],
+    context as Parameters<typeof stacknext.onRequestError>[2],
+  )
+}
+```
+
+Do not replace an existing `instrumentation.ts`. Import `registerStackNext` and
+`onRequestError` into the existing hook instead. See
+[Installation](installation.md).
+
+## Behavior
+
+- `register()` is inert when `STACKNEXT_COLLECTOR_URL` and `STACKNEXT_TOKEN` are
+  absent. A production build can ship safely.
+- If another OpenTelemetry tracer provider is already registered, StackNext
+  yields to it and does not replace it.
+- Spans are redacted and normalized before enqueueing.
+- The exporter never performs synchronous network I/O.
+- The transport shares one bounded queue with the Drizzle and Prisma adapters.
+- `shutdownStackNext()` flushes buffered spans and is safe to call more than
+  once.
+
+## Documentation map
+
+- [Installation](installation.md) — peer requirements and safe setup.
+- [Instrumentation](instrumentation.md) — `register`, options and lifecycle.
+- [Configuration](configuration.md) — environment variables and verbose tracing.
+- [Custom spans](custom-spans.md) — `withStackNextSpan*` and Server Actions.
+- [Troubleshooting](troubleshooting.md) — no telemetry, provider conflicts and
+  Edge warnings.
+
+## Related packages
+
+- `@stacknext/core` supplies the wire types, redaction and transport.
+- `@stacknext/drizzle` and `@stacknext/prisma` add database query events to the
+  same queue.
+- `@stacknext/cli` runs the collector that receives the data.

package/docs/installation.md

@@ -0,0 +1,97 @@
+---
+title: Installation
+description: Install @stacknext/next safely without replacing existing instrumentation or monitoring.
+---
+
+# Installation
+
+## Requirements
+
+- Node.js `>=20.9.0`.
+- Next.js 15 or 16 with the App Router.
+- The Node.js runtime. Edge instrumentation is not supported.
+- A local StackNext collector started by `stacknext dev`.
+
+## Install
+
+```bash
+npm install --save-dev @stacknext/cli @stacknext/next
+```
+
+or:
+
+```bash
+pnpm add -D @stacknext/cli @stacknext/next
+```
+
+Install inside the Next.js application package, not at a monorepo root.
+
+## Create the hook
+
+```bash
+npx stacknext init
+```
+
+If the project has no `instrumentation.ts`/`.js`, `init` writes one that:
+
+1. runs only when `NEXT_RUNTIME === 'nodejs'`;
+2. dynamically imports `@stacknext/next` so Edge bundling does not load Node-only
+   modules;
+3. calls `register()` and `onRequestError`.
+
+The generated file is idempotent and recognized by `stacknext uninstall`.
+
+## Preserve existing instrumentation
+
+Never overwrite an existing hook that another monitoring tool owns. Add
+StackNext inside it:
+
+```ts
+import {
+  registerStackNext,
+  onRequestError as stackNextOnRequestError,
+} from '@stacknext/next'
+
+export async function register() {
+  await startExistingMonitoring()
+  await registerStackNext()
+}
+
+// Only if the file does not already export an error hook.
+export const onRequestError = stackNextOnRequestError
+```
+
+If `onRequestError` already exists, call
+`stackNextOnRequestError(error, request, context)` inside it.
+
+StackNext checks for an already-registered OpenTelemetry provider and leaves it
+untouched. It does not create a second SDK when another APM is active.
+
+## Environment
+
+`stacknext dev` supplies:
+
+| Variable | Purpose |
+| --- | --- |
+| `STACKNEXT_COLLECTOR_URL` | Loopback collector origin. |
+| `STACKNEXT_TOKEN` | Bearer token for ingest. |
+| `STACKNEXT_PROJECT_NAME` | Project name reported with telemetry. |
+| `STACKNEXT_NEXT_VERSION` | Next.js version for environment checks. |
+| `STACKNEXT_CAPTURE_FETCH` | `0` drops Next.js fetch spans. |
+| `STACKNEXT_CAPTURE_ERRORS` | `0` disables the error hook. |
+| `STACKNEXT_DEBUG` | `1` enables debug logs. |
+
+Do not commit these values. The token lives in `.stacknext/run.json` with mode
+`0600` and is generated per run.
+
+## Verify
+
+With `stacknext dev` running:
+
+```bash
+npx stacknext doctor
+npx stacknext status
+```
+
+Then make one request and confirm `requests` and `spans` increase. If the
+dashboard is empty, see [Troubleshooting](troubleshooting.md).

package/docs/instrumentation.md

@@ -0,0 +1,98 @@
+---
+title: Instrumentation
+description: register, registerStackNext and the OpenTelemetry lifecycle used by StackNext.
+---
+
+# Instrumentation
+
+## `register(options?)`
+
+```ts
+import { register } from '@stacknext/next'
+
+await register()
+```
+
+Alias for `registerStackNext()`. Call it from the app's `instrumentation.ts`
+`register()` hook. It returns `null` when tracing is disabled or another
+provider is active.
+
+## `registerStackNext(options?)`
+
+```ts
+import { registerStackNext } from '@stacknext/next'
+
+const registration = await registerStackNext()
+```
+
+`StackNextRegisterOptions`:
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `transport` | `StackNextTransportOptions` | Overrides environment transport configuration. |
+| `collectorUrl` | string | Collector URL, also used to filter self-instrumentation requests. |
+| `serviceName` | string | OTel service name. Defaults to the transport value or `next-app`. |
+| `projectName` | string | Project name reported to the collector. |
+| `nextVersion` | string | Next.js version for the environment snapshot. |
+| `captureFetch` | boolean | Set `false` to drop `AppRender.fetch` spans. |
+| `enabled` | boolean | Set `false` to keep StackNext loaded but inactive. |
+
+It returns a `StackNextRegistration` with `provider`, `transport`, `exporter`,
+`serviceName` and `registeredAt`, or `null`.
+
+### Registration order
+
+1. Return the existing registration if this process already registered.
+2. Return `null` when `enabled: false` or the runtime is not Node.js.
+3. Return `null` when another OTel provider is already registered.
+4. Resolve the shared transport from options or environment.
+5. Return `null` when collector URL/token are absent.
+6. Build a `NodeTracerProvider` with a `BatchSpanProcessor`:
+   - scheduled delay 200 ms;
+   - queue size 2,048;
+   - export batch 256;
+   - export timeout 2,000 ms.
+7. Register the provider and install a composite W3C trace-context and baggage
+   propagator.
+8. Store the registration globally and hook `beforeExit` to flush.
+
+The propagator is required so an incoming `traceparent` from a local Playwright
+capture becomes the parent of the Next.js request trace.
+
+## `getStackNextRegistration()`
+
+Returns the active registration without creating one. Useful in tests and
+shutdown code.
+
+## `shutdownStackNext()`
+
+```ts
+import { shutdownStackNext } from '@stacknext/next'
+
+await shutdownStackNext()
+```
+
+Flushes buffered spans and shuts down the provider and transport. Safe to call
+more than once. Next.js owns process signals; StackNext only hooks
+`beforeExit`.
+
+## Manual exporter utilities
+
+`StackNextSpanExporter`, `readableSpanToInput`, `spanAttributes` and
+`StackNextSpanExporterOptions` are exported for tests and custom integrations.
+`readableSpanToInput` returns `null` for invalid ids, internal instrumentation
+spans and requests to the StackNext collector itself. It redacts names,
+attributes, resource attributes and status messages.
+
+## Self-instrumentation filter
+
+Requests to `/__stacknext/` and the collector origin are excluded so the
+dashboard and MCP traffic do not appear as application requests.
+
+## What is not automatic
+
+- Server Components are not traced individually.
+- Server Actions are not named automatically. See [Custom spans](custom-spans.md).
+- Application functions and arbitrary database drivers are not inferred.
+- Browser/client tracing is out of scope.
+- Edge runtime is not supported.

package/docs/troubleshooting.md

@@ -0,0 +1,78 @@
+---
+title: Troubleshooting
+description: Diagnose missing Next.js telemetry, provider conflicts, Edge warnings and startup failures.
+---
+
+# Troubleshooting
+
+## The dashboard is empty
+
+1. Confirm the app is started through `stacknext dev`, not `next dev`. The CLI
+   supplies the collector URL and token.
+2. Run `stacknext doctor`. It checks Node.js, Next.js, the App Router, config,
+   instrumentation, the dashboard build and collector health.
+3. Run `stacknext status --json` and inspect `runtime` and `connections`.
+4. Make a request after the app has fully started.
+5. Check `stacknext coverage`: `active` with no requests means the app is
+   connected but the feature has not been exercised yet.
+
+## `register()` returns `null`
+
+Possible causes:
+
+- `STACKNEXT_COLLECTOR_URL` or `STACKNEXT_TOKEN` is missing. Start the app with
+  `stacknext dev`.
+- Another OpenTelemetry provider is already registered. Run with
+  `STACKNEXT_DEBUG=1` and look for the "leaving it untouched" message. StackNext
+  intentionally yields instead of replacing another APM.
+- The runtime is not Node.js. Edge is unsupported.
+- `enabled: false` was passed explicitly.
+
+## No error records
+
+- Check `instrumentation.captureErrors` and `STACKNEXT_CAPTURE_ERRORS`.
+- Confirm `instrumentation.ts` exports `onRequestError`.
+- An existing `onRequestError` must call `stackNextOnRequestError(...)`.
+- Control-flow errors from not-found/redirect responses are intentionally
+  excluded from diagnostics.
+- Errors without an active span context are correlated by route/method and a
+  30-second window. They may show as fallback-correlated or uncorrelated.
+
+## Missing fetch spans
+
+Set `instrumentation.captureFetch` to `true` (the default) and ensure
+`STACKNEXT_CAPTURE_FETCH` is not `0`. Only Next.js-emitted fetch spans can be
+captured.
+
+## Edge build warnings or failures
+
+Keep every StackNext import behind:
+
+```ts
+if (process.env.NEXT_RUNTIME !== 'nodejs') return
+```
+
+Use a dynamic import inside the hook. Do not import `@stacknext/next` at the top
+level of a module that Edge also bundles.
+
+## Existing monitoring stopped working
+
+StackNext must never replace a provider. If another tool stops receiving data,
+check whether it registered before or after `registerStackNext()` and whether
+the generated hook was merged into the existing `instrumentation.ts` rather than
+replacing it. `stacknext init` prints a manual patch when a file exists.
+
+## Telemetry is dropped
+
+The in-memory store is bounded by `collector.maxSpans` and
+`collector.retentionMs`. `/api/health`, `stacknext status` and the dashboard
+settings page report drop counters. `NEXT_OTEL_VERBOSE=1` increases span volume
+and can shorten the effective retention window.
+
+## Verify
+
+```bash
+stacknext doctor --json
+stacknext status --json
+stacknext coverage --json
+```

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@stacknext/next",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Next.js instrumentation and OpenTelemetry exporter for StackNext",
   "license": "MIT",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -23,7 +24,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@stacknext/core": "0.9.0",
+    "@stacknext/core": "0.11.0",
     "@opentelemetry/api": "1.9.0",
     "@opentelemetry/context-async-hooks": "2.12.0",
     "@opentelemetry/core": "2.12.0",