genai/trace

Request correlation IDs for centralized logging. A TraceInterceptor reads X-Request-Id (or generates one), exposes it via a TraceContext bean + a global trace_id(), echoes it on the response, and a Monolog processor stamps it on every log line. PHP 5.3-safe at runtime.

v1.0.1 2026-07-10 02:10 UTC

Requires

• php: >=5.3.0
• genai/property: *

Suggests

• genai/attribute: PHP 8 build-time scanning of TraceProperty.
• genai/di: Auto-wires the TraceContext bean (the bundle's #[Configuration]).
• genai/web: TraceInterceptor — reads/echoes the correlation header per request.
• monolog/monolog: TraceProcessor stamps the trace id on every log record.

Apache-2.0

Published on Packagist.org on 2026-07-10 02:15 UTC

README

Request correlation IDs for centralized logging. Each request gets a trace id (read from the inbound header or generated), threaded through the request and stamped on every log line — so you can grep one id and see the whole request's journey across services. PHP 5.3.29-safe at runtime.

How it works

• TraceInterceptor (outermost) reads X-Request-Id from the request (set by an upstream gateway/service), or generates a 128-bit hex id when absent; stores it on TraceContext; and echoes it on the response.
• TraceContext holds the id for the request (a container singleton) and is also exposed statically, so:
  • the global trace_id() helper works in templates/error pages, and
  • the Monolog TraceProcessor can read it without DI.
• Downstream calls should forward the same header to continue the chain.

Use it

1. composer require genai/trace — that's it. The TraceInterceptor is self-enabling: it carries #[Intercept(order: -30)] and lives in a scanned bundle namespace, so installing the package turns it on (no app wiring). Every response now gets X-Request-Id and trace_id() works.

2. Stamp it on your logs (Monolog):

   $logger->pushProcessor(new \GenAI\Trace\Monolog\TraceProcessor());
   // every record now carries extra.trace_id

3. Optional config (app.ini):

   [trace]
   header = X-Request-Id    ; the correlation header (default)

Now every response has X-Request-Id, every log line has extra.trace_id, and trace_id() is available anywhere (e.g. show it on a 500 page as a support ref).

Notes

• Propagation: when calling other services, forward the header (X-Request-Id: <trace_id()>) so they log under the same id.
• Header: defaults to X-Request-Id (simple correlation). Point it at traceparent if you adopt W3C Trace Context later.
• Decoupled: monolog is a suggest — the core (context + interceptor) works without it; the processor only references plain arrays.