release: WRNexusJS 0.8.0

packages/observability/README.md

@@ -1,5 +1,9 @@
 # @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
@@ -7,3 +11,68 @@ 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.