@lazarv/react-server/telemetry

OpenTelemetry integration. Safe no-op when OpenTelemetry packages are not installed — import getTracer, getMeter, withSpan, and friends directly without guarding.

function getMeter(): Meter;

Get the active OpenTelemetry meter. Returns a no-op meter when telemetry is disabled.

function getMetrics(): {
    httpRequestDuration: {
        record(value: number, attributes?: Record<string, string | number>): void;
    };
    httpActiveRequests: {
        add(value: number, attributes?: Record<string, string | number>): void;
    };
    rscRenderDuration: {
        record(value: number, attributes?: Record<string, string | number>): void;
    };
    domRenderDuration: {
        record(value: number, attributes?: Record<string, string | number>): void;
    };
    actionDuration: {
        record(value: number, attributes?: Record<string, string | number>): void;
    };
    cacheHits: {
        add(value: number, attributes?: Record<string, string | number>): void;
    };
    cacheMisses: {
        add(value: number, attributes?: Record<string, string | number>): void;
    };
} | null;

Built-in metrics instruments. Returns null when telemetry is disabled.

function getOtelContext(): Context | null;

Get the OTel context for the current request.

function getSpan(): Span;

Get the current request span from the per-request context. Returns a no-op span when telemetry is disabled or called outside a request.

function getTracer(): Tracer;

Get the active OpenTelemetry tracer. Returns a no-op tracer when telemetry is disabled.

function injectTraceContext(headers: Headers): Promise<void>;

Inject W3C trace context into outgoing response headers. Useful when making downstream HTTP calls that should be correlated.

function withSpan<T>(name: string, fn: (span: Span) => Promise<T> | T): Promise<T>;
function withSpan<T>(name: string, attributes: Record<string, string | number | boolean>, fn: (span: Span) => Promise<T> | T): Promise<T>;

Execute fn within a child span of the current request span.

Parameters

• name — Span name
• fn — Function to execute inside the span

Returns — The return value of fn

import { withSpan } from "@lazarv/react-server/telemetry";

const result = await withSpan("db.query", async (span) => {
  span.setAttribute("db.system", "postgres");
  return await db.query("SELECT ...");
});

interface Meter {
    createCounter(name: string, options?: unknown): {
        add(value: number, attributes?: Record<string, unknown>): void;
    };
    createHistogram(name: string, options?: unknown): {
        record(value: number, attributes?: Record<string, unknown>): void;
    };
    createUpDownCounter(name: string, options?: unknown): {
        add(value: number, attributes?: Record<string, unknown>): void;
    };
}

Minimal Meter interface compatible with

interface Span {
    setAttribute(key: string, value: unknown): Span;
    setAttributes(attributes: Record<string, unknown>): Span;
    addEvent(name: string, attributes?: Record<string, unknown>): Span;
    setStatus(status: {
        code: number;
        message?: string;
    }): Span;
    recordException(exception: unknown): void;
    end(): void;
    isRecording(): boolean;
    spanContext(): {
        traceId: string;
        spanId: string;
        traceFlags: number;
    };
    updateName(name: string): Span;
}

Minimal Span interface compatible with

interface Tracer {
    startSpan(name: string, options?: unknown, context?: unknown): Span;
    startActiveSpan<F extends (span: Span) => unknown>(name: string, fn: F): ReturnType<F>;
}

Minimal Tracer interface compatible with

type Context = unknown;

OTel context — opaque type.