@aient/otel-browser

@aient/otel-browser sends browser traces and logs to Aient using public OTLP HTTP endpoints. Use a publishable key and release metadata from your build environment. For React or Next.js (client mount, identify/clearUser, and cleanup), see the browser quickstart.

Configuration

Option	Meaning
`publishableKey`	Aient environment publishable key safe for browser code
`serviceName`	Frontend service name; match source map uploads
`installationId`	Caller-owned application installation ID, emitted as a resource and untrusted baggage correlation field
`attributes`	Static resource attributes fixed for the SDK lifetime
`contextAttributes`	Initial mutable string context for future spans and outgoing baggage
`release.environment`	Deployment environment slug
`release.commit`	Build commit SHA; match source map uploads
`release.branch`	Build branch or ref for release correlation
`exporterUrl`	Optional base endpoint override; the SDK appends `/v1/traces` and `/v1/logs`
`exporterHeaders`	Optional custom exporter headers merged with Aient auth
`logs.exporterUrl`	Optional logs-specific endpoint override

The SDK sends OTLP HTTP JSON payloads. http/protobuf is not bundled; legacy protobuf config falls back to JSON. Avoid high-cardinality span names and avoid attaching sensitive user input to attributes.

Dynamic context

Call sdk.setContextAttributes() after a business, account, or workspace switch. The call synchronously replaces the whole snapshot; null or an empty object clears it. sdk.getContextAttributes() returns a clone.

sdk.setContextAttributes({
  'business.id': 'business_123',
  'workspace.id': 'workspace_456',
})

// Clear on logout
sdk.setContextAttributes(null)

Future spans capture the current snapshot at span start; in-flight and ended spans are not changed retroactively. Outgoing Fetch/XHR baggage preserves unrelated entries and replaces SDK-owned keys. All enduser.* keys and app.installation.id are omitted from generic context. Browser context and baggage are untrusted telemetry correlation data. Never use them for authorization; downstream services must derive identity and access from trusted server-side sessions or credentials.

User context and baggage

Call sdk.identify({ userId, pseudoId, email, role }) after sign-in to replace the complete user snapshot and tag future browser spans/logs. Call sdk.clearUser() on sign-out. sdk.getIdentity() returns a clone containing the installation plus current user fields. The legacy user-context methods remain aliases. app.installation.id, enduser.id, and enduser.pseudo.id may propagate as W3C baggage. They are correlation hints, not authentication. Email and role do not propagate. Aient backends derive authenticated enduser.id from the verified server session and overwrite the browser value before downstream work. Use a stable, non-reversible hash (for example, an HMAC of the user id with a server-side secret) for pseudoId so you can correlate sessions without exposing PII.

sdk.identify({
  userId: 'user_123',          // untrusted baggage correlation
  pseudoId: 'pseudo_abc',      // untrusted baggage correlation
  email: '[email protected]',   // local span attribute only
  role: 'admin',               // local span attribute only
})

Reference

Changelog

@aient/otel-browser SDK reference

@aient/otel-browser

Configuration

Dynamic context

User context and baggage

​@aient/otel-browser

​Configuration

​Dynamic context

​User context and baggage

@aient/otel-browser

Configuration

Dynamic context

User context and baggage