Download the PHP package amashukov/tracing-bundle without Composer

amashukov/tracing-bundle

A Symfony 7 bundle that stamps every inbound HTTP request with a UUIDv7 X-Request-Id, mirrors it onto every Monolog log record's extra.request_id, echoes it back on the response, and rides through Symfony Messenger so a worker logging a handler ends up with the same id the originating HTTP request held.

amashukov/tracing-bundle is a vendor-extractable Symfony 7 bundle for end-to-end request_id propagation. Doing this once at the right layer beats bolting it on per-call: the bundle ships the kernel listener, the resolver, the Monolog processor, the Messenger stamp, the consume-side context restorer, validation at the trust boundary, and the CLI fallback so every console run / cron / worker logs {"request_id":"..."} instead of an empty extra block. Drop it into a Symfony 7 project, get the same id flowing through the FE fetch, the controller, every log line on every channel, the response header, and the queue-bound worker that picks the message up minutes later — with zero App\* namespace coupling.

Features

• Per-request UUIDv7 — generated via symfony/uid when the incoming X-Request-Id is missing or malformed; valid inbound ids are lowercased and forwarded unchanged.
• Listener at the kernel boundary — kernel.request (priority 256) writes the id onto the Request attribute; kernel.response (priority -256) mirrors it onto the response header. Main-request only; sub-requests inherit the parent id naturally.
• Validation at the trust boundary — incoming header rejected when length ≠ 36 or it contains anything outside [a-f0-9-]. Prevents log-injection (SQL fragments, control characters, oversized payloads) from contaminating log files and aggregator search.
• Monolog processor on every channel — extra.request_id attached to every LogRecord (app, doctrine, security, messenger, ...) with pre-existing extras preserved.
• Messenger sync → queue → worker bridge — dispatch-side middleware attaches a RequestIdStamp to outbound envelopes; consume-side restores the id into WorkerRequestIdContext before the handler runs, clears in finally so message N+1 starts clean.
• CLI fallback — every console / cron / non-Messenger worker run logs {"request_id":"cli"} instead of an empty extra block — log-aggregator queries stay consistent regardless of execution mode.
• final readonly services — narrow contracts, immutable wiring, autowired by default.
• Zero App\* coupling — bundle depends only on monolog/monolog + symfony/*. Drop into any project without renaming.

Installation

Symfony Flex registers the bundle automatically. If you don't run Flex, add it manually:

Requirements

• PHP 8.3+ (UUIDv7 needs symfony/uid ≥ 7.0)
• monolog/monolog ^3.0
• symfony/* ^7.0 (config, dependency-injection, event-dispatcher, http-foundation, http-kernel, uid, yaml)
• symfony/messenger ^7.0 — soft suggest. The middleware class only loads when Messenger is installed; non-Messenger projects pay zero overhead.

Usage

After install — no further config. Every request automatically:

1. Receives a request_id attribute on the Request.
2. Logs extra.request_id in every Monolog record.
3. Mirrors X-Request-Id on the response.

Reading the id inside a service

Browser side (Nuxt 3 / 4 plugin)

Playwright per-test echo

Then debug any failing run:

Every BE event scoped to that one test, no cross-spec noise.

CORS allow header

If the FE talks to a different origin, allow the header on both directions:

Messenger integration (sync → queue → worker)

When a Messenger message crosses the sync → queue boundary, the worker process has no RequestStack. The bundle's middleware closes that gap.

Dispatch side (HTTP request handler):

Consume side (worker process):

Per W3C Trace Context spec Non-HTTP Protocol Support and the Symfony Messenger official middleware pattern ($envelope->last(ReceivedStamp::class) discriminates dispatch vs consume).

Class catalogue

Validation

Incoming X-Request-Id is rejected when:

• length ≠ 36 chars
• contains anything outside [a-f0-9-]

Rejected → bundle generates a fresh UUIDv7.

CLI fallback

In CLI context (no Request on RequestStack, no WorkerRequestIdContext value set), the resolver returns the literal cli. Every console command / one-shot cron task logs {"request_id":"cli"} instead of an empty extra block — log-aggregator queries stay consistent regardless of execution mode.

Trace Context (W3C traceparent)

This bundle deliberately implements the X-Request-Id header pattern only (Heroku / Cloudflare CF-Ray style). For W3C Trace Context (traceparent / OpenTelemetry alignment) pair this bundle with the official open-telemetry/opentelemetry-php-instrumentation-symfony — the two are complementary, not alternatives.

Testing

Suite covers: valid UUIDv7 accept, mixed-case header lowercased, five invalid-header regen cases (missing, too short, too long, wrong charset, SQL-injection-looking string), response header mirror, sub-request skip, subscribed-events shape, CLI fallback (no request / no attribute / non-string attribute), extra.request_id attach with pre-existing extras preserved, Messenger stamp value semantics, worker-context set/get/clear, middleware dispatch path, middleware consume path, middleware finally clears between messages.

License

MIT — see LICENSE.

Author

Andrei Mashukov — [email protected]