Runtime · Package reference

@wrnexus/observability

Structured logging, tracing, health, and integration adapters.

v0.8.7Private registryRuntime

Install the package

After WorkRoot approves private registry access, install the release-aligned package:

bun add @wrnexus/observability@0.8.7

Request preview access. Never put registry tokens in source control.

Open-standard traces, metrics, logs, health checks, Web Vitals, error reporting and profiling.

Use createOperationTracer() for database, cache, queue, realtime, server-action or custom application spans. Export through OTLP, Prometheus, Zipkin/Jaeger, or the Sentry-compatible error reporter; Grafana can consume the Prometheus or OTLP signals.

Privacy-conscious counters, gauges, histograms, HTTP middleware, Web Vitals ingestion, browser collection, and exporter adapters. Request bodies and user identifiers are not collected by default.

export default {
  observability: { enabled: true, serverTiming: true, sampleRate: 0.1, webVitals: true },
};

Traces, correlated logs, and OTLP

import {
  createOtlpMetricExporter,
  createOtlpTraceExporter,
  createStructuredLogger,
  metricsMiddleware,
  traceMiddleware,
} from "@wrnexus/observability";

const traces = createOtlpTraceExporter("https://collector.example/v1/traces", {
  serviceName: "checkout",
  headers: { authorization: `Bearer ${process.env.OTLP_TOKEN}` },
});

export const tracing = traceMiddleware({
  serviceName: "checkout",
  sampleRate: 0.1,
  exporter: traces,
  onExportError(error) {
    console.error("trace export failed", error);
  },
});

export const metrics = metricsMiddleware();
export const metricExporter = createOtlpMetricExporter("https://collector.example/v1/metrics", {
  serviceName: "checkout",
});

export const logger = createStructuredLogger({ service: "checkout" });
// Request middleware can create a correlated child from ctx.locals.
logger
  .child({
    traceId: ctx.locals.traceId,
    spanId: ctx.locals.spanId,
    requestId: ctx.locals.requestId,
  })
  .info("order accepted", { orderId });

The tracing middleware accepts and validates W3C traceparent, creates a child server span, stores correlation identifiers in ctx.locals, installs the framework tracer on ctx.tracer, and returns traceparent plus x-request-id. Export failures are isolated from application responses when onExportError is configured.

Liveness and readiness

import { HealthRegistry } from "@wrnexus/core";
import { createLivenessHandler, createReadinessHandler } from "@wrnexus/observability";

const health = new HealthRegistry();
health.register("database", async () =>
  (await db.ping()) ? { status: "up" } : { status: "down" },
);

export const live = createLivenessHandler();
export const ready = createReadinessHandler(health);

Liveness reports whether the process can answer requests. Readiness returns HTTP 503 when a registered dependency is down. Dependency messages and details are hidden unless exposeDetails: true is explicitly selected for a trusted endpoint.

Complete TypeScript API

Generated from the exact installed package declarations.

export { MetricLabels, MetricPoint, MetricsRegistry } from './metrics.js';
export { MetricExporter, MetricsMiddlewareOptions, WebVitalRecord, WebVitalsHandlerOptions, createHttpMetricExporter, createOtlpMetricExporter, createWebVitalsHandler, defaultMetrics, metricsMiddleware } from './server.js';
export { WebVitalsClientOptions, webVitalsClient } from './client.js';
export { S as SpanExporter, a as SpanRecord, T as TraceContext, b as TraceMiddlewareOptions, c as createOtlpTraceExporter, f as formatTraceparent, p as parseTraceparent, t as traceMiddleware } from './trace-CvRlPzhE.js';
export { HealthHandlerOptions, createLivenessHandler, createReadinessHandler } from './health.js';
export { LogLevel, LogRecord, StructuredLogger, StructuredLoggerOptions, createStructuredLogger } from './logging.js';
export { ErrorReporter, FrameworkSpanKind, LogExporter, OperationTracer, createJaegerExporter, createOperationTracer, createOtlpLogExporter, createPerformanceProfiler, createPrometheusPushExporter, createSentryCompatibleReporter, createZipkinExporter, renderPrometheus } from './integrations.js';
import '@wrnexus/core';

Examples

Copy-ready examples from the installed package documentation.

Privacy-conscious counters, gauges, histograms, HTTP middleware, Web Vitals ingestion, browser collection, and exporter adapters. Request bodies and user identifiers are not collected by default.

export default {
  observability: { enabled: true, serverTiming: true, sampleRate: 0.1, webVitals: true },
};

## Traces, correlated logs, and OTLP

import {
  createOtlpMetricExporter,
  createOtlpTraceExporter,
  createStructuredLogger,
  metricsMiddleware,
  traceMiddleware,
} from "@wrnexus/observability";

const traces = createOtlpTraceExporter("https://collector.example/v1/traces", {
  serviceName: "checkout",
  headers: { authorization: `Bearer ${process.env.OTLP_TOKEN}` },
});

export const tracing = traceMiddleware({
  serviceName: "checkout",
  sampleRate: 0.1,
  exporter: traces,
  onExportError(error) {
    console.error("trace export failed", error);
  },
});

export const metrics = metricsMiddleware();
export const metricExporter = createOtlpMetricExporter("https://collector.example/v1/metrics", {
  serviceName: "checkout",
});

export const logger = createStructuredLogger({ service: "checkout" });
// Request middleware can create a correlated child from ctx.locals.
logger
  .child({
    traceId: ctx.locals.traceId,
    spanId: ctx.locals.spanId,
    requestId: ctx.locals.requestId,
  })
  .info("order accepted", { orderId });

## Liveness and readiness

import { HealthRegistry } from "@wrnexus/core";
import { createLivenessHandler, createReadinessHandler } from "@wrnexus/observability";

const health = new HealthRegistry();
health.register("database", async () =>
  (await db.ping()) ? { status: "up" } : { status: "down" },
);

export const live = createLivenessHandler();
export const ready = createReadinessHandler(health);