Otel Logging Laravel Package

Technical Evaluation

Category and architecture fit changelo/otel-logging positions itself as a Laravel logging channel that bridges Monolog → OpenTelemetry Logs → OTLP. Laravel's LogManager has a first-class extension point for this (Log::extend or a custom channel driver referenced from config/logging.php), so the integration surface is idiomatic and low-friction. The package slots in as one more channel inside a stack, meaning it can coexist with single/daily/stderr rather than replacing them.

The architectural value hinges on one thing: does it inject trace_id/span_id from the active OTel span into each log record? Without that, it is a generic log shipper with an OTLP transport, and the collector's filelog receiver or an existing vendor agent does the same job with zero application code. With it, logs become first-class correlated telemetry alongside traces — that is the actual product.

Integration feasibility The happy path is small: composer require, publish config, add a channel entry, flip LOG_CHANNEL/LOG_STACK. A competent Laravel engineer can produce a working staging demo in under a day. The real programme effort is not the package — it is standing up the collector, defining resource attributes (service.name, deployment.environment), and modelling ingest cost downstream.

Technical risk

Key questions for the maintainer / code review

1. What is the actual license, and is it OSI-approved?
2. Which open-telemetry/* packages and versions are pinned? Is the logs SDK still experimental?
3. Does the handler inject the active span context, or only static resource attributes?
4. Is export synchronous per-record, batched, or flushed at terminating? What happens on collector timeout?
5. Does a failed export throw (breaking the request) or fail silently and degrade to the fallback channel?
6. Is there CI, a test suite, and coverage for exception rendering and context array serialisation?
7. How does it behave under long-running processes — does the batch buffer ever flush in a Horizon worker?

Integration Approach

Stack fit Target Laravel 10/11/12 on PHP 8.2+, Monolog 3, PSR-3. Confirm whether the transport is OTLP/HTTP+protobuf (portable, no ext-grpc) or gRPC (requires the PHP extension and is a common deployment blocker). Prefer HTTP/protobuf for platform consistency.

Build vs. buy comparators (evaluate before committing)

If the package is a thin wrapper over the official handler, adopt upstream directly and avoid the bus-factor-1 dependency.

Migration path and sequencing

1. Phase 0 — Gate. Resolve license; code review against the questions above. If license is unclear, stop here.
2. Phase 1 — Collector first. Stand up an OTel Collector in staging with memory_limiter → batch → OTLP exporter to the chosen backend. Logs are worthless without this; do not start with the app.
3. Phase 2 — Traces before logs. Instrument one low-risk service with traces and standardise service.name / deployment.environment resource attributes. Logs inherit correlation from spans; doing logs first wastes the exercise.
4. Phase 3 — Shadow dual-write. Add the OTLP channel to the stack alongside the existing file channel on one service. Compare fidelity, latency delta, and volume against baseline for two weeks.
5. Phase 4 — Expand per service behind an env flag (LOG_STACK=stack,daily,otlp), keeping the file channel as local fallback.
6. Phase 5 — Rationale review. Only after 3–5 services are live decide whether to remove file channels or keep them for incident forensics.

Compatibility gates Lock the package to an exact version; verify illuminate/support and monolog/monolog constraints resolve against the app's composer.lock before rollout. Test explicitly under Octane and a Horizon worker — those are where PHP request-scoped assumptions break.

Operational Impact

Maintenance Assume a fork-and-own posture. With a single maintainer, no dependents, and no visible release process, the realistic outcome is that your platform team vendors the package or patches it in-tree. Budget for that explicitly rather than discovering it at the first Laravel major upgrade. Pin exact versions and add a Renovate/Dependabot exclusion with a manual review cadence.

Support No commercial support, no SLA, no community Slack. Ownership must be assigned to a named platform engineer. Write a runbook covering: how to disable the channel, how to verify export health, and how to reconcile against the backend.

Scaling Log volume is typically one to three orders of magnitude larger than trace volume. This is the dominant cost driver, and it is easy to underestimate:

• Collector sizing: memory_limiter and batch processors are mandatory; without them a single verbose service can OOM the collector.
• Backend ingest cost: most vendors price per GB ingested and per GB scanned. Model the cost from a sampled week of production logs before the rollout, not after.
• Volume control: confirm the handler honours Laravel's log level so LOG_LEVEL=warning in production actually suppresses debug egress. There is no meaningful sampling story for logs — unlike traces, you cannot probabilistically drop error records.
• Cardinality: discourage putting user IDs or request IDs into OTel attributes; use log body fields instead.

Failure modes to design around

• Collector unavailable. Must degrade to drop-and-continue. If the handler throws from inside a log call, a collector outage becomes an application outage. Set a short export timeout and verify the fallback channel still fires.
• Request latency. Synchronous export adds the collector's p99 to every log-emitting request. Batch or defer to terminating.
• Memory growth. Long-running workers and Octane hold the exporter's buffer indefinitely. Confirm shutdown flush or force periodic flush.
• Duplicate ingestion. Adding the channel to a stack while a vendor agent is also shipping stdout silently doubles cost.
• Unflushed logs on fatal. OOM and hard fatals lose the buffer — precisely the logs you most want. Accept this or keep the file fallback.
• PII egress. Logs now leave the host. Any redaction that existed in file-based pipelines must be reimplemented at the handler or collector level. Treat as a compliance review item, not an engineering detail.
• Backpressure. A slow backend propagates into the collector queue and then the app. Configure sending_queue limits and dropping policies deliberately.

Ramp-up Platform team: ~2–3 sprints to cover collector deployment, resource-attribute standards, backend cost modelling, and the runbook. Application teams: ~half a day each for channel configuration and semantic-convention basics. The learning curve is not Laravel — it is OpenTelemetry resource semantics and collector operations. Plan a brown-bag session before Phase 3.

Recommendation Do not adopt as-is. The NOASSERTION license is a hard gate, and at 5 stars with zero dependents and a single maintainer the maintenance burden almost certainly exceeds the configuration it saves. Treat this package as a reference implementation: read it to understand the Laravel channel wiring, then build on open-telemetry/opentelemetry-logger-monolog or keepsuit/laravel-opentelemetry, or short-circuit the whole question with a collector filelog receiver. Revisit only if the license is clarified and the package demonstrates trace-context injection plus active maintenance.