WRNexusJS/packages/observability

@wrnexus/observability

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.