Next.js

Browser (RUM SDK or OTel web SDK)
   │  fetch / navigation  ── traceparent header ──┐
   ▼                                              ▼
Next.js server (OTel for Node.js) ── DB, Redis, downstream HTTP calls
   │  OTLP/HTTP
   ▼
KubeSense trace ingest (kubesense-kubecol:33443) → APM → Traces, Services, Service Map

spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-nodejs: "kubesense/otel-instrumentation"
    spec:
      containers:
        - name: web
          image: <YOUR_REGISTRY>/storefront:1.0.0
          env:
            - name: OTEL_SERVICE_NAME
              value: storefront

kubectl rollout restart deployment/storefront -n <namespace>

npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node

export OTEL_SERVICE_NAME=storefront
export OTEL_EXPORTER_OTLP_ENDPOINT=http://<KUBESENSE_INGEST_HOST>:33443
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_RESOURCE_ATTRIBUTES=kubesense.cluster=<CLUSTER_NAME>,kubesense.env_type=legacy
export OTEL_NODE_RESOURCE_DETECTORS=env,host,os,process
export OTEL_NODE_DISABLED_INSTRUMENTATIONS=fs,dns,net
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"

npx next start

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

// instrumentation.ts (project root, or src/)
import { registerOTel, OTLPHttpProtoTraceExporter } from '@vercel/otel';

export function register() {
  registerOTel({
    serviceName: process.env.OTEL_SERVICE_NAME ?? 'storefront',
    attributes: {
      'kubesense.cluster': '<CLUSTER_NAME>',
      'kubesense.env_type': 'k8s', // 'legacy' on VMs
    },
    traceExporter: new OTLPHttpProtoTraceExporter({
      // Full URL including /v1/traces
      url: process.env.KUBESENSE_TRACES_URL ??
        'http://kubesense-kubecol.kubesense.svc.cluster.local:33443/v1/traces',
    }),
  });
}

export OTEL_SERVICE_NAME=storefront
export KUBESENSE_TRACES_URL=http://kubesense-kubecol.kubesense.svc.cluster.local:33443/v1/traces

npm run build && npm start

npm install --save @opentelemetry/instrumentation-pg @opentelemetry/instrumentation-ioredis

import { registerOTel, OTLPHttpProtoTraceExporter } from '@vercel/otel';
import { PgInstrumentation } from '@opentelemetry/instrumentation-pg';
import { IORedisInstrumentation } from '@opentelemetry/instrumentation-ioredis';

export function register() {
  registerOTel({
    serviceName: process.env.OTEL_SERVICE_NAME ?? 'storefront',
    attributes: { 'kubesense.cluster': '<CLUSTER_NAME>', 'kubesense.env_type': 'k8s' },
    traceExporter: new OTLPHttpProtoTraceExporter({ url: process.env.KUBESENSE_TRACES_URL }),
    // 'auto' keeps the default fetch and HTTP instrumentation
    instrumentations: ['auto', new PgInstrumentation(), new IORedisInstrumentation()],
  });
}

npm install --save @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node

// instrumentation.ts (project root, or src/)
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation.node');
  }
}

// instrumentation.node.ts
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

// The exporter, endpoint, service name and resource attributes
// are configured from the OTEL_* environment variables.
const sdk = new NodeSDK({
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-fs': { enabled: false },
    }),
  ],
});

sdk.start();

// next.config.js (Next.js 15; in 13.2 to 14, use experimental.serverComponentsExternalPackages)
module.exports = {
  serverExternalPackages: ['@opentelemetry/sdk-node', '@opentelemetry/auto-instrumentations-node'],
};

OTEL_SERVICE_NAME=storefront
OTEL_EXPORTER_OTLP_ENDPOINT=http://kubesense-kubecol.kubesense.svc.cluster.local:33443
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_RESOURCE_ATTRIBUTES=kubesense.cluster=<CLUSTER_NAME>,kubesense.env_type=k8s
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none

// app/checkout/actions.ts
'use server';
import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('storefront');

export async function placeOrder(cartId: string) {
  return tracer.startActiveSpan('placeOrder', async (span) => {
    try {
      span.setAttribute('cart.id', cartId);
      return await submitOrder(cartId);
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw err;
    } finally {
      span.end();
    }
  });
}

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build          # next.config.js sets output: 'standalone'

FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

npm install @kubesense/kubesense-browser-rum

// instrumentation-client.ts
import { kubesenseSdk } from '@kubesense/kubesense-browser-rum';

kubesenseSdk.init({
  applicationId: process.env.NEXT_PUBLIC_KUBESENSE_RUM_APP_ID!,
  clientToken: process.env.NEXT_PUBLIC_KUBESENSE_RUM_CLIENT_TOKEN!,
  kubesenseRumEndpoint: '<YOUR_KUBESENSE_RUM_ENDPOINT>',
  service: 'storefront-web',
  env: 'production',
  version: process.env.NEXT_PUBLIC_APP_VERSION,
  sessionSampleRate: 100,
  trackUserInteractions: true,
  trackResources: true,
  trackLongTasks: true,
  // Link browser requests to server traces. Include your own API domains.
  allowedTracingUrls: [
    {
      match: (url: string) => url.startsWith(window.location.origin),
      propagatorTypes: ['tracecontext'],
    },
    { match: /https:\/\/api\.example\.com/, propagatorTypes: ['tracecontext'] },
  ],
  traceSampleRate: 100,
});

// app/kubesense-rum.tsx
'use client';
import { kubesenseSdk } from '@kubesense/kubesense-browser-rum';

if (typeof window !== 'undefined') {
  kubesenseSdk.init({
    // same options as above
  });
}

export function KubesenseRum() {
  return null;
}

// app/layout.tsx
import { KubesenseRum } from './kubesense-rum';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <KubesenseRum />
        {children}
      </body>
    </html>
  );
}

// pages/_app.tsx (Pages Router), or instrumentation-client.ts (Next.js 15.3+)
import { datadogRum } from '@datadog/browser-rum';

datadogRum.init({
  applicationId: process.env.NEXT_PUBLIC_RUM_APPLICATION_ID!,   // KubeSense application ID
  clientToken: process.env.NEXT_PUBLIC_RUM_CLIENT_TOKEN!,       // KubeSense client token
  site: 'datadoghq.com',                                         // required by the SDK; not used with proxy
  proxy: 'https://<KUBESENSE_RUM_HOST>/api/v2/proxy',
  service: 'storefront-web',
  env: 'production',
  version: process.env.NEXT_PUBLIC_APP_VERSION,
  sessionSampleRate: 100,
  sessionReplaySampleRate: 20,
  trackUserInteractions: true,
  trackResources: true,
  trackLongTasks: true,
  // Link browser requests to the OpenTelemetry server traces
  allowedTracingUrls: [
    { match: (url: string) => url.startsWith(window.location.origin), propagatorTypes: ['tracecontext'] },
    { match: /https:\/\/api\.example\.com/, propagatorTypes: ['tracecontext'] },
  ],
});

npm install --save @opentelemetry/api @opentelemetry/sdk-trace-web @opentelemetry/sdk-trace-base \
  @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/instrumentation \
  @opentelemetry/instrumentation-fetch @opentelemetry/instrumentation-xml-http-request \
  @opentelemetry/instrumentation-user-interaction @opentelemetry/context-zone

// app/api/otel/v1/traces/route.ts
const TARGET =
  process.env.KUBESENSE_TRACES_URL ??
  'http://kubesense-kubecol.kubesense.svc.cluster.local:33443/v1/traces';

const MAX_BYTES = 1_000_000;

export async function POST(req: Request) {
  const body = await req.arrayBuffer();
  if (body.byteLength > MAX_BYTES) {
    return new Response(null, { status: 413 });
  }
  const res = await fetch(TARGET, {
    method: 'POST',
    headers: { 'Content-Type': req.headers.get('content-type') ?? 'application/json' },
    body,
    cache: 'no-store',
  });
  return new Response(null, { status: res.status });
}

// instrumentation-client.ts (Next.js 15.3+), or a 'use client' module as shown for RUM
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { BatchSpanProcessor, TraceIdRatioBasedSampler, ParentBasedSampler } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch';
import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';
import { UserInteractionInstrumentation } from '@opentelemetry/instrumentation-user-interaction';
import { ZoneContextManager } from '@opentelemetry/context-zone';

const provider = new WebTracerProvider({
  resource: resourceFromAttributes({
    'service.name': 'storefront-web',
    'kubesense.cluster': '<CLUSTER_NAME>',
    'kubesense.env_type': 'k8s',
  }),
  // Keep 10% of page traces; adjust to your traffic
  sampler: new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(0.1) }),
  spanProcessors: [
    new BatchSpanProcessor(
      new OTLPTraceExporter({ url: `${window.location.origin}/api/otel/v1/traces` }),
    ),
  ],
});

provider.register({ contextManager: new ZoneContextManager() });

// Requests that should carry the traceparent header: your own origin and your APIs.
// Don't use /.*/: third-party APIs reject the extra header in their CORS preflight.
const propagateTraceHeaderCorsUrls = [/https:\/\/api\.example\.com/];
const ignoreUrls = [/\/api\/otel\//];

registerInstrumentations({
  instrumentations: [
    new FetchInstrumentation({ propagateTraceHeaderCorsUrls, ignoreUrls }),
    new XMLHttpRequestInstrumentation({ propagateTraceHeaderCorsUrls, ignoreUrls }),
    new UserInteractionInstrumentation({ eventNames: ['click', 'submit'] }),
  ],
});