# @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.

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

## Traces, correlated logs, and OTLP

```ts
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

```ts
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.