Download the PHP package keepsuit/laravel-opentelemetry without Composer

OpenTelemetry integration for laravel

OpenTelemetry is a collection of tools, APIs, and SDKs. Use it to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) to help you analyze your software’s performance and behavior.

This package allow to integrate OpenTelemetry in a Laravel application.

Installation

You can install the package via composer:

You can publish the config file with:

This is the contents of the published config file:

Traces

This package provides a set of integrations to automatically trace common operations in a Laravel application. You can disable or customize each integration in the config file in the instrumentations section.

Provided tracing integrations

• Http server requests
• Http client
• Database
• Redis
• Queue jobs
• Logs context
• Manual traces

Http server requests

Http server requests are automatically traced by injecting \Keepsuit\LaravelOpenTelemetry\Support\HttpServer\TraceRequestMiddleware::class to the global middlewares. You can disable it by setting OT_INSTRUMENTATION_HTTP_SERVER to false or removing the HttpServerInstrumentation::class from the config file.

Configuration options:

• excluded_paths: list of paths to exclude from tracing
• allowed_headers: list of headers to include in the trace
• sensitive_headers: list of headers with sensitive data to hide in the trace

Http client

To trace an outgoing http request call the withTrace method on the request builder.

You can disable it by setting OT_INSTRUMENTATION_HTTP_CLIENT to false or removing the HttpClientInstrumentation::class from the config file.

Configuration options:

• allowed_headers: list of headers to include in the trace
• sensitive_headers: list of headers with sensitive data to hide in the trace

Database

Database queries are automatically traced. You can disable it by setting OT_INSTRUMENTATION_QUERY to false or removing the QueryInstrumentation::class from the config file.

Redis

Redis commands are automatically traced. You can disable it by setting OT_INSTRUMENTATION_REDIS to false or removing the RedisInstrumentation::class from the config file.

Queue jobs

Queue jobs are automatically traced. It will automatically create a parent span with kind PRODUCER when a job is dispatched and a child span with kind CONSUMER when the job is executed. You can disable it by setting OT_INSTRUMENTATION_QUEUE to false or removing the QueueInstrumentation::class from the config file.

Logs context

When starting a trace with provided instrumentation, the trace id is automatically injected in the log context. This allows to correlate logs with traces.

If you are starting the root trace manually, you should call Tracer::updateLogContext() to inject the trace id in the log context.

[!NOTE] When using the OpenTelemetry logs driver (otlp), the trace id is automatically injected in the log context without the need to call Tracer::updateLogContext().

Manual traces

Spans can be manually created with the newSpan method on the Tracer facade. This method returns a SpanBuilder instance that can be used to customize and start the span.

The simplest way to create a custom trace is with measure method:

Alternatively you can manage the span manually:

With measure the span is automatically set to active (so it will be used as parent for new spans). With start you have to manually set the span as active:

Other utility methods are available on the Tracer facade:

Logs

This package provides a custom log channel that allows to process logs with OpenTelemetry instrumentation. This packages injects a log channel named otlp that can be used to send logs to OpenTelemetry using laravel default log system.

As an alternative, you can use the Logger facade to send logs directly to OpenTelemetry:

Testing

Changelog

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

Credits

• Fabio Capucci
• All Contributors

License

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