Monolog Enricher Laravel Package

Technical Evaluation

Architecture fit. The package is a thin adapter between two systems: Monolog (the PSR-3 logging pipeline Laravel ships with) and the New Relic PHP agent. It consists of two components — a Monolog processor that reads newrelic_get_linking_metadata() and injects trace.id, span.id, entity.guid, entity.name, and hostname into each log record, and a handler that wraps an existing handler to forward enriched records to the New Relic Logs API. Architecturally it is a decorator pattern, not a framework plugin: it holds no state, owns no business logic, and requires no schema changes. For a TPM this is attractive — the blast radius is confined to the logging channel it is attached to, and it can be introduced for a single channel and rolled back by config change alone.

Integration feasibility. Low effort for the happy path: composer require newrelic/monolog-enricher, register the processor on a channel's tap or via a small service provider in config/logging.php, and ensure the New Relic PHP agent extension is loaded. Roughly a half-day for a competent Laravel engineer to reach a working proof of concept in staging.

Technical risk. Substantial for anything long-lived:

• Staleness. Last release March 2021, 25 stars, 0 dependents, overall score 2.73. This is a single-purpose shim that has seen no upstream activity for four years. Effectively unmaintained.
• Monolog 3 incompatibility (likely). Laravel 10+ ships Monolog 3. A 2021-era constraint of ^1.22|^2.0 will force a Composer conflict; workarounds mean forking or pinning, either of which converts the package from a dependency into owned code.
• Runtime coupling. Enrichment only works where the PHP agent is loaded and the transaction context exists. CLI commands, queue workers, Octane workers, and local/CI environments will produce empty or partial metadata, which is easy to misread as "correlation is broken" when it is simply absent.
• Strategic drift. New Relic has been moving toward OpenTelemetry and native agent log-forwarding paths; a 2021 Monolog helper may be superseded by vendor-supported configuration.

Key questions. Which Laravel and Monolog versions are in use today, and for how long? Is the New Relic PHP agent installed and version-managed across every runtime (web, queue, scheduler, Octane)? Is the goal log-to-trace correlation only, or also log shipping to New Relic Logs? What is monthly log volume and ingest budget? Who owns the code if upstream goes dark? Does the org already standardise on OTel collectors, which would make this redundant?

Integration Approach

Stack fit. Strong conceptual fit with Laravel's logging configuration: one channel, one processor, no application code changes. The package is generic Monolog, so it also fits non-Laravel PHP services, which is useful if the broader estate is mixed.

Migration path. Three options, in ascending cost:

1. Adopt as-is — only viable if the app is on Monolog 1/2 (Laravel ≤9). Fastest route to value.
2. Fork in-house — the surface is small (two classes). Vendor the code into app/Logging or a private package, adjust the Monolog constraint, and add tests. This is the realistic path for Laravel 10+ and is cheap enough that a TPM should budget for it up front rather than treat it as a surprise.
3. Reimplement — a custom processor calling newrelic_get_linking_metadata() is perhaps 40 lines. If the fork is contested, this is a legitimate alternative that removes the dependency entirely.

Compatibility. Confirm the agent version supports linking metadata (agent ≥ 9.x for full distributed tracing), that newrelic.distributed_tracing.enabled=true, and that the entity/labels are set so records resolve to the right APM entity. Validate that enrichment survives the handler stack ordering — processors must run before the formatting handler.

Sequencing.

1. Confirm agent presence and non-empty linking metadata on a staging host.
2. Prove correlation on a single non-critical channel; verify trace.id resolves to a trace in the New Relic UI.
3. Resolve the Monolog 3 issue via fork if applicable; add unit tests around the processor.
4. Roll out per channel (start with HTTP, then queue workers with a clear expectation of partial coverage).
5. Document the fallback path and the config toggle before broad enablement.

Operational Impact

Maintenance. Treat this as internally owned from day one. Upstream is dormant; there is no patch stream, no CVE responsiveness, and no compatibility work. Ownership cost is low (small code surface) but non-zero, and it must be assigned to a named team with a renewal/retirement review date.

Support. Apache-2.0 gives legal freedom to fork, which mitigates the abandonment risk considerably. Vendor support should not be assumed — New Relic support may treat an unmaintained community helper as out of scope, so internal runbooks are the actual support surface.

Scaling. Per-record overhead is a handful of agent calls plus array writes — negligible against typical request logging, but measurable on chatty debug channels or batch jobs emitting tens of thousands of lines. The larger scaling concern is economic: every enriched log line is billable ingest in New Relic Logs. Adding entity.guid and hostname increases payload size and cardinality. Gate adoption behind a log-volume estimate and a sampling/level policy; the package should not be enabled on debug in production.

Failure modes.

• Agent absent or extension not loaded → enrichment silently missing, or a fatal error if the function is called unguarded. Wrap in function_exists.
• Empty metadata in CLI/queue contexts → logs appear uncorrelated; teams lose trust in the tooling.
• Monolog major upgrade breaks the handler wrap contract → logging pipeline fails at the worst moment. Pin and test.
• Handler misordering causes double-formatting or lost processors.
• Ingest spikes from verbose levels, leading to an unplanned observability bill.

Ramp-up. Very shallow — an engineer familiar with Monolog can read the entire package in under an hour. The real ramp-up is operational, not code: SRE needs to understand agent prerequisites, New Relic Logs forwarding configuration, environment-specific coverage gaps, and cost controls. Budget a short runbook and a brown-bag session rather than a formal enablement programme.

TPM recommendation. Worth a low-cost, time-boxed pilot if the stack is Monolog 2 and the agent is already deployed; the correlation value is real and the integration is cheap. Do not adopt it as a strategic dependency on Laravel 10+ or as a long-term bet — plan to fork or replace with a ~40-line internal processor, and set a review checkpoint before it becomes load-bearing in production.