@ratel-ai/telemetry-otlp

v0.1.1 · TypeScript · npm · source

Generated from the doc comments at ratel-ai/ratel@3be0ecb — do not edit by hand. Regenerate with pnpm sync:api in apps/docs.

@ratel-ai/telemetry-otlp — the OTLP exporter surface for Ratel telemetry.

Turnkey OpenTelemetry SDK wiring over the OTel-free @ratel-ai/telemetry vocabulary. Split out (ADR-0007) so importing the constants never pulls the OTel SDK. Two entry points: init() for a greenfield app where Ratel owns the provider, and ratelSpanProcessor() / ratelTraceExporter() to compose Ratel onto a provider a partner already owns (Langfuse, the Vercel AI SDK, ...). The OTLP config resolver and options are re-exported from @ratel-ai/telemetry for convenience.

Interfaces

InitOptions

init() (in @ratel-ai/telemetry-otlp) resolves endpoint + auth from RATEL_URL / RATEL_API_KEY, with explicit { endpoint, apiKey } values taking precedence over the environment. An explicit apiKey sets the Bearer header; the RATEL_API_KEY fallback only applies when neither apiKey nor an explicit Authorization header is given, so ambient env never overrides an auth header the caller passed on purpose.

Extended by

• TelemetryInitOptions
• RatelSpanProcessorOptions

Properties

apiKey?

optional apiKey?: string

Ratel API key; sent as Authorization: Bearer <apiKey>. Defaults to RATEL_API_KEY.

endpoint?

optional endpoint?: string

Full OTLP traces URL (incl. /v1/traces). Defaults to RATEL_URL.

headers?

optional headers?: Record<string, string>

Extra headers merged onto the request. An explicit Authorization here is kept over the RATEL_API_KEY env fallback.

serviceName?

optional serviceName?: string

service.name resource attribute. Defaults to DEFAULT_SERVICE_NAME.

---

RatelSpanProcessorOptions

Options for ratelSpanProcessor: the OTLP endpoint/auth plus an optional filter.

Extends

• InitOptions

Properties

apiKey?

optional apiKey?: string

Ratel API key; sent as Authorization: Bearer <apiKey>. Defaults to RATEL_API_KEY.

Inherited from

InitOptions.apiKey

enabled?

optional enabled?: boolean

Set false to skip exporter construction and return a no-op processor.

endpoint?

optional endpoint?: string

Full OTLP traces URL (incl. /v1/traces). Defaults to RATEL_URL.

Inherited from

InitOptions.endpoint

headers?

optional headers?: Record<string, string>

Extra headers merged onto the request. An explicit Authorization here is kept over the RATEL_API_KEY env fallback.

Inherited from

InitOptions.headers

serviceName?

optional serviceName?: string

service.name resource attribute. Defaults to DEFAULT_SERVICE_NAME.

Inherited from

InitOptions.serviceName

spanFilter?

optional spanFilter?: SpanFilter

Override the default ratelSignalFilter; () => true forwards every span.

---

ResolvedOtlpConfig

Resolved exporter configuration; the pure core of the OTLP exporter, exposed for testing.

Properties

headers

headers: Record<string, string>

serviceName

serviceName: string

url

url: string

---

TelemetryHandle

Handle returned by init; shutdown() flushes and stops the exporter.

Methods

shutdown()

shutdown(): Promise<void>

Returns

Promise<void>

---

TelemetryInitOptions

Options for the turnkey init path.

Extends

• InitOptions

Properties

apiKey?

optional apiKey?: string

Ratel API key; sent as Authorization: Bearer <apiKey>. Defaults to RATEL_API_KEY.

Inherited from

InitOptions.apiKey

enabled?

optional enabled?: boolean

On first setup, set false to skip configuration and provider registration.

endpoint?

optional endpoint?: string

Full OTLP traces URL (incl. /v1/traces). Defaults to RATEL_URL.

Inherited from

InitOptions.endpoint

headers?

optional headers?: Record<string, string>

Extra headers merged onto the request. An explicit Authorization here is kept over the RATEL_API_KEY env fallback.

Inherited from

InitOptions.headers

serviceName?

optional serviceName?: string

service.name resource attribute. Defaults to DEFAULT_SERVICE_NAME.

Inherited from

InitOptions.serviceName

spanFilter?

optional spanFilter?: SpanFilter

Override the default filter; init() forwards every span when omitted.

Type Aliases

SpanFilter

SpanFilter = (span) => boolean

Predicate deciding whether a finished span is forwarded to Ratel.

Parameters

Returns

boolean

Variables

API_KEY_ENV

const API_KEY_ENV: "RATEL_API_KEY" = "RATEL_API_KEY"

Env var whose value is the default Ratel API key.

---

DEFAULT_SERVICE_NAME

const DEFAULT_SERVICE_NAME: "ratel" = "ratel"

service.name used when the caller does not pass one.

---

ENDPOINT_ENV

const ENDPOINT_ENV: "RATEL_URL" = "RATEL_URL"

Env var whose value is the default OTLP endpoint.

Functions

init()

init(opts?): TelemetryHandle

Wire an OTLP http/protobuf exporter + batch processor + service.name resource over a NodeTracerProvider, register it as the global provider, and return a shutdown handle. Everything else is the untouched OTel SDK.

init() owns the global provider, so it exports every span by default (unlike ratelSpanProcessor, whose default gen_ai.*/ratel.* filter exists for sharing a provider). Pass spanFilter to narrow that set, or enabled: false for a no-op handle on first setup. Repeated calls return the existing handle when Ratel already owns the active provider—even if a later caller is disabled—so shutting that handle down stops export for every caller. It throws with a pointer to ratelSpanProcessor when a foreign provider is registered. Shutdown is terminal: after handle.shutdown(), a later init() throws rather than hand back the dead handle (call trace.disable() first to re-initialize).

Parameters

Returns

TelemetryHandle

---

ratelSignalFilter()

ratelSignalFilter(span): boolean

Default filter: forward only signal-bearing spans — a ratel.* span name, or any attribute key under gen_ai.* / ratel.*. This is what lets Ratel share a provider with e.g. Langfuse + the Vercel AI SDK and ingest only the gen_ai/ratel signal (the AI SDK's gen_ai.* spans + Ratel's own ratel.search / execute_tool), dropping the framework's ai.* wrapper noise.

Parameters

Returns

boolean

---

ratelSpanProcessor()

ratelSpanProcessor(opts?): SpanProcessor

A BatchSpanProcessor over the Ratel OTLP exporter that forwards only the spans passing RatelSpanProcessorOptions.spanFilter (default ratelSignalFilter). Add it to your own provider's spanProcessors to send Ratel telemetry alongside another provider — no global side effects, no resource. Greenfield apps that want Ratel to own the provider should call init instead. enabled: false returns a no-op processor before resolving endpoint/auth configuration.

Parameters

Returns

SpanProcessor

---

ratelTraceExporter()

ratelTraceExporter(opts?): OTLPTraceExporter

Build the OTLP http/protobuf trace exporter at the resolved Ratel endpoint. The standalone exporter for callers wiring their own span-processor; ratelSpanProcessor batches over it. Carries no resource — the caller's provider owns service.name.

Parameters

Returns

OTLPTraceExporter

---

resolveOtlpConfig()

resolveOtlpConfig(opts?, env?): ResolvedOtlpConfig

Resolve InitOptions into concrete exporter config. Pure and env-injectable so the endpoint/auth precedence is testable without a network.

Parameters

Returns

ResolvedOtlpConfig