Sign Up
Open in ChatGPT Open in Claude Open in Perplexity

NextJs Integration Guide

The monoscope Next.js SDK lets you monitor HTTP requests in your Next.js applications. It builds upon OpenTelemetry instrumentation to create custom spans for each request, capturing key details such as request and response bodies, headers, and status codes. It also monitors outgoing requests and reports errors.

To get started, you’ll need the OpenTelemetry Node.js library and some basic configuration.


Prerequisites

You need a monoscope project and its API key. If you do not have them yet, follow Get started.

Set Up With Your Coding Agent

Your coding agent can add the instrumentation for you. Install the monoscope skills and the monoscope CLI:

# Claude Code
claude plugin marketplace add monoscope-tech/skills
claude plugin install monoscope-skills@monoscope-skills

# Cursor, Codex, Cline and other agents
npx skills add monoscope-tech/skills

# monoscope CLI
curl https://monoscopehq.com/install.sh | sh
monoscope auth login

Then ask your agent to instrument the project. In Claude Code, run:

/monoscope-skills:instrument Add OpenTelemetry for monoscope to this project

The skill uses the CLI to add the SDK and to make sure that events arrive. To do the setup by hand, follow the steps below. For help from a person, email us.

Installation

Install the monoscope Next.js SDK, the OpenTelemetry API and @vercel/otel:

npm install --save @monoscopetech/next @opentelemetry/api @vercel/otel

Set Up OpenTelemetry

OpenTelemetry sends traces, metrics and logs to monoscope. Add these environment variables to your .env file:

OTEL_EXPORTER_OTLP_ENDPOINT="http://otelcol.monoscope.tech:4318"
OTEL_SERVICE_NAME="my-service" # Specifies the name of the service.
OTEL_RESOURCE_ATTRIBUTES="x-api-key=YOUR_API_KEY" # Adds your API KEY to the resource.
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" #Specifies the protocol to use for the OpenTelemetry exporter.

Register OpenTelemetry in instrumentation.ts

Create instrumentation.ts (or .js) in your project root, or in src if you use a src directory:

import { registerOTel } from "@vercel/otel";

export function register() {
  registerOTel("{YOUR_PROJECT_NAME}");
}

HTTP Requests Monitoring

The monoscope wrappers record headers, response time, status code and request and response bodies for each request.

Wrap your routes with withMonoscopeAppRouter for the App Router, or withMonoscopePagesRouter for the Pages Router.

App Router Example

import { withMonoscopeAppRouter } from "@monoscopetech/next";
import { NextRequest, NextResponse } from "next/server";
async function handleRequest(req: NextRequest) {
  return NextResponse.json({ message: "hello world" });
}

// Optional configuration
const config = {
  captureResponseBody: true,
}
export const GET = withMonoscopeAppRouter(handleRequest, config);

Pages Router Example

import type { NextApiRequest, NextApiResponse } from "next";
import { withMonoscopePagesRouter } from "@monoscopetech/next";

function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ message: "Hello from Next.js!" });
}

// Optional configuration
const config = {
  captureResponseBody: true,
}

export default withMonoscopePagesRouter(handler, config);

Configuration Options

Pass an object with these optional fields as the second argument of the wrapper:

Option Description
debug Set to true to enable debug mode.
serviceName A defined string name of your application.
tags A list of defined tags for your services (used for grouping and filtering data on the dashboard).
serviceVersion A defined string version of your application (used for further debugging on the dashboard).
redactHeaders A list of HTTP header keys to redact. authorization, cookie, set-cookie and proxy-authorization are always redacted.
redactResponseBody A list of JSONPaths from the response body to redact.
redactRequestBody A list of JSONPaths from the request body to redact.
captureRequestBody Default false, set to true if you want to capture the request body.
captureResponseBody Default false, set to true if you want to capture the response body.

Reporting Errors

monoscope detects many API issues automatically. Reporting errors adds backend context to a failing request, as Sentry or Bugsnag do. To report an error, call reportError.

import { NextRequest, NextResponse } from "next/server";
import { withMonoscopeAppRouter, reportError } from "@monoscopetech/next";
async function handleRequest(req: NextRequest) {
  try {
    throw new Error("Something went wrong");
  } catch (e) {
    // reportError sends the error to monoscope
    reportError(e);
  }

  return NextResponse.json({ message: "hello world" });
}

export const GET = withMonoscopeAppRouter(handleRequest);

Identifying users & tenants

Attach the authenticated user and tenant to every request span so you can filter, group, and search by identity in the dashboard (e.g. “all errors for user.email = [email protected]”). Call setUser and setTenant from inside a route handler that’s wrapped with withMonoscopeAppRouter or withMonoscopePagesRouter — the SDK writes them to the active request span using the standard attribute keys (user.id, user.email, user.full_name, tenant.id, tenant.name).

import { withMonoscopeAppRouter, setUser, setTenant } from "@monoscopetech/next";
import { NextResponse } from "next/server";
import { getSession } from "@/lib/auth";

async function handler() {
  const session = await getSession();
  if (session?.user) {
    setUser({
      id: session.user.id,
      email: session.user.email,
      name: session.user.name,
    });
    setTenant({ id: session.user.orgId, name: session.user.orgName });
  }
  return NextResponse.json({ ok: true });
}

export const GET = withMonoscopeAppRouter(handler);

Both helpers skip undefined/null fields, so partial info is fine. They must run inside a handler wrapped by withMonoscopeAppRouter/withMonoscopePagesRouter — calls outside that scope are log a warning and do nothing.

Tracking Sessions

If you use the monoscope browser SDK on your frontend, session.id is propagated and tagged automatically — no Next.js code required. The browser SDK injects the W3C baggage header on every outbound fetch/XHR, and the monoscope wrapper extracts it and tags the request span under the standard OTel session.id attribute.

For server-only sessions (server components without the browser SDK, or your own session scheme), set the session ID alongside user and tenant on the active request span. The three together — who, which org, which session — are what makes a trace searchable and replayable in the dashboard:

import { withMonoscopeAppRouter, setUser, setTenant, setSession } from "@monoscopetech/next";
import { getSession } from "@/lib/auth";

async function handler() {
  const session = await getSession();
  if (session?.user) {
    setUser({ id: session.user.id, email: session.user.email, name: session.user.name });
    setTenant({ id: session.user.orgId, name: session.user.orgName });
  }
  if (session?.id) setSession(session.id);
  // ...
}

export const GET = withMonoscopeAppRouter(handler);

setSession writes the standard session.id attribute to the active request span. Calls outside a wrapped handler are no-ops.

Monitoring Axios Requests

To monitor a specific outgoing Axios request, use the observeAxios function.

import { NextRequest, NextResponse } from "next/server";
import { withMonoscopeAppRouter, observeAxios } from "@monoscopetech/next";

async function handleRequest(req: NextRequest) {
  // Observe an Axios request
  const response = await observeAxios({
    urlWildcard: "/todos/:id",
  }).get("https://jsonplaceholder.typicode.com/todos/1");

  return NextResponse.json({ data: response.data });
}

export const GET = withMonoscopeAppRouter(handleRequest);

Use urlWildcard for URLs with dynamic path parameters. It lets monoscope group requests to the same endpoint.

All observeAxios Options

Below is the full list of options for the observeAxios function:

Option Description
urlWildcard optional The route pattern of the url if it has dynamic path parameters.
redactHeaders A list of HTTP header keys to redact. authorization, cookie, set-cookie and proxy-authorization are always redacted.
redactResponseBody A list of JSONPaths from the response body to redact.
redactRequestBody A list of JSONPaths from the request body to redact.

Non-HTTP Entry Points (Background Jobs, Workers, CLIs)

The Next.js wrapper only covers route handlers and pages. Server Actions, Vercel Cron jobs (/api/cron/* triggered externally are still HTTP, but anything running outside the request cycle is not), separate worker processes, and CLI scripts are invisible until you wrap each handler in a span yourself. Always instrument these alongside your HTTP routes.

Use the standard OpenTelemetry tracer API directly inside the worker / cron handler. Auto-instrumentation picks up downstream HTTP/database calls automatically once a parent span is active.

// worker.ts — separate process started via `node worker.js`
import { trace, SpanStatusCode } from "@opentelemetry/api";
import { Worker } from "bullmq";

const tracer = trace.getTracer("my-service-worker");

new Worker("emails", async (job) => {
  return tracer.startActiveSpan(
    `email.${job.name}`,
    {
      attributes: {
        "messaging.system": "bullmq",
        "messaging.operation": "process",
        "messaging.destination.name": "emails",
        "messaging.message.id": job.id,
        "code.function": job.name,
      },
    },
    async (span) => {
      try {
        await sendEmail(job.data);
        span.setStatus({ code: SpanStatusCode.OK });
      } catch (err) {
        span.recordException(err as Error);
        span.setStatus({ code: SpanStatusCode.ERROR });
        throw err;
      } finally {
        span.end();
      }
    }
  );
});

For Server Actions called outside a normal request ('use server' in a background context), the same tracer.startActiveSpan wrapper applies. For CLI / one-shot scripts, call await sdk.shutdown() before the process exits so the BatchSpanProcessor flushes; otherwise spans are dropped silently.

Next Steps


Explore the NextJs SDK