obserfable-otel

Frontend browser monitoring SDK that auto-instruments your app and exports telemetry to any OpenTelemetry-compatible backend.

Install

npm install obserfable-otel
# or
pnpm add obserfable-otel

Quick Start

Call setupObserfable() once at your app's entry point before anything else runs.

import { setupObserfable, startSpan, obserfableLogger } from 'obserfable-otel'

setupObserfable({
  serviceName: 'my-app',
  endpoint: 'https://ingest.signoz.io',
  headers: { 'signoz-access-token': 'your-token' },
  environment: 'production',
})

// Manual tracing
const span = startSpan('checkout', { 'cart.items': 3 })
await processPayment()
span.end()

// Logging
obserfableLogger.info('Payment completed', { orderId: '123' })

Auto-instrumentation starts immediately after setupObserfable() — no extra code needed for fetch, XHR, page load, errors, and web vitals.

Config Options

| Option | Type | Required | Default | Description | |---|---|---|---|---| | serviceName | string | Yes | — | Identifies your service in the backend | | endpoint | string | Yes | — | Base OTLP endpoint URL (e.g. https://ingest.signoz.io) | | headers | Record<string, string> | No | {} | Auth headers sent with every export request | | environment | string | No | — | Deployment environment (e.g. production, staging) | | debug | boolean | No | false | Enables SDK-level console logging | | sampleRate | number | No | 1.0 | Trace sample rate between 0.0 and 1.0 | | autoInstrumentationOptions | AutoInstrumentationType[] | No | All enabled | Select which auto-instrumentations to activate | | propagateTraceHeaderCorsUrls | Array<string \| RegExp> | No | [] | URLs that should receive traceparent headers on cross-origin requests | | userInteractionEvents | (keyof HTMLElementEventMap)[] | No | ['click', 'submit'] | DOM events to auto-trace when user-interaction is enabled |

autoInstrumentationOptions values

| Value | What it instruments | |---|---| | fetch | window.fetch outgoing requests | | xhr | XMLHttpRequest outgoing requests | | document-load | Page load and resource timing | | errors | window.onerror and unhandled promise rejections | | web-vitals | LCP, CLS, INP, FCP, TTFB | | user-interaction | DOM events (click, submit, etc.) |

Supported Backends

Any OTLP/HTTP-compatible backend works. The endpoint you provide receives signal-specific paths automatically:

| Backend | Endpoint example | |---|---| | SigNoz | https://ingest.<region>.signoz.cloud:443 | | Grafana Tempo | https://<host>/otlp | | Jaeger | http://localhost:4318 | | Honeycomb | https://api.honeycomb.io | | OpenTelemetry Collector | http://localhost:4318 |

License

MIT