Opentelemetry Logger Monolog Laravel Package

Technical Evaluation

Architecture fit

• The package is a thin adapter: a Monolog HandlerInterface implementation that converts Monolog records into OpenTelemetry log records and pushes them through an OTel LoggerProvider (with Processor/Exporter supplied by the application). It is not a framework, not an auto-instrumentation agent, and it does not bootstrap the SDK.
• For a Laravel estate this is a plumbing component, not an architecture decision. It slots into the existing logging.php channel model as a custom handler behind a monolog-driver channel, or via Log::extend for a first-class otel channel name. The architectural weight lives in the OTel SDK bootstrap (resource detection, OTLP exporter, batch processor, shutdown flush) which we own either way.
• Strategic fit depends entirely on whether the platform roadmap already commits to OpenTelemetry for traces. If spans are already OTel-based, this handler is the cheapest path to trace–log correlation (trace_id/span_id stamped onto every log line), which is the single highest-value outcome. If tracing is not OTel, this adds a second observability pipeline for marginal benefit.

Integration feasibility

• Low code cost: one composer dependency, one handler registration, one channel entry, plus a LoggerProvider service provider. Realistically 1–3 engineer-days including collector wiring and validation, not a multi-sprint effort.
• The hard part is not the handler; it is lifecycle. PHP-FPM and Laravel Octane have fundamentally different flush semantics. Under FPM you need a register_shutdown_function flush on the BatchLogRecordProcessor; under Octane you need a per-request flush and a reset of the provider/context to avoid leaking state and losing records at worker recycle.
• Correlation is conditional: trace_id/span_id only appear if an active span exists in the OTel Context at log time. That means middleware ordering, span creation inside the request lifecycle, and queue/console contexts where no span exists at all — the handler cannot invent that.
• Export transport is the usual OTel PHP tax: OTLP over gRPC (ext-grpc) or HTTP/protobuf (ext-protobuf or a pure-PHP fallback). Confirm the runtime image has the extension, or budget for a container rebuild across every service.

Technical risk

• Adoption risk is the dominant risk. 9 stars and 0 dependents means effectively no production reference base. Contrib-scope packages in the opentelemetry-php org receive best-effort maintenance and are the first to lag when the core SDK shifts API surface. There is no meaningful community to absorb a breaking change.
• Version-coupling risk. The handler's composer constraint must track the OTel SDK (still stabilising its logs signal) and Monolog. Monolog 2 vs 3 matters: Laravel 9 pins Monolog 2, Laravel 10+ pins Monolog 3. Verify the supported matrix before assuming a single dependency bump across the estate.
• Logs-signal maturity. OTel logs are the least settled of the three signals; spec and SDK behaviour around severity mapping, exception/stacktrace attributes, and body-vs-attributes shape have moved. Backend rendering of exception traces may be poorer than a purpose-built Laravel log channel.
• Blast radius is contained. The adapter is small enough to vendor or fork outright. That materially de-risks the low-star count — we are not adopting a framework, we are adopting ~one class plus a test.

Key questions

1. Does a current release support both Monolog 2 and 3, and which OTel SDK minor versions are pinned?
2. Does the handler propagate trace_id/span_id and trace_flags automatically, or must we supply them via Monolog's extra/context?
3. What is the failure policy when the exporter throws — does it swallow, log-to-stderr, or bubble into the request?
4. Is there an official release cadence, or is this effectively one maintainer's side project? Who is the security contact?
5. Do we already run an OTel Collector, or does this decision implicitly fund one?
6. Build-vs-adopt: our own ~100-line handler is a credible alternative if answers 1–4 are unsatisfactory.

Integration Approach

Stack fit

• Natural fit for a Laravel monolith or modular monolith already using Monolog channels, and for any service where we want logs and traces landing in the same backend with correlated IDs. Poor fit for teams standardising on a vendor SDK (Datadog, New Relic) — do not run two agents against the same process.
• Works cleanly alongside stack channels, which is the safest adoption shape: existing file/stderr channel retained, OTel handler appended as a second member of the stack.

Migration path

• Phase 0 — spike on one non-critical service, console/file exporter only, no backend. Prove the handler emits correct severity and exception attributes.
• Phase 1 — dual-write. Existing channel untouched; OTel handler added to the stack. Ship a correlation middleware that opens a root span. Compare OTel records to file logs for a week on volume, PII surface, and trace linkage.
• Phase 2 — route OTLP to a collector, add the Collector as the single egress point (so backend choice stays reversible), enable the batch processor with explicit flush hooks.
• Phase 3 — promote to a shared internal package (wrapping the contrib handler plus our bootstrap), then retire redundant file shipping where the collector covers it. Keep local file logging as the break-glass path.

Compatibility

• Pin the handler, the OTel SDK, and Monolog together in the internal wrapper so services do not independently float. Treat the OTel SDK as an infrastructure dependency with a change-approval gate, not a routine composer update passenger.
• Verify PHP version floor (8.1+ is the realistic baseline for current OTel PHP), Laravel version, Octane vs FPM, and the availability of ext-grpc/ext-protobuf in every runtime image before committing.
• Watch for handler/LoggerProvider singleton reuse under Octane: a stale provider is a silent data-loss vector, not a crash.

Sequencing

1. Decision gate: is OTel the sanctioned telemetry standard? If unowned, stop here.
2. Runtime prerequisites: extensions, collector endpoint, collector deployed.
3. Correlation middleware and span lifecycle (this is the actual work).
4. Handler + bootstrap in one pilot service.
5. Internal wrapper package, then fan-out by service tier, highest-traffic first to surface cost quickly.

Operational Impact

Maintenance

• Two surfaces to maintain: the thin contrib package (low churn, but no upstream SLA — plan to vendor or pin hard) and our OTel bootstrap/collector configuration (higher churn, fully ours).
• Budget roughly 0.1–0.2 FTE ongoing for the wrapper plus collector, spiking at SDK upgrades. The dominant cost is the collector and backend, not the handler.
• Because the code surface is tiny, an exit or fork is a day's work. That should be stated explicitly to avoid the package being treated as a strategic dependency.

Support

• No vendor support; community GitHub issues only. Escalation path for a production incident is "read the class, patch our fork." Acceptable only because the class is small.
• Support burden shifts to the platform team owning the internal wrapper — which is the right place for it, but must be resourced, not assumed.

Scaling

• Log volume, not request volume, is the scaling axis. Every log line becomes a billable network egress and a billable backend ingest event; a chatty Laravel app can multiply observability spend 5–10× versus file logs. Enforce level floors per environment (warning+ in production initially) and keep the existing local channel for verbose debugging.
• Batch processor sizing (maxQueueSize, scheduleDelayMillis, export timeout) must be tuned per workload; queue saturation silently drops records under load, which is exactly when you need them.
• Collector becomes a shared dependency with its own capacity plan and HA story.

Failure modes

• Collector/exporter unreachable → batch queue fills, records dropped; requests should stay healthy if the handler is non-blocking. Confirm this empirically with the collector stopped.
• Missing flush at request end (FPM shutdown, Octane recycle) → invisible log loss with no error. Test explicitly; this is the most likely production surprise.
• PII/compliance regression: OTel captures full context arrays and exception payloads by default, potentially shipping secrets or personal data that a curated file channel would have filtered. Needs a redaction/attribute-limit policy before Phase 2.
• Duplicate or missing logs during dual-write cause confusion in incident triage; annotate dashboards accordingly during migration.
• Severity mapping mismatches make backend filtering unreliable; validate the full Laravel level set (emergency → debug) end-to-end.

Ramp-up

• Engineers need only Monolog channel knowledge to use it, but the platform team needs OTel fundamentals: context propagation, processors vs exporters, resource attributes, collector pipelines, and the semantic conventions for logs.
• Realistic ramp: 1–2 days for a competent Laravel engineer on the wrapper; 1–2 weeks for genuine collector/SDK ownership. Budget a half-day of team enablement on how to find correlated logs from a trace ID, or the correlation capability goes unused.

Verdict for a TPM

Technically low-risk, organisationally medium-risk. The opportunity score is credible: high leverage per unit of effort if OpenTelemetry is already the sanctioned standard for traces — the handler is then the cheapest available route to trace-correlated logs. If OTel is not already committed, this package is not the reason to adopt it; it is a follow-on, and the 9-star/0-dependent profile means the correct posture is pin hard, vendor the class, and treat the collector as the real system under management.