The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
more docs updates
dduxaa78d60d8328
diff --git a/docs/pages/client/_meta.json b/docs/pages/client/_meta.jsonindex 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.mdxindex 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:+```typescriptimport { 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 Alternativediff --git a/docs/pages/client/hono/traces.mdx b/docs/pages/client/hono/traces.mdxindex 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:```typescriptdiff --git a/docs/pages/client/nextjs/_meta.json b/docs/pages/client/nextjs/_meta.jsonnew file mode 100644index 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.mdxnew file mode 100644index 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 conceptsdiff --git a/docs/pages/client/nextjs/traces.mdx b/docs/pages/client/nextjs/traces.mdxnew file mode 100644index 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 OTeldiff --git a/docs/pages/client/otel/index.mdx b/docs/pages/client/otel/index.mdxindex 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) |