# Browser / React

Instrument browser applications with OpenTelemetry

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:**

```bash
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
```

**pnpm:**

```bash
pnpm add @opentelemetry/api \
  @opentelemetry/sdk-trace-web \
  @opentelemetry/context-zone \
  @opentelemetry/instrumentation \
  @opentelemetry/instrumentation-document-load \
  @opentelemetry/instrumentation-fetch \
  @opentelemetry/exporter-trace-otlp-http
```

**yarn:**

```bash
yarn add @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`:

```javascript
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`:

```jsx
import { setupInstrumentation } from "./instrumentation";

setupInstrumentation();

// ... rest of your app
```

## Environment Variables

Store your token in environment variables:

```bash
# .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](https://github.com/kopai-app/kopai-integration-examples/tree/main/react-spa)**

## 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