Weave Code
Opentelemetry Logger Monolog Laravel Package
open-telemetry/opentelemetry-logger-monolog
Monolog handler that bridges your Laravel or PHP application's logs with OpenTelemetry, exporting records through the OTLP logging SDK so they can be correlated with traces and metrics in your observability backend.
A Monolog handler that bridges PHP application logs to OpenTelemetry. It converts Monolog records into OpenTelemetry log records and sends them through the configured LoggerProvider, so existing logging calls can reach OTLP-compatible backends without rewriting application code.
- Maps Monolog levels to OpenTelemetry severity
- Preserves message, context, and exception data as attributes
- Works with OpenTelemetry processors and exporters
- Keeps batching, resource, and sampling in the SDK
- Simple handler registration in any Monolog stack
Frequently asked questions about Opentelemetry Logger Monolog
- How do I install and configure opentelemetry-logger-monolog in Laravel?
- Install it with composer require open-telemetry/opentelemetry-logger-monolog, then register the handler on a monolog-driver channel in config/logging.php or expose a custom otel channel through Log::extend. You also need a service provider that builds an OpenTelemetry LoggerProvider with a processor and exporter, because the package does not bootstrap the SDK for you. Realistic effort is one to three engineer-days including collector wiring and validation.
- Does this handler support Monolog 2 and Laravel 9?
- This package is a Monolog v3 handler, so Laravel 10 and later, which pin Monolog 3, are the natural fit. Laravel 9 pins Monolog 2, so verify the supported matrix before assuming one dependency bump works across the whole estate. Check the composer constraints for both the Monolog and OpenTelemetry SDK versions pinned by the release you install.
- How are trace_id and span_id attached to my log records?
- The handler stamps trace_id, span_id, and trace flags onto log records from the active OpenTelemetry span in the current Context at log time. If no span exists, as is common in queue workers and console commands, no identifiers appear and the handler cannot invent them. That makes middleware ordering and where you start spans inside the request lifecycle important.
- Do I need an OpenTelemetry Collector to use this handler?
- You need an exporter, not necessarily a collector: an OTLP exporter can point at an OTLP-compatible backend directly or at an OpenTelemetry Collector. Most teams run a collector for batching, retries, and vendor switching. Confirm whether your platform already operates one before treating this decision as standalone, since adopting the handler can implicitly fund that infrastructure.
- Why are my OpenTelemetry logs missing or lost under PHP-FPM or Laravel Octane?
- Under PHP-FPM you need a register_shutdown_function flush on the BatchLogRecordProcessor, or buffered records are lost when the process ends. Under Laravel Octane you need a per-request flush plus a reset of the provider and context to avoid state leaking between requests and records being dropped at worker recycle. FPM and Octane have fundamentally different flush semantics, and that lifecycle work is the hard part rather than the handler itself.
- Which PHP extensions are required for OTLP export with this handler?
- OTLP over gRPC requires ext-grpc, while OTLP over HTTP/protobuf requires ext-protobuf or a pure-PHP fallback. Confirm the extension exists in your runtime image or budget for a container rebuild across every service. This is standard OpenTelemetry PHP transport overhead rather than something specific to this package.
- Does this package capture exceptions and stack traces in OTel log records?
- Monolog records, including exception data in context and extra, are converted into OTel log records with severity mapping. However, the OpenTelemetry logs signal is the least settled of the three, and conventions around body-versus-attributes shape and exception or stacktrace attributes have moved. Test how your backend renders exception traces, because it may be poorer than a purpose-built Laravel log channel.
- Is opentelemetry-logger-monolog production-ready given its low star count?
- Treat adoption risk as the dominant risk: the package has roughly nine stars and no dependents, so there is effectively no production reference base. Contrib-scope packages in the opentelemetry-php organisation get best-effort maintenance, tend to lag when the core SDK shifts API surface, and have little community to absorb a breaking change. The counterweight is that the adapter is roughly one class plus a test, so it is cheap to vendor or fork if upstream stalls.
- How do I test that my Laravel logs actually reach the OTLP backend?
- Point the exporter at a local collector or a test OTLP endpoint and confirm records arrive with the expected severity, body, and trace_id and span_id values. Exercise the paths that matter: an HTTP request with an active span, a queue job with no span, and an unreachable collector. Also verify flush behaviour under your real runtime, FPM or Octane, because a passing development test can hide records lost at shutdown.
- Should I write my own Monolog handler instead of using this package?
- If you only need to bridge Monolog to OTLP and control severity mapping, a hand-written handler of around a hundred lines is a credible alternative that removes the dependency and its maintenance risk. Adopt this package when you want a spec-shaped conversion and are already committed to OpenTelemetry for traces, since trace-to-log correlation is the highest-value outcome. If your tracing is not OTel-based, this mostly adds a second observability pipeline for marginal benefit.
Weaver
How can I help you explore Laravel packages today?