Laravel OpenTelemetry Integration

Tail sampling allows you to make sampling decisions based on complete trace data (e.g., keeping traces that contain errors or are slow) rather than just the initial span.

Note: Application-level tail sampling is best suited for single-service scenarios. For multi-service environments, use an OpenTelemetry Collector.

Built-in Rules

• ErrorsRule: Keeps traces containing error/exception spans.
• SlowTraceRule: Keeps traces exceeding a specific threshold_ms.

Configuration

• enabled: Boolean to enable/disable tail sampling.
• decision_wait: Maximum time (ms) to wait for the end of a trace before making a decision.
• rules: An array of rules to apply.

'tail_sampling' => [
    'enabled' => false,
    'decision_wait' => 5000,  
    'rules' => [
        TailSampling\Rules\ErrorsRule::class => true,
        TailSampling\Rules\SlowTraceRule::class => [
            'enabled' => true,
            'threshold_ms' => 2000,
        ],
    ],
],

The package supports two sampling strategies to control which traces are exported:

Head Sampling

Decisions are made at the start of a span. It is fast and ideal for rate limiting or percentage-based sampling. Configure this in the traces.sampler section of your config.

Tail Sampling

Decisions are made after the trace completes, allowing you to keep traces based on full data (e.g., errors or slow duration).

Note: Tail sampling implemented at the application level is best for single-service scenarios. For multi-service environments, use an OpenTelemetry Collector.

Built-in Tail Sampling Rules

• Errors Rule: Keeps traces containing any span with an error status.
• Slow Trace Rule: Keeps traces exceeding a duration threshold (default 2000ms).

Tail Sampling Configuration Variables

Upgrading to v2.0 involves several breaking changes in configuration, namespaces, and the Meter API. If you have a published configuration file, you must compare it with the new version and update it manually.

Configuration Changes

• Event Instrumentation: Rename ignored to excluded.
• Console Instrumentation: Behavior is reversed. Instead of excluded, use commands to specify which commands to include. By default, commands are not traced.
• Logs Configuration: The trace_id_field default value changed from traceid to trace_id.
• HTTP Instrumentation: A new sensitive_query_parameters option is available for both server and client instrumentations to redact sensitive data.

Namespace Changes

If you import these classes directly, update your imports:

• Keepsuit\LaravelOpenTelemetry\Support\InstrumentationUtilities $\rightarrow$ Keepsuit\LaravelOpenTelemetry\Instrumentation\Support\InstrumentationUtilities
• Keepsuit\LaravelOpenTelemetry\Support\View\TracedViewEngine $\rightarrow$ Keepsuit\LaravelOpenTelemetry\Instrumentation\Support\View\TracedViewEngine
• Keepsuit\LaravelOpenTelemetry\Support\HttpClient\GuzzleTraceMiddleware $\rightarrow$ Keepsuit\LaravelOpenTelemetry\Instrumentation\Support\Http\Client\GuzzleTraceMiddleware
• Keepsuit\LaravelOpenTelemetry\Support\HttpServer\TraceRequestMiddleware $\rightarrow$ Keepsuit\LaravelOpenTelemetry\Instrumentation\Support\Http\Server\TraceRequestMiddleware

Exporter Behavior

• In v2.0, setting the exporter to null uses a no-op exporter that discards all data.
• To use the in-memory exporter, set the exporter to memory.

Http client requests are traced by default. You can switch to manual mode by setting 'manual' => true in the configuration. In manual mode, you must explicitly call withTrace() on the request builder.

Route Name Resolution: Because low-cardinality URL templates cannot be automatically detected for client requests, you can manually resolve them using HttpClientInstrumentation::setRouteNameResolver() in your service provider.

Metrics:

• http.client.request.duration (histogram, seconds): Outgoing HTTP request duration.

Disabling: Set OTEL_INSTRUMENTATION_HTTP_CLIENT=false or remove HttpClientInstrumentation::class from the config.

// Manual mode usage
Http::withTrace()->get('https://example.com');

// Custom route name resolver
use Keepsuit\LaravelOpenTelemetry\Instrumentation\HttpClientInstrumentation;
use Psr\Http\Message\RequestInterface;

public function boot(): void
{
    HttpClientInstrumentation::setRouteNameResolver(function (RequestInterface $request): ?string {
        return match (true) {
            str_starts_with($request->getUri()->getPath(), '/products/') => '/products/{id}',
            default => null,
        };
    });
}