Download the PHP package overtrue/laravel-open-telemetry without Composer

Laravel OpenTelemetry

This package provides a simple way to add OpenTelemetry to your Laravel application.

⚠️ Breaking Changes in Recent Versions

SpanBuilder API Changes: The SpanBuilder::start() method behavior has been updated for better safety and predictability:

• Before: start() automatically activated the span's scope, which could cause issues in async scenarios
• Now: start() only creates the span without activating its scope (safer default behavior)
• Migration: If you need the old behavior, use startAndActivate() instead of start()

For most use cases, the new start() behavior is safer and recommended. See the Advanced Span Creation section for detailed usage patterns.

Features

• ✅ Zero Configuration: Works out of the box with sensible defaults.
• ✅ Laravel Native: Deep integration with Laravel's lifecycle and events.
• ✅ Octane & FPM Support: Full compatibility with Laravel Octane and traditional FPM setups.
• ✅ Powerful Measure Facade: Provides an elegant API for manual, semantic tracing.
• ✅ Automatic Tracing: Built-in watchers for cache, database, HTTP clients, queues, and more.
• ✅ Flexible Configuration: Control traced paths, headers, and watchers to fit your needs.
• ✅ Standards Compliant: Adheres to OpenTelemetry Semantic Conventions.

Installation

You can install the package via composer:

Configuration

Important Note for Octane Users

When using Laravel Octane, it is highly recommended to set OTEL_* environment variables at the machine or process level (e.g., in your Dockerfile, docker-compose.yml, or Supervisor configuration) rather than relying solely on the .env file.

This is because some OpenTelemetry components, especially those enabled by OTEL_PHP_AUTOLOAD_ENABLED, are initialized before the Laravel application fully boots and reads the .env file. Setting them as system-level environment variables ensures they are available to the PHP process from the very beginning.

This package uses the standard OpenTelemetry environment variables for configuration. Add these to your .env file for basic setup:

Basic Configuration

Package Configuration

For package-specific settings, publish the configuration file:

This will create a config/otel.php file. Here are the key options:

Enabling/Disabling Tracing

You can completely enable or disable tracing for the entire application. This is useful for performance tuning or disabling tracing in certain environments.

Set OTEL_ENABLED=false in your .env file to disable all tracing.

Filtering Requests and Headers

You can control which requests are traced and which headers are recorded to enhance performance and protect sensitive data. All patterns support wildcards (*) and are case-insensitive.

• ignore_paths: A list of request paths to exclude from tracing. Useful for health checks, metrics endpoints, etc.

• allowed_headers: A list of HTTP header patterns to include in spans. If empty, no headers are recorded.

• sensitive_headers: A list of header patterns whose values will be masked (replaced with ***).

Watchers

You can enable or disable specific watchers to trace different parts of your application.

Usage

The package is designed to work with minimal manual intervention, but it also provides a powerful Measure facade for creating custom spans.

Automatic Tracing

With the default configuration, the package automatically traces:

• Incoming HTTP requests.
• Database queries (QueryWatcher).
• Cache operations (CacheWatcher).
• Outgoing HTTP client requests (HttpClientWatcher).
• Thrown exceptions (ExceptionWatcher).
• Queue jobs (QueueWatcher).
• ...and more, depending on the enabled watchers.

Creating Custom Spans with Measure::trace()

For tracing specific blocks of code, the Measure::trace() method is the recommended approach. It automatically handles span creation, activation, exception recording, and completion.

The trace method will:

• Start a new span.
• Execute the callback.
• Automatically record and re-throw any exceptions that occur within the callback.
• End the span when the callback completes.

Advanced Span Creation with SpanBuilder

For more control over span lifecycle, you can use the SpanBuilder directly through Measure::span(). The SpanBuilder provides several methods for different use cases:

Basic Span Creation (Recommended for most cases)

Span with Activated Scope

Span with Context (For Manual Propagation)

Using Semantic Spans

To promote standardization, the package provides semantic helper methods that create spans with attributes conforming to OpenTelemetry's Semantic Conventions.

Database Spans

Note: If QueryWatcher is enabled, individual queries are already traced. This is useful for tracing a larger transaction or a specific business operation involving multiple queries.

HTTP Client Spans

Custom Spans

Retrieving the Current Span

You can access the currently active span anywhere in your code.

Watchers

The package includes several watchers that automatically create spans for common Laravel operations. You can enable or disable them in config/otel.php.

• CacheWatcher: Traces cache hits, misses, writes, and forgets.
• QueryWatcher: Traces the execution of every database query.
• HttpClientWatcher: Traces all outgoing HTTP requests made with Laravel's Http facade.
• ExceptionWatcher: Traces all exceptions thrown in your application.
• QueueWatcher: Traces jobs being dispatched, processed, and failing.
• RedisWatcher: Traces Redis commands.
• AuthenticateWatcher: Traces authentication events like login, logout, and failed attempts.

Trace ID Injection Middleware

The package includes middleware to add a X-Trace-Id header to your HTTP responses, which is useful for debugging.

You can apply it to specific routes:

Or apply it globally in app/Http/Kernel.php:

Environment Variables Reference

Core OpenTelemetry Variables

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• overtrue
• All Contributors

License

The MIT License (MIT). Please see License File for more information.