79 lines
2.7 KiB
Markdown
79 lines
2.7 KiB
Markdown
# @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.
|