Logging Bundle Laravel Package

Technical Evaluation

What this package actually is. Despite the Laravel/PHP framing, keboola/logging-bundle is a Symfony bundle, not a Laravel package. It ships three classes: a DependencyInjection\KeboolaLoggingExtension that runs a function_exists('DDTrace\current_context') check at container compile time, a Monolog\DataDogContextProcessor tagged monolog.processor, and the bundle registration class. Its entire functional surface is: if the ddtrace PHP extension is loaded, attach extra.dd.trace_id and extra.dd.span_id to every Monolog record so Datadog can correlate logs to APM traces. There is no configuration, no service provider, no facade.

What 2.0.0 changes. The 2.0.0 release is a manifest-level breaking change, not a functional one: Monolog 3.x is now the only supported Monolog, and Symfony 7.x is now explicitly supported (Symfony 6.4 presumably retained). Nothing in the release notes suggests the processor logic, the extra.dd.* key contract, the DI guard, the missing php constraint, or the two-branch test coverage changed. Operationally this is good news for us — it confirms the package has been formalised onto the stack we would actually use (Laravel 10/11/12 all ship Monolog 3) — but it means every technical risk identified below survives 2.0.0 intact.

Architecture fit.

• The capability fits any Laravel stack already running Datadog APM with the ddtrace extension — log/trace correlation is a real gap in most Laravel Datadog setups and this is the canonical fix.
• The packaging does not fit. Laravel does not auto-discover Symfony bundles; Symfony\Component\HttpKernel\Bundle\Bundle and DependencyInjection\Extension are dead weight in a Laravel app. Installing it pulls Symfony HttpKernel/DI/Config transitively for ~60 lines of logic. 2.0.0 does not change this; if anything, declaring Symfony 7 support widens the transitive surface a Laravel consumer inherits from a package that contributes one processor.
• The extension-presence guard is the strongest design decision: the package is inert and safe on every environment, which makes it a low-blast-radius addition. That said, it also means failure is silent — no extension, no correlation, no error.
• Monolog 3-only is the right boundary for us and slightly improves architectural fit, but it is a hard cut: any Laravel 8-or-earlier service in the estate (Monolog 2) can no longer consume the package at all and would have to vendor anyway. That bifurcates the rollout into "Laravel 10+ = can depend; everything older = must vendor," which is an argument for simply standardising on the vendored path.

Integration feasibility.

• High, if we decouple from the bundle. The processor is a standard Monolog v3 processor; Laravel's config/logging.php supports 'tap' => [ProcessorClass::class] per channel. That is a one-file change and gets the identical behaviour without booting Symfony DI.
• Two viable paths: (a) composer require keboola/logging-bundle:^2.0 and reference only Keboola\LoggingBundle\Monolog\DataDogContextProcessor in the channel tap; (b) vendor the ~20-line processor into app/Logging/ with attribution under MIT. Given the adoption signals below, (b) is the defensible default and (a) the fallback if Keboola ships fixes we want. 2.0.0 marginally strengthens case (a) — it is evidence the package is maintained, and it removes the Monolog-2/Monolog-3 ambiguity a vendored copy would otherwise have to carry — but it does not fix the mirror or the missing php constraint.
• If we had already vendored from 1.2.0 source, re-verify the processor signature against Monolog 3 (__invoke(LogRecord $record): LogRecord) and the LogRecord API rather than array $record; the 2.0.0 breaking change is precisely this surface. A stale vendored copy silently misbehaves against Monolog 3.

Technical risk.

• Adoption signal is near-zero: 1 star, 0 dependents, score 0.005, opportunity 35.89. No community validation, no third-party production evidence. The publisher (Keboola) is credible, but this is effectively an internal library that happens to be public. A 2.0.0 major does not create an adopter base.
• Mirror-only repository, actively hostile to contribution. keboola/logging-bundle is a read-only CI re-split of libs/logging-bundle/ in keboola/platform-libraries. PRs against it are force-overwritten and closed. Any bug we hit means cloning a large monorepo, or forking. For a 60-line dependency that is a poor trade — and 2.0.0 demonstrates the churn mode: the mirror is force-pushed on every green monorepo build, so derived tags can include a major version bump for what is, functionally, a composer.json edit.
• Key-name contract is fragile and undetected. extra.dd.trace_id / extra.dd.span_id must survive the Monolog formatter and then be remapped in Datadog's log pipeline. Monolog's default JsonFormatter nests these under extra, so out of the box Datadog will not correlate — you need a formatter that flattens extra, or a pipeline remapper targeting extra.dd.trace_id. A rename or refactor breaks correlation with zero test failure and zero runtime error. Nothing in 2.0.0 addresses this.
• No php constraint in composer.json. Composer will happily install on PHP 8.4/8.5 where nothing is tested. CI reportedly covers Symfony 6.4/7.2 on PHP 8.1/8.3; Symfony 7.x support in 2.0.0 implies PHP 8.2+ is exercised for that leg, but PHP 8.4 and Symfony 8 remain uncovered. Open question: did 2.0.0 add a php constraint? The release notes don't say, and this is the one line item that would move the risk needle.
• config.policy.advisories.block=false in the package's own composer config (a CI workaround) does not propagate to consumers, but it signals dependency resolution friction that consumers may inherit.
• Test coverage is two branches — extension present (via stubs) and absent. There are no formatter-level or end-to-end correlation assertions, and a major version that only touched dependency constraints was not an occasion to add any.

Key questions.

1. Is the ddtrace extension present in every runtime that emits logs — php-fpm, queue:work supervisors, schedule:run, and any Lambda/container sidecars? Correlation is per-process.
2. Which Monolog formatter do our channels use, and does it flatten extra to top level? If not, who owns the Datadog log-pipeline remapper?
3. Does 2.0.0 add a php constraint, and is Symfony 6.4 still supported or are we forced onto 7.x? Read the actual composer.json, not the release notes.
4. Do we need Datadog service/env/version tags on the processor, or is DD_SERVICE/DD_ENV injection sufficient?
5. Are we willing to own a vendored copy, or do we need upstream fixes and therefore a monorepo fork relationship? 2.0.0 is the first evidence that upstream ships at all — does that change the answer?
6. What is the actual business value — are we debugging cross-service traces where log-trace join saves incident time, or is this checkbox observability hygiene?
7. Does our Datadog contract have log-trace correlation enabled in the relevant indexes (it is not universal across all log indexes)?

Integration Approach

Stack fit.

• Laravel 10/11/12 + Monolog 3 + ddtrace extension: the processor class is directly reusable, and as of 2.0.0 it is only usable there. The Symfony bundle wrapper is not. This is now a clean, unambiguous match with our target platform — no version-matrix hedging.
• Laravel's LogManager already merges tap processors into the channel's Monolog logger, so no service provider is needed — this is the whole integration.
• If the app is Laravel Octane or uses a custom logger factory, verify the processor is instantiated once per worker, not per request.
• If any service is below Laravel 9 (Monolog 2), it is out of scope for the dependency path; use the vendored processor with the Monolog 3 LogRecord signature only if it is on Monolog 3, otherwise write it as a two-line adapter.

Migration path.

1. Confirm ddtrace extension version and that DDTrace\current_context() returns non-null inside a web request and inside a queued job. This is the single go/no-go gate.
2. Add app/Logging/DataDogContextProcessor.php (vendored, MIT header preserved) or composer require keboola/logging-bundle:^2.0. Pin the major — the mirror's derived tags have already taken one unexplained major jump.
3. Register via 'tap' => [DataDogContextProcessor::class] on the stack/daily/stderr channels used in production; guard registration with function_exists so local and CI environments are unaffected.
4. Align the formatter: either flatten extra into the JSON root or add a Datadog pipeline remapper for extra.dd.trace_id → dd.trace_id.
5. Verify in Datadog: pick a trace ID from APM, confirm the corresponding log lines are returned by the Logs tab of that trace.

Compatibility.

• Monolog 3 is now mandatory, which matches every Laravel version we run in production (10+). This removes the previous caveat entirely.
• PHP 8.1–8.3 is the tested envelope; treat 8.4 as unsupported until verified. Pin the dependency or the vendored copy. Re-check whether 2.0.0 added a php constraint — if it did, Composer will protect us; if not, it still won't.
• Symfony 7.x support is declared; Symfony 6.4 status should be confirmed from composer.json. Irrelevant to a Laravel tap integration, which never instantiates the bundle.
• No conflict with Laravel's own logging pipeline. extra is not used by Laravel internals, so overwriting risk is nil.
• Watch for double-tagging if the Datadog PHP tracer's own log injection is enabled — DD_LOGS_INJECTION=true already does this at the tracer level and would make this package redundant. Check this first; it may obviate the entire evaluation, and 2.0.0 does not change that calculus.

Sequencing.

• Week 1: confirm DD_LOGS_INJECTION is off, verify extension presence across all runtimes, re-read the 2.0.0 composer.json for the php constraint, decide vendor vs. depend.
• Week 2: implement processor + tap + formatter/pipeline change in staging, validate correlation end-to-end.
• Week 3: production rollout on one high-traffic service, monitor Datadog log volume and ingest cost delta.
• Week 4: template to remaining services; add a CI smoke test asserting extra.dd.trace_id appears when the extension is stubbed.
• Standing: subscribe to releases. A 1.2.0 → 2.0.0 bump for a manifest edit means we should expect further majors; the pin is not set-and-forget.

Operational Impact

Maintenance.

• Effectively zero ongoing code maintenance if vendored — the logic is stable and the Datadog contract (dd.trace_id/dd.span_id) is fixed. Vendoring shifts the burden from dependency management to a ~20-line file we own, which is the cheaper side of that trade at this scale. 2.0.0 strengthens this: the only change in a major release was a dependency-constraint edit, i.e. exactly the kind of churn a vendored copy is immune to.
• If we depend on the package instead: version pinning matters, because the mirror is force-pushed on every green monorepo build. Tags are derived, not curated, and 2.0.0 came with no per-release changelog beyond the notes shown — there is no guarantee the next major is as benign.
• Upstream fixes require a monorepo fork. Budget for that being slow and unfamiliar to the team. The upside of 2.0.0 is that it proves the upstream does cut releases, so an upstream-fix path exists in principle.

Support.

• No vendor SLA, no issue triage on the mirror, no community. Support is "read the source" — acceptable because the source is three classes.
• Keboola is a real company and the monorepo is public, so there is a path to upstream, but it is not a support channel we can plan an incident around.

Scaling.

• The processor executes DDTrace\current_context() once per log record. At high log volume (thousands of records/sec across a fleet) this is a measurable but small per-record function call; benchmark before applying to chatty debug channels. Recommend production channels only.
• Log payload grows slightly (two short string/numeric fields per line) — negligible, but it does increase Datadog log ingest and index cost proportionally to volume. Model this before fleet-wide rollout.
• Long-running queue:work processes need the trace context to be refreshed per job; verify the processor isn't capturing a stale context from a prior job's span.

Failure modes.

• Silent no-op (most likely): extension absent in a runtime → processor never registered → no correlation, no error, no alert. Mitigation: assert on boot or in a healthcheck that function_exists('DDTrace\current_context') in each container image.
• Silent correlation break: formatter change nests extra, or a Datadog pipeline remapper is edited → logs and traces stop joining, nothing fails. Mitigation: synthetic check that emits a log inside a known trace and asserts the join in Datadog; run post-deploy.
• Key rename: an over-eager "cleanup" refactor renames dd.trace_id → breaks correlation invisibly. Mitigation: comment the contract in the vendored file and cover it with a unit test.
• Tracer log injection double-write if DD_LOGS_INJECTION=true is enabled later — duplicate or conflicting fields. Mitigation: make it a mutually exclusive setting in the platform config.
• Composer resolution surprise on PHP 8.4+ due to the missing php constraint — only applies if we depend rather than vendor, and only if 2.0.0 did not add one.
• Vendored-copy drift against Monolog 3: a copy lifted from 1.2.0-era source may target the Monolog 2 array $record signature. Mitigation: diff the vendored processor against 2.0.0 before merging.

Ramp-up.

• Engineering effort is measured in hours, not days: one processor registration, one formatter or pipeline decision. The learning curve is not the code — it is understanding Datadog's correlation contract (top-level dd.trace_id, pipeline remappers, per-index enablement) and knowing that all three layers must align.
• The realistic risk is not implementation cost, it is organisational complacency: correlation looks "done" because the package is installed, when in fact the formatter step is the one that actually determines whether it works. A 2.0.0 release landing quietly makes this worse — teams see "we're on the latest major" and assume the observability outcome followed. Assign explicit ownership of the end-to-end verification, not just the composer line.