{"id":26576698,"url":"https://github.com/keepsuit/laravel-opentelemetry","last_synced_at":"2025-12-24T17:35:29.796Z","repository":{"id":65459256,"uuid":"391581375","full_name":"keepsuit/laravel-opentelemetry","owner":"keepsuit","description":"OpenTelemetry integration for laravel","archived":false,"fork":false,"pushed_at":"2025-02-23T17:48:50.000Z","size":283,"stargazers_count":44,"open_issues_count":1,"forks_count":13,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-07T09:10:26.567Z","etag":null,"topics":["laravel","opentelemetry","tracing"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/keepsuit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-01T09:18:49.000Z","updated_at":"2025-03-02T14:10:01.000Z","dependencies_parsed_at":"2025-03-22T14:24:44.814Z","dependency_job_id":"58062782-c4c6-46ce-a1d3-c7af31e19527","html_url":"https://github.com/keepsuit/laravel-opentelemetry","commit_stats":{"total_commits":117,"total_committers":3,"mean_commits":39.0,"dds":0.02564102564102566,"last_synced_commit":"1cc9b2b3cebf055ade5225042765e2fa82e3d614"},"previous_names":[],"tags_count":49,"template":false,"template_full_name":"spatie/package-skeleton-laravel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keepsuit%2Flaravel-opentelemetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keepsuit%2Flaravel-opentelemetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keepsuit%2Flaravel-opentelemetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keepsuit%2Flaravel-opentelemetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keepsuit","download_url":"https://codeload.github.com/keepsuit/laravel-opentelemetry/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247436284,"owners_count":20938533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["laravel","opentelemetry","tracing"],"created_at":"2025-03-23T03:26:27.375Z","updated_at":"2025-12-24T17:35:29.790Z","avatar_url":"https://github.com/keepsuit.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenTelemetry integration for laravel\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/keepsuit/laravel-opentelemetry.svg?style=flat-square)](https://packagist.org/packages/keepsuit/laravel-opentelemetry)\n[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/keepsuit/laravel-opentelemetry/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/keepsuit/laravel-opentelemetry/actions?query=workflow%3Arun-tests+branch%3Amain)\n[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/keepsuit/laravel-opentelemetry/fix-php-code-style-issues.yml?branch=main\u0026label=code%20style\u0026style=flat-square)](https://github.com/keepsuit/laravel-opentelemetry/actions?query=workflow%3A\"Fix+PHP+code+style+issues\"+branch%3Amain)\n[![Total Downloads](https://img.shields.io/packagist/dt/keepsuit/laravel-opentelemetry.svg?style=flat-square)](https://packagist.org/packages/keepsuit/laravel-opentelemetry)\n\n_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._\n\nThis package allow to integrate OpenTelemetry in a Laravel application.\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require keepsuit/laravel-opentelemetry\n```\n\nYou can publish the config file with:\n\n```bash\nphp artisan vendor:publish --provider=\"Keepsuit\\LaravelOpenTelemetry\\LaravelOpenTelemetryServiceProvider\" --tag=\"opentelemetry-config\"\n```\n\nThis is the contents of the published config file:\n\n```php\n\u003c?php\n\nuse Keepsuit\\LaravelOpenTelemetry\\Instrumentation;\nuse OpenTelemetry\\SDK\\Common\\Configuration\\Variables;\n\nreturn [\n    /**\n     * Service name\n     */\n    'service_name' =\u003e env(Variables::OTEL_SERVICE_NAME, \\Illuminate\\Support\\Str::slug((string) env('APP_NAME', 'laravel-app'))),\n\n    /**\n     * Service instance id\n     * Should be unique for each instance of your service.\n     * If not set, a random id will be generated on each request.\n     */\n    'service_instance_id' =\u003e env('OTEL_SERVICE_INSTANCE_ID'),\n\n    /**\n     * Comma separated list of propagators to use.\n     * Supports any otel propagator, for example: \"tracecontext\", \"baggage\", \"b3\", \"b3multi\", \"none\"\n     */\n    'propagators' =\u003e env(Variables::OTEL_PROPAGATORS, 'tracecontext'),\n\n    /**\n     * OpenTelemetry Meter configuration\n     */\n    'metrics' =\u003e [\n        /**\n         * Metrics exporter\n         * This should be the key of one of the exporters defined in the exporters section\n         * Supported drivers: \"otlp\", \"console\", \"null\"\n         */\n        'exporter' =\u003e env(Variables::OTEL_METRICS_EXPORTER, 'otlp'),\n    ],\n\n    /**\n     * OpenTelemetry Traces configuration\n     */\n    'traces' =\u003e [\n        /**\n         * Traces exporter\n         * This should be the key of one of the exporters defined in the exporters section\n         */\n        'exporter' =\u003e env(Variables::OTEL_TRACES_EXPORTER, 'otlp'),\n\n        /**\n         * Traces sampler\n         */\n        'sampler' =\u003e [\n            /**\n             * Wraps the sampler in a parent based sampler\n             */\n            'parent' =\u003e env('OTEL_TRACES_SAMPLER_PARENT', true),\n\n            /**\n             * Sampler type\n             * Supported values: \"always_on\", \"always_off\", \"traceidratio\"\n             */\n            'type' =\u003e env('OTEL_TRACES_SAMPLER_TYPE', 'always_on'),\n\n            'args' =\u003e [\n                /**\n                 * Sampling ratio for traceidratio sampler\n                 */\n                'ratio' =\u003e env('OTEL_TRACES_SAMPLER_TRACEIDRATIO_RATIO', 0.05),\n            ],\n        ],\n\n        /**\n         * Traces span processors.\n         * Processors classes must implement OpenTelemetry\\SDK\\Trace\\SpanProcessorInterface\n         *\n         * Example: YourTracesSpanProcessor::class\n         */\n        'processors' =\u003e [],\n    ],\n\n    /**\n     * OpenTelemetry logs configuration\n     */\n    'logs' =\u003e [\n        /**\n         * Logs exporter\n         * This should be the key of one of the exporters defined in the exporters section\n         * Supported drivers: \"otlp\", \"console\", \"null\"\n         */\n        'exporter' =\u003e env(Variables::OTEL_LOGS_EXPORTER, 'otlp'),\n\n        /**\n         * Inject active trace id in log context\n         *\n         * When using the OpenTelemetry logger, the trace id is always injected in the exported log record.\n         * This option allows to inject the trace id in the log context for other loggers.\n         */\n        'inject_trace_id' =\u003e true,\n\n        /**\n         * Context field name for trace id\n         */\n        'trace_id_field' =\u003e 'traceid',\n\n        /**\n         * Logs record processors.\n         * Processors classes must implement OpenTelemetry\\SDK\\Logs\\LogRecordProcessorInterface\n         *\n         * Example: YourLogRecordProcessor::class\n         */\n        'processors' =\u003e [],\n    ],\n\n    /**\n     * OpenTelemetry exporters\n     *\n     * Here you can configure exports used by metrics, traces and logs.\n     * If you want to use the same protocol with different endpoints,\n     * you can copy the exporter with a different and change the endpoint\n     *\n     * Supported drivers: \"otlp\", \"zipkin\", \"console\", \"null\"\n     */\n    'exporters' =\u003e [\n        'otlp' =\u003e [\n            'driver' =\u003e 'otlp',\n            'endpoint' =\u003e env(Variables::OTEL_EXPORTER_OTLP_ENDPOINT, 'http://localhost:4318'),\n            /**\n             * Supported protocols: \"grpc\", \"http/protobuf\", \"http/json\"\n             */\n            'protocol' =\u003e env(Variables::OTEL_EXPORTER_OTLP_PROTOCOL, 'http/protobuf'),\n            'max_retries' =\u003e env('OTEL_EXPORTER_OTLP_MAX_RETRIES', 3),\n            'traces_timeout' =\u003e env(Variables::OTEL_EXPORTER_OTLP_TRACES_TIMEOUT, env(Variables::OTEL_EXPORTER_OTLP_TIMEOUT, 10000)),\n            'traces_headers' =\u003e (string) env(Variables::OTEL_EXPORTER_OTLP_TRACES_HEADERS, env(Variables::OTEL_EXPORTER_OTLP_HEADERS, '')),\n            /**\n             * Override protocol for traces export\n             */\n            'traces_protocol' =\u003e env(Variables::OTEL_EXPORTER_OTLP_TRACES_PROTOCOL),\n            'metrics_timeout' =\u003e env(Variables::OTEL_EXPORTER_OTLP_METRICS_TIMEOUT, env(Variables::OTEL_EXPORTER_OTLP_TIMEOUT, 10000)),\n            'metrics_headers' =\u003e (string) env(Variables::OTEL_EXPORTER_OTLP_METRICS_HEADERS, env(Variables::OTEL_EXPORTER_OTLP_HEADERS, '')),\n            /**\n             * Override protocol for metrics export\n             */\n            'metrics_protocol' =\u003e env(Variables::OTEL_EXPORTER_OTLP_METRICS_PROTOCOL),\n            /**\n             * Preferred metrics temporality\n             * Supported values: \"Delta\", \"Cumulative\"\n             */\n            'metrics_temporality' =\u003e env(Variables::OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE),\n            'logs_timeout' =\u003e env(Variables::OTEL_EXPORTER_OTLP_LOGS_TIMEOUT, env(Variables::OTEL_EXPORTER_OTLP_TIMEOUT, 10000)),\n            'logs_headers' =\u003e (string) env(Variables::OTEL_EXPORTER_OTLP_LOGS_HEADERS, env(Variables::OTEL_EXPORTER_OTLP_HEADERS, '')),\n            /**\n             * Override protocol for logs export\n             */\n            'logs_protocol' =\u003e env(Variables::OTEL_EXPORTER_OTLP_LOGS_PROTOCOL),\n        ],\n\n        'zipkin' =\u003e [\n            'driver' =\u003e 'zipkin',\n            'endpoint' =\u003e env(Variables::OTEL_EXPORTER_ZIPKIN_ENDPOINT, 'http://localhost:9411'),\n            'timeout' =\u003e env(Variables::OTEL_EXPORTER_ZIPKIN_TIMEOUT, 10000),\n            'max_retries' =\u003e env('OTEL_EXPORTER_ZIPKIN_MAX_RETRIES', 3),\n        ],\n    ],\n\n    /**\n     * List of instrumentation used for application tracing\n     */\n    'instrumentation' =\u003e [\n        Instrumentation\\HttpServerInstrumentation::class =\u003e [\n            'enabled' =\u003e env('OTEL_INSTRUMENTATION_HTTP_SERVER', true),\n            'excluded_paths' =\u003e [],\n            'excluded_methods' =\u003e [],\n            'allowed_headers' =\u003e [],\n            'sensitive_headers' =\u003e [],\n        ],\n\n        Instrumentation\\HttpClientInstrumentation::class =\u003e [\n            'enabled' =\u003e env('OTEL_INSTRUMENTATION_HTTP_CLIENT', true),\n            'manual' =\u003e false, // When set to true, you need to call `withTrace()` on the request to enable tracing\n            'allowed_headers' =\u003e [],\n            'sensitive_headers' =\u003e [],\n        ],\n\n        Instrumentation\\QueryInstrumentation::class =\u003e env('OTEL_INSTRUMENTATION_QUERY', true),\n\n        Instrumentation\\RedisInstrumentation::class =\u003e env('OTEL_INSTRUMENTATION_REDIS', true),\n\n        Instrumentation\\QueueInstrumentation::class =\u003e env('OTEL_INSTRUMENTATION_QUEUE', true),\n\n        Instrumentation\\CacheInstrumentation::class =\u003e env('OTEL_INSTRUMENTATION_CACHE', true),\n\n        Instrumentation\\EventInstrumentation::class =\u003e [\n            'enabled' =\u003e env('OTEL_INSTRUMENTATION_EVENT', true),\n            'ignored' =\u003e [],\n        ],\n\n        Instrumentation\\ViewInstrumentation::class =\u003e env('OTEL_INSTRUMENTATION_VIEW', true),\n\n        Instrumentation\\LivewireInstrumentation::class =\u003e env('OTEL_INSTRUMENTATION_LIVEWIRE', true),\n\n        Instrumentation\\ConsoleInstrumentation::class =\u003e [\n            'enabled' =\u003e env('OTEL_INSTRUMENTATION_CONSOLE', true),\n            'excluded' =\u003e [],\n        ],\n    ],\n];\n```\n\n\u003e [!NOTE]  \n\u003e OpenTelemetry instrumentation can be completely disabled by setting the `OTEL_SDK_DISABLED` environment variable to `true`.\n\n## Traces\n\nThis package provides a set of integrations to automatically trace common operations in a Laravel application.\nYou can disable or customize each integration in the config file in the `instrumentations` section.\n\n### Provided tracing integrations\n\n- [Http server requests](#http-server-requests)\n- [Http client](#http-client)\n- [Database](#database)\n- [Redis](#redis)\n- [Queue jobs](#redis)\n- [Logs context](#logs-context)\n- [Manual traces](#manual-traces)\n\n### Http server requests\n\nHttp server requests are automatically traced by injecting `\\Keepsuit\\LaravelOpenTelemetry\\Support\\HttpServer\\TraceRequestMiddleware::class` to the global middlewares.\nYou can disable it by setting `OT_INSTRUMENTATION_HTTP_SERVER` to `false` or removing the `HttpServerInstrumentation::class` from the config file.\n\nConfiguration options:\n\n- `excluded_paths`: list of paths to exclude from tracing\n- `allowed_headers`: list of headers to include in the trace\n- `sensitive_headers`: list of headers with sensitive data to hide in the trace\n\n### Http client\n\nTo trace an outgoing http request call the `withTrace` method on the request builder.\n\n```php\nHttp::withTrace()-\u003eget('https://example.com');\n```\n\nYou can disable it by setting `OT_INSTRUMENTATION_HTTP_CLIENT` to `false` or removing the `HttpClientInstrumentation::class` from the config file.\n\nConfiguration options:\n\n- `allowed_headers`: list of headers to include in the trace\n- `sensitive_headers`: list of headers with sensitive data to hide in the trace\n\n### Database\n\nDatabase queries are automatically traced.\nYou can disable it by setting `OT_INSTRUMENTATION_QUERY` to `false` or removing the `QueryInstrumentation::class` from the config file.\n\n### Redis\n\nRedis commands are automatically traced.\nYou can disable it by setting `OT_INSTRUMENTATION_REDIS` to `false` or removing the `RedisInstrumentation::class` from the config file.\n\n### Queue jobs\n\nQueue jobs are automatically traced.\nIt 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.\nYou can disable it by setting `OT_INSTRUMENTATION_QUEUE` to `false` or removing the `QueueInstrumentation::class` from the config file.\n\n### Logs context\n\nWhen starting a trace with provided instrumentation, the trace id is automatically injected in the log context.\nThis allows to correlate logs with traces.\n\nIf you are starting the root trace manually,\nyou should call `Tracer::updateLogContext()` to inject the trace id in the log context.\n\n\u003e [!NOTE]\n\u003e When using the OpenTelemetry logs driver (`otlp`),\n\u003e the trace id is automatically injected in the log context without the need to call `Tracer::updateLogContext()`.\n\n### Manual traces\n\nSpans can be manually created with the `newSpan` method on the `Tracer` facade.\nThis method returns a `SpanBuilder` instance that can be used to customize and start the span.\n\nThe simplest way to create a custom trace is with `measure` method:\n\n```php\nuse Keepsuit\\LaravelOpenTelemetry\\Facades\\Tracer;\n\nTracer::newSpan('my custom trace')-\u003emeasure(function () {\n    // do something\n});\n```\n\nAlternatively you can manage the span manually:\n\n```php\nuse Keepsuit\\LaravelOpenTelemetry\\Facades\\Tracer;\n\n$span = Tracer::newSpan('my custom trace')-\u003estart();\n\n// do something\n\n$span-\u003eend();\n```\n\nWith `measure` the span is automatically set to active (so it will be used as parent for new spans).\nWith `start` you have to manually set the span as active:\n\n```php\nuse Keepsuit\\LaravelOpenTelemetry\\Facades\\Tracer;\n\n$span = Tracer::newSpan('my custom trace')-\u003estart();\n$scope = $span-\u003eactivate()\n\n// do something\n\n$scope-\u003edetach();\n$span-\u003eend();\n```\n\nOther utility methods are available on the `Tracer` facade:\n\n```php\nuse Keepsuit\\LaravelOpenTelemetry\\Facades\\Tracer;\n\nTracer::traceId(); // get the active trace id\nTracer::activeSpan(); // get the active span\nTracer::activeScope(); // get the active scope\nTracer::currentContext(); // get the current trace context (useful for advanced use cases)\nTracer::propagationHeaders(); // get the propagation headers required to propagate the trace to other services\nTracer::extractContextFromPropagationHeaders(array $headers); // extract the trace context from propagation headers\n```\n\n## Metrics\n\nYou can create custom meters using the `Meter` facade:\n\n```php\nuse Keepsuit\\LaravelOpenTelemetry\\Facades\\Meter;\n\n// create a counter meter\n$meter = Meter::createCounter('my-meter', 'times', 'my custom meter');\n$meter-\u003eadd(1);\n\n// create a histogram meter\n$meter = Meter::createHistogram('my-histogram', 'ms', 'my custom histogram');\n$meter-\u003erecord(100, ['name' =\u003e 'value', 'app' =\u003e 'my-app']);\n\n// create a gauge meter\n$meter = Meter::createGauge('my-gauge', null, 'my custom gauge');\n$meter-\u003erecord(100, ['name' =\u003e 'value', 'app' =\u003e 'my-app']);\n$meter-\u003erecord(1.2, ['name' =\u003e 'percentage', 'app' =\u003e 'my-app']);\n```\n\n### Metrics Temporality\n\nThe OTLP exporter supports setting a preferred temporality for exported metrics with `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` env variable.\nThe supported values are `Delta` and `Cumulative`.\nIf not set, the default temporality for each metric type will be used.\n\n## Logs\n\nThis package provides a custom log channel that allows to process logs with OpenTelemetry instrumentation.\nThis packages injects a log channel named `otlp` that can be used to send logs to OpenTelemetry using laravel default log system.\n\n```php\n// config/logging.php\n'channels' =\u003e [\n    // injected channel config, you can override it adding an `otlp` channel in your config\n    'otlp' =\u003e [\n        'driver' =\u003e 'monolog',\n        'handler' =\u003e \\Keepsuit\\LaravelOpenTelemetry\\Support\\OpenTelemetryMonologHandler::class,\n        'level' =\u003e 'debug',\n    ]\n]\n```\n\nAs an alternative, you can use the `Logger` facade to send logs directly to OpenTelemetry:\n\n```php\nuse Keepsuit\\LaravelOpenTelemetry\\Facades\\Logger;\n\nLogger::emergency('my log message');\nLogger::alert('my log message');\nLogger::critical('my log message');\nLogger::error('my log message');\nLogger::warning('my log message');\nLogger::notice('my log message');\nLogger::info('my log message');\nLogger::debug('my log message');\n```\n\n### Development Setup\n\nTo simplify development, a `Makefile` is provided. The project runs in a Docker container that mirrors your host user's UID and GID to avoid permission issues.\n\n#### Available Makefile Commands\n\n| Command        | Description                                                                 |\n|----------------|-----------------------------------------------------------------------------|\n| `make build`   | Builds the Docker image with your UID/GID for proper file permissions.     |\n| `make start`   | Starts the containers in the background using Docker Compose.              |\n| `make stop`    | Stops and removes the containers.                                           |\n| `make shell`   | Starts the containers (if needed) and opens a Bash shell in the `app` one. |\n| `make test`    | Runs the test suite via Composer inside the `app` container.               |\n| `make lint`    | Runs the linter via Composer inside the `app` container.                   |\n\n\n\u003e 📝 Before using `make shell`, ensure the container is running (`make start` in another terminal).\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Credits\n\n- [Fabio Capucci](https://github.com/keepsuit)\n- [Aurimas Niekis](https://github.com/aurimasniekis)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeepsuit%2Flaravel-opentelemetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeepsuit%2Flaravel-opentelemetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeepsuit%2Flaravel-opentelemetry/lists"}