Skip to main content

​
Browser telemetry quickstart

Install the browser package and start telemetry once during application boot. 
pnpm add @aient/otel-browser

import { registerOTelBrowser } from '@aient/otel-browser'

registerOTelBrowser({
  publishableKey: import.meta.env.VITE_AIENT_PUBLISHABLE_KEY,
  serviceName: 'web',
  release: {
    commit: import.meta.env.VITE_COMMIT_SHA,
    branch: import.meta.env.VITE_COMMIT_REF,
    environment: import.meta.env.MODE,
  },
})

​
React and Next.js

Browsers only: call registerOTelBrowser from a client component after mount (not during render). Initialize once, then call setUserContext when the signed-in user changes so traces stay correlated without re-creating the SDK. 
'use client'

import { useEffect, useRef } from 'react'
import { registerOTelBrowser, type BrowserSDK } from '@aient/otel-browser'

export function TelemetryInit({ userId }: { userId?: string | null }) {
  const sdkRef = useRef<BrowserSDK | null>(null)

  useEffect(() => {
    const sdk = registerOTelBrowser({
      publishableKey: process.env.NEXT_PUBLIC_AIENT_PUBLISHABLE_KEY!,
      serviceName: process.env.NEXT_PUBLIC_OTEL_SERVICE_NAME ?? 'web',
      release: {
        commit: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA ?? 'dev',
        branch: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF ?? 'local',
        environment: process.env.NEXT_PUBLIC_VERCEL_ENV ?? 'development',
      },
    })
    sdkRef.current = sdk
    return () => {
      void sdk.shutdown()
    }
  }, [])

  useEffect(() => {
    sdkRef.current?.setUserContext(userId ? { userId } : null)
  }, [userId])

  return null
}
In the App Router, render <TelemetryInit userId={user?.id} /> from app/layout.tsx (or a client shell) so the server can pass the current user id into the client tree. For the Pages Router, mount the same component under _app. Use NEXT_PUBLIC_* only for values that are safe to expose to the browser (the publishable key is designed for that).

​
Release metadata

Use the same serviceName and release.commit when uploading source maps. That lets Aient connect browser stack frames to the correct original source.

​
Privacy

Do not attach secrets, auth tokens, raw request bodies, or user-entered sensitive content to spans or logs. Publishable keys identify only the Aient environment and are safe for browser code. When you call setUserContext, the SDK only propagates enduser.pseudo.id to downstream services as W3C baggage. Trusted identity (enduser.id), email, and role stay on local browser spans and are not sent over the wire; Aient backends derive the authenticated user from your server session instead. See the SDK reference for details.

​
Transport

@aient/otel-browser sends OTLP HTTP JSON payloads. http/protobuf is not bundled; legacy protobuf config falls back to JSON.