A Laravel package that seamlessly integrates with OpenTelemetry by sending your application logs to OpenTelemetry collectors using the OTLP protocol.
- 🔄 Sends Laravel logs to an OpenTelemetry collector
- 🧩 Properly formats log attributes according to OTLP specification
- 🛡️ Handles exceptions gracefully with comprehensive error reporting
- ⚙️ Configurable via environment variables or config file
- 🔍 Supports distributed tracing context (trace and span IDs)
- 🔌 Compatible with Laravel 8, 9, 10, 11 and 12
You can install the package via composer:
composer require changole/otel-loggingPublish the configuration file:
php artisan vendor:publish --tag=otel-logging-configThis will create a config/otel-logging.php file where you can configure the package.
Configure the package using environment variables in your .env file:
OTEL_ENABLED=true
OTEL_EXPORTER_ENDPOINT=https://collector.example.com/v1/logs
OTEL_SERVICE_NAME=my-laravel-app
OTEL_HTTP_TIMEOUT=5Add the OpenTelemetry channel to your logging configuration in config/logging.php:
'channels' => [
// ...
'otel' => [
'driver' => 'monolog',
'handler' => Changole\OtelLogging\Otel\OtelLogHandler::class,
],
// Or use it in a stack
'stack' => [
'driver' => 'stack',
'channels' => ['single', 'otel'],
'ignore_exceptions' => false,
],
],Once configured, the handler will automatically send logs to your OpenTelemetry collector:
// Using the dedicated channel
Log::channel('otel')->info('This is a test message', ['user_id' => 123]);
// Or when using the stack (if you added 'otel' to your stack channels)
Log::info('This message will go to both file and OpenTelemetry', [
'user_id' => 123,
]);Exception details are automatically formatted according to OpenTelemetry conventions:
try {
// Your code
} catch (\Exception $e) {
Log::error('Error processing payment', [
'exception' => $e,
'payment_id' => $paymentId,
]);
}Add trace and span IDs to correlate logs with traces:
Log::info('Processing order', [
'order_id' => $order->id,
'trace_id' => $traceId,
'span_id' => $spanId,
]);| Environment Variable | Description | Default |
|---|---|---|
OTEL_ENABLED |
Enable or disable OpenTelemetry logging | false |
OTEL_EXPORTER_ENDPOINT |
The URL of the OpenTelemetry collector | https://collector.example.com/v1/logs |
OTEL_SERVICE_NAME |
The name of your service | laravel-app |
OTEL_HTTP_TIMEOUT |
Timeout for HTTP requests in seconds | 5 |
- Check that
OTEL_ENABLEDis set totruein your.envfile - Verify your collector endpoint is correct and accessible
- Check your Laravel logs for any error messages related to sending logs
The package is designed to have minimal impact on performance, but if you're concerned about performance in high-volume environments:
- Consider using a batched collector endpoint
- Set an appropriate log level to reduce the volume of logs
Contributions are welcome! Please feel free to submit a Pull Request.
The MIT License (MIT). Please see License File for more information.
OpenTelemetry is a collection of tools, APIs, and SDKs used to instrument, generate, collect, and export telemetry data (logs) for analysis in order to understand what is happening on your software's.