Observability¶

Overview¶

Katal includes built-in request observability middleware for: - structured request logs - correlation ID propagation (X-Request-ID) - W3C trace context pass-through (traceparent) - response timing header (X-Response-Time)

Quick Start¶

import { Application, LoggingIntegration } from "katal";

const app = new Application({ port: 3000 });

const logger = new LoggingIntegration().toConsole();

app.useRequestObservability({
    logger,
    setResponseHeaders: true,
    includeQueryInPath: false,
});

await app.listen();

Structured Log Shape¶

The middleware emits a single structured log per request:

{
  "requestId": "...",
  "traceparent": "00-...",
  "method": "GET",
  "path": "/users",
  "status": 200,
  "durationMs": 12
}

Headers Added¶

When setResponseHeaders is true (default): - X-Request-ID: request correlation id - traceparent: propagated if present in incoming request - X-Response-Time: total middleware-observed duration

API¶

`app.useRequestObservability(options?)`¶

Registers observability middleware globally.

Options: - logger: object with info(message, context) method (optional) - setResponseHeaders: boolean, default true - includeQueryInPath: boolean, default false

Notes¶

If no logger is provided, middleware logs JSON to console.log.
Request id is resolved from incoming x-request-id or generated automatically.