Browser / React

Instrument your frontend applications (React, Vue, Angular, vanilla JS) to send traces to Kopai.

Token Types

Kopai provides two token types:

Token	Use for	Visibility
Backend	Server-side apps	keep secret
Frontend	Browser apps	safe to expose

Frontend tokens are designed to be embedded in your frontend JS app bundle.

Installation

npm install @opentelemetry/api \
  @opentelemetry/sdk-trace-web \
  @opentelemetry/context-zone \
  @opentelemetry/instrumentation \
  @opentelemetry/instrumentation-document-load \
  @opentelemetry/instrumentation-fetch \
  @opentelemetry/exporter-trace-otlp-http

React Setup

Create src/instrumentation.js:

import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { ZoneContextManager } from "@opentelemetry/context-zone";
import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
import { DocumentLoadInstrumentation } from "@opentelemetry/instrumentation-document-load";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { resourceFromAttributes } from "@opentelemetry/resources";
import {
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
} from "@opentelemetry/semantic-conventions";

export function setupInstrumentation() {
  const resource = resourceFromAttributes({
    [ATTR_SERVICE_NAME]: "my-react-app",
    [ATTR_SERVICE_VERSION]: "1.0.0",
  });

  const exporter = new OTLPTraceExporter({
    url: "https://otlp-http.kopai.app/v1/traces",
    headers: {
      Authorization: `Bearer ${import.meta.env.VITE_KOPAI_TOKEN}`,
    },
  });

  const provider = new WebTracerProvider({
    resource,
    spanProcessors: [new BatchSpanProcessor(exporter)],
  });

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

  registerInstrumentations({
    instrumentations: [
      new DocumentLoadInstrumentation(),
      new FetchInstrumentation({
        propagateTraceHeaderCorsUrls: [/.+/g],
      }),
    ],
  });
}

Initialize in main.jsx:

import { setupInstrumentation } from "./instrumentation";

setupInstrumentation();

// ... rest of your app

Environment Variables

Store your token in environment variables:

.env

VITE_KOPAI_TOKEN=your_frontend_token

Bundler	Prefix	Access
Vite	VITE_	import.meta.env.VITE_*
Create React App	REACT_APP_	process.env.REACT_APP_*
Next.js	NEXT_PUBLIC_	process.env.NEXT_PUBLIC_*

Auto-Instrumentation

The setup above automatically captures:

• Document load - Page load timing, resources
• Fetch requests - All HTTP calls with timing
• Trace propagation - Links frontend to backend traces

Working Example

For a complete working example with React frontend and Express backend:

React SPA Example

Troubleshooting

No traces appearing

1. Check browser DevTools → Network for requests to otlp-http.kopai.app
2. Verify token format: Authorization: Bearer <token>
3. Check console for CORS errors

401 Unauthorized

• Verify token is correct (no extra spaces)
• Check Bearer prefix is included

CORS errors

• Your origin must be in the token’s allowed origins