Skip to content

The only tool you need to know what is happening and how to fix it.

more docs updates

dduxaa78d60d8328
diff --git a/docs/pages/client/_meta.json b/docs/pages/client/_meta.json
index af4cadc3..6127589c 100644
--- a/docs/pages/client/_meta.json
+++ b/docs/pages/client/_meta.json
@@ -14,6 +14,7 @@
"node-sdk": "Node.js (OTel)",
"nestjs": "NestJS (OTel)",
"hono": "Hono",
+ "nextjs": "Next.js (OTel)",
"react": "React",
"vue": "Vue.js",
"svelte": "Svelte",
diff --git a/docs/pages/client/hono/index.mdx b/docs/pages/client/hono/index.mdx
index 48ac80a3..4af2f775 100644
--- a/docs/pages/client/hono/index.mdx
+++ b/docs/pages/client/hono/index.mdx
@@ -46,14 +46,76 @@ const sdk = new NodeSDK({
sdk.start();
```
+## Route & Error Middleware (Required)
+
+Hono has no dedicated OTel instrumentation package, so two pieces are missing that you must add manually:
+
+1. **Route middleware** — Without it, Traceway falls back to the literal URL path (e.g., `/api/users/1`, `/api/users/2`) instead of grouping requests by route pattern (`GET /api/users/:id`).
+2. **Error handler** — Hono catches errors before they reach the HTTP layer, so OTel never sees them. Without an explicit handler, errors won't appear as Issues in Traceway.
+
+### Route Middleware
+
+Register this middleware **before** your route handlers. It runs after the handler completes (`await next()`), reads the matched route pattern via `c.req.routePath`, and sets `http.route` on the active OTel span:
+
+```typescript
+import { trace } from "@opentelemetry/api";
+
+app.use("*", async (c, next) => {
+ await next();
+ const span = trace.getActiveSpan();
+ if (span) {
+ span.setAttribute("http.route", c.req.routePath);
+ }
+});
+```
+
+### Error Handler
+
+Record exceptions on the active span so they appear as Issues in Traceway:
+
+```typescript
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+
+app.onError((err, c) => {
+ const span = trace.getActiveSpan();
+ if (span) {
+ span.recordException(err);
+ span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+ }
+ return c.json({ error: "Internal Server Error" }, 500);
+});
+```
+
## Application Code
+Here's a complete example with the route middleware and error handler in place:
+
```typescript
import { serve } from "@hono/node-server";
import { Hono } from "hono";
+import { trace, SpanStatusCode } from "@opentelemetry/api";
const app = new Hono();
+// Route middleware — sets http.route for endpoint grouping
+app.use("*", async (c, next) => {
+ await next();
+ const span = trace.getActiveSpan();
+ if (span) {
+ span.setAttribute("http.route", c.req.routePath);
+ }
+});
+
+// Error handler — records exceptions as Issues
+app.onError((err, c) => {
+ const span = trace.getActiveSpan();
+ if (span) {
+ span.recordException(err);
+ span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+ }
+ return c.json({ error: "Internal Server Error" }, 500);
+});
+
app.get("/api/users", (c) => {
return c.json({ users: [] });
});
@@ -87,15 +149,17 @@ node server.js
## What Gets Captured
-Hono on Node.js uses `@hono/node-server`, which creates a standard Node.js HTTP server. OTel auto-instrumentation captures:
+Hono on Node.js uses `@hono/node-server`, which creates a standard Node.js HTTP server. With the route middleware and error handler from above, OTel captures:
| Layer | What's Captured |
|-------|-----------------|
-| HTTP server | Incoming requests with method, route, status code, duration |
+| HTTP server | Incoming requests with method, status code, duration |
+| Route middleware | `http.route` for endpoint grouping (e.g., `GET /api/users/:id`) |
+| Error handler | Exceptions recorded as Issues with stack traces |
| HTTP client (fetch) | Outgoing HTTP request spans |
| Database (pg, mysql2, etc.) | Query spans |
-Root SERVER spans become **Endpoints** in Traceway (e.g., `GET /api/users`), child spans become **Spans**, and exception events become **Issues**.
+Root SERVER spans become **Endpoints** in Traceway, child spans become **Spans**, and exception events become **Issues**.
## Environment Variable Alternative
diff --git a/docs/pages/client/hono/traces.mdx b/docs/pages/client/hono/traces.mdx
index e10bbea4..a2bd06ed 100644
--- a/docs/pages/client/hono/traces.mdx
+++ b/docs/pages/client/hono/traces.mdx
@@ -61,6 +61,8 @@ app.use("/api/*", addUserContext);
## Exception Recording
+> **Important:** The `app.onError` handler below is required for all Hono + OTel setups. If you followed the [Quick Start](/client/hono), it's already included. Without it, Hono catches errors internally and OTel never records them.
+
Capture exceptions on the active span so they appear as Issues in Traceway:
```typescript
diff --git a/docs/pages/client/nextjs/_meta.json b/docs/pages/client/nextjs/_meta.json
new file mode 100644
index 00000000..13ec779a
--- /dev/null
+++ b/docs/pages/client/nextjs/_meta.json
@@ -0,0 +1,4 @@
+{
+ "index": "Quick Start",
+ "traces": "Traces"
+}
diff --git a/docs/pages/client/nextjs/index.mdx b/docs/pages/client/nextjs/index.mdx
new file mode 100644
index 00000000..a0ce5bbe
--- /dev/null
+++ b/docs/pages/client/nextjs/index.mdx
@@ -0,0 +1,184 @@
+# Next.js (OpenTelemetry)
+
+Instrument your Next.js application with OpenTelemetry and export server-side traces and metrics to Traceway. This guide covers the App Router (Next.js 13.4+). For client-side error tracking, see `@tracewayapp/next` on the Connection page in your Traceway dashboard.
+
+## Installation
+
+```bash
+npm install @opentelemetry/sdk-node \
+ @opentelemetry/auto-instrumentations-node \
+ @opentelemetry/exporter-trace-otlp-http \
+ @opentelemetry/exporter-metrics-otlp-http \
+ @opentelemetry/api
+```
+
+## Setup
+
+Create an `instrumentation.ts` file in the root of your project (next to `next.config.js`). Next.js loads this file automatically during server startup — no `--require` flag needed.
+
+```typescript
+export async function register() {
+ if (process.env.NEXT_RUNTIME === "nodejs") {
+ const { NodeSDK } = await import("@opentelemetry/sdk-node");
+ const { OTLPTraceExporter } = await import(
+ "@opentelemetry/exporter-trace-otlp-http"
+ );
+ const { OTLPMetricExporter } = await import(
+ "@opentelemetry/exporter-metrics-otlp-http"
+ );
+ const { PeriodicExportingMetricReader } = await import(
+ "@opentelemetry/sdk-metrics"
+ );
+ const { getNodeAutoInstrumentations } = await import(
+ "@opentelemetry/auto-instrumentations-node"
+ );
+
+ const sdk = new NodeSDK({
+ serviceName: "my-nextjs-app",
+ serviceVersion: "1.0.0",
+
+ traceExporter: new OTLPTraceExporter({
+ url: "https://your-traceway-instance.com/api/otel/v1/traces",
+ headers: { Authorization: "Bearer your-project-token" },
+ }),
+
+ metricReader: new PeriodicExportingMetricReader({
+ exporter: new OTLPMetricExporter({
+ url: "https://your-traceway-instance.com/api/otel/v1/metrics",
+ headers: { Authorization: "Bearer your-project-token" },
+ }),
+ exportIntervalMillis: 30_000,
+ }),
+
+ instrumentations: [getNodeAutoInstrumentations()],
+ });
+
+ sdk.start();
+ }
+}
+```
+
+The `process.env.NEXT_RUNTIME === "nodejs"` guard is required — Next.js runs `instrumentation.ts` in both the Node.js and Edge runtimes, but the OTel Node SDK only works in Node.js. Dynamic `import()` prevents OTel packages from being bundled into the Edge runtime.
+
+## Enabling the Instrumentation Hook (Next.js 13.4–14.x)
+
+For Next.js versions before 15, enable the instrumentation hook in `next.config.js`:
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+ experimental: {
+ instrumentationHook: true,
+ },
+};
+
+module.exports = nextConfig;
+```
+
+This is not needed for Next.js 15+, where the instrumentation hook is stable by default.
+
+## Route Helper (Required)
+
+Next.js (App Router) does not use Express or Fastify under the hood, so the OTel auto-instrumentation cannot set `http.route` automatically. Without it, Traceway falls back to the literal URL path — every unique URL becomes a separate endpoint (e.g., `/api/users/1` and `/api/users/2` instead of `GET /api/users/[id]`).
+
+Create a `withRoute` helper that wraps your API route handlers. It sets `http.route` for endpoint grouping and records exceptions as Issues:
+
+```typescript
+// lib/with-route.ts
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+
+type RouteHandler = (
+ req: Request,
+ context: { params: Promise<Record<string, string>> }
+) => Response | Promise<Response>;
+
+export function withRoute(route: string, handler: RouteHandler): RouteHandler {
+ return async (req, context) => {
+ const span = trace.getActiveSpan();
+ if (span) {
+ span.setAttribute("http.route", route);
+ }
+ try {
+ return await handler(req, context);
+ } catch (error) {
+ if (span) {
+ span.recordException(error as Error);
+ span.setStatus({
+ code: SpanStatusCode.ERROR,
+ message: (error as Error).message,
+ });
+ }
+ throw error;
+ }
+ };
+}
+```
+
+Wrap every API route handler with `withRoute`, passing the route pattern that matches your file path:
+
+```typescript
+// app/api/users/route.ts
+import { withRoute } from "@/lib/with-route";
+
+export const GET = withRoute("/api/users", async () => {
+ const users = await db.users.findAll();
+ return Response.json(users);
+});
+```
+
+```typescript
+// app/api/users/[id]/route.ts
+import { withRoute } from "@/lib/with-route";
+
+export const GET = withRoute("/api/users/[id]", async (req, { params }) => {
+ const { id } = await params;
+ return Response.json({ id, name: "John" });
+});
+```
+
+## What Gets Captured
+
+With the setup above and the `withRoute` helper, OTel captures:
+
+| Layer | What's Captured |
+|-------|-----------------|
+| HTTP server | Incoming requests with method, status code, duration |
+| `withRoute` helper | `http.route` for endpoint grouping + exception recording |
+| Database (pg, mysql2, Prisma, etc.) | Query spans |
+| HTTP client (fetch) | Outgoing HTTP request spans |
+
+Root SERVER spans become **Endpoints** in Traceway (e.g., `GET /api/users/[id]`), child spans become **Spans**, and exception events become **Issues**.
+
+## Environment Variable Alternative
+
+Instead of hardcoding the endpoint and token, you can use standard OTel environment variables:
+
+```bash
+export OTEL_SERVICE_NAME="my-nextjs-app"
+export OTEL_EXPORTER_OTLP_ENDPOINT="https://your-traceway-instance.com/api/otel"
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-project-token"
+```
+
+With these set, the SDK picks them up automatically — your `instrumentation.ts` can omit the exporter URLs and headers.
+
+## Test Your Integration
+
+Add a test API route:
+
+```typescript
+// app/api/test-error/route.ts
+import { withRoute } from "@/lib/with-route";
+
+export const GET = withRoute("/api/test-error", async () => {
+ throw new Error("Test error from Next.js");
+});
+```
+
+Visit `/api/test-error` and check your Traceway dashboard — the error should appear under **Issues** with a full stack trace, and the endpoint should be grouped as `GET /api/test-error`.
+
+## Next Steps
+
+- [Traces](/client/nextjs/traces) — manual spans, Server Component tracing
+- [Node.js OTel Guide](/client/node-sdk) — general Node.js setup details
+- [OTel Overview](/client/otel) — protocol details and authentication
+- [OTel Trace Mapping](/client/otel/traces) — how OTel spans map to Traceway concepts
diff --git a/docs/pages/client/nextjs/traces.mdx b/docs/pages/client/nextjs/traces.mdx
new file mode 100644
index 00000000..143bbb60
--- /dev/null
+++ b/docs/pages/client/nextjs/traces.mdx
@@ -0,0 +1,124 @@
+# Traces
+
+Auto-instrumentation handles HTTP request tracing automatically. This page covers manual span creation and custom instrumentation patterns for Next.js.
+
+## Manual Spans
+
+Use `@opentelemetry/api` to create custom spans for operations that aren't auto-instrumented:
+
+```typescript
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+import { withRoute } from "@/lib/with-route";
+
+const tracer = trace.getTracer("my-nextjs-app");
+
+export const GET = withRoute("/api/orders/[id]", async (req, { params }) => {
+ const { id } = await params;
+
+ return tracer.startActiveSpan("fetch-order", async (span) => {
+ try {
+ span.setAttribute("order.id", id);
+ const order = await db.orders.findById(id);
+
+ if (!order) {
+ span.setStatus({ code: SpanStatusCode.ERROR, message: "Order not found" });
+ span.end();
+ return Response.json({ error: "Not found" }, { status: 404 });
+ }
+
+ span.end();
+ return Response.json(order);
+ } catch (error) {
+ span.recordException(error as Error);
+ span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message });
+ span.end();
+ throw error;
+ }
+ });
+});
+```
+
+## Server Components
+
+Add tracing to React Server Components:
+
+```typescript
+import { trace } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("my-nextjs-app");
+
+export default async function UsersPage() {
+ return tracer.startActiveSpan("UsersPage.render", async (span) => {
+ try {
+ const users = await fetchUsers();
+ span.setAttribute("user.count", users.length);
+
+ return (
+ <ul>
+ {users.map((user) => (
+ <li key={user.id}>{user.name}</li>
+ ))}
+ </ul>
+ );
+ } finally {
+ span.end();
+ }
+ });
+}
+```
+
+Server Component spans appear as **Spans** in Traceway, nested under the parent HTTP request trace.
+
+## Nested Spans
+
+Spans created inside an active span are automatically linked as children:
+
+```typescript
+const tracer = trace.getTracer("my-nextjs-app");
+
+async function processPayment(orderId: string) {
+ return tracer.startActiveSpan("process-payment", async (span) => {
+ try {
+ await validateCard(orderId);
+ await chargeAmount(orderId);
+ span.setStatus({ code: SpanStatusCode.OK });
+ } catch (error) {
+ span.recordException(error as Error);
+ span.setStatus({ code: SpanStatusCode.ERROR });
+ throw error;
+ } finally {
+ span.end();
+ }
+ });
+}
+```
+
+## Recording Exceptions
+
+Use `recordException` on the active span to capture errors as Issues in Traceway:
+
+```typescript
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+
+function riskyOperation() {
+ const span = trace.getActiveSpan();
+
+ try {
+ doSomethingDangerous();
+ } catch (error) {
+ if (span) {
+ span.recordException(error as Error);
+ span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message });
+ }
+ throw error;
+ }
+}
+```
+
+The `recordException` call adds an event with `exception.type`, `exception.message`, and `exception.stacktrace` attributes. Traceway normalizes and hashes the stack trace to group identical errors into a single Issue.
+
+## Next Steps
+
+- [Quick Start](/client/nextjs) — setup and installation
+- [Node.js Traces](/client/node-sdk/traces) — more on manual spans and context propagation
+- [Node.js Metrics](/client/node-sdk/metrics) — custom metrics with OTel
diff --git a/docs/pages/client/otel/index.mdx b/docs/pages/client/otel/index.mdx
index a9f5b873..55d9784c 100644
--- a/docs/pages/client/otel/index.mdx
+++ b/docs/pages/client/otel/index.mdx
@@ -20,7 +20,7 @@ Any language with an OTel SDK can export to Traceway. Here are the most common o
| Python | [opentelemetry-python](https://github.com/open-telemetry/opentelemetry-python) | `pip install opentelemetry-sdk` |
| C# / .NET | [opentelemetry-dotnet](https://github.com/open-telemetry/opentelemetry-dotnet) | `dotnet add package OpenTelemetry` |
| Go | [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go) | `go get go.opentelemetry.io/otel` |
-| Node.js | [opentelemetry-js](https://github.com/open-telemetry/opentelemetry-js) | `npm install @opentelemetry/sdk-node` — see [Node.js guide](/client/node-sdk), [NestJS guide](/client/nestjs), [Hono guide](/client/hono) |
+| Node.js | [opentelemetry-js](https://github.com/open-telemetry/opentelemetry-js) | `npm install @opentelemetry/sdk-node` — see [Node.js guide](/client/node-sdk), [NestJS guide](/client/nestjs), [Hono guide](/client/hono), [Next.js guide](/client/nextjs) |
| PHP / Symfony | [opentelemetry-php](https://github.com/open-telemetry/opentelemetry-php) | `composer require open-telemetry/sdk` — see [Symfony guide](/client/symfony) |
| Cloudflare Workers | [workers-sdk](https://developers.cloudflare.com/workers/observability/otel/) | Built-in — see [Cloudflare guide](/client/otel-cloudflare) |