{"id":15045097,"url":"https://github.com/auxmoney/opentracingbundle-core","last_synced_at":"2025-10-08T07:41:56.502Z","repository":{"id":38109357,"uuid":"232122387","full_name":"auxmoney/OpentracingBundle-core","owner":"auxmoney","description":"Collection of symfony bundles providing everything needed for a symfony application to enable distributed tracing","archived":false,"fork":false,"pushed_at":"2023-04-25T15:13:13.000Z","size":432,"stargazers_count":25,"open_issues_count":9,"forks_count":14,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-01-31T04:32:08.518Z","etag":null,"topics":["auxmoney","distributed-tracing","guzzle","jaeger","monolog","opentracing","opentracing-bundle","symfony","symfony-bundle","zipkin"],"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/auxmoney.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2020-01-06T14:50:48.000Z","updated_at":"2024-11-14T09:35:55.000Z","dependencies_parsed_at":"2024-06-18T15:18:17.680Z","dependency_job_id":"54dda3c9-1f75-4c3f-b234-bbd3acd8dac1","html_url":"https://github.com/auxmoney/OpentracingBundle-core","commit_stats":{"total_commits":97,"total_committers":12,"mean_commits":8.083333333333334,"dds":0.6082474226804124,"last_synced_commit":"37c5ace4ea09dcdf82c452595254ae83846bd319"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auxmoney%2FOpentracingBundle-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auxmoney%2FOpentracingBundle-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auxmoney%2FOpentracingBundle-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auxmoney%2FOpentracingBundle-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/auxmoney","download_url":"https://codeload.github.com/auxmoney/OpentracingBundle-core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238053514,"owners_count":19408699,"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":["auxmoney","distributed-tracing","guzzle","jaeger","monolog","opentracing","opentracing-bundle","symfony","symfony-bundle","zipkin"],"created_at":"2024-09-24T20:51:27.223Z","updated_at":"2025-10-08T07:41:51.464Z","avatar_url":"https://github.com/auxmoney.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# auxmoney OpentracingBundle\n\n[![test](https://github.com/auxmoney/OpentracingBundle-core/workflows/test/badge.svg)](https://github.com/auxmoney/OpentracingBundle-core/actions?query=workflow%3Atest)\n![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/auxmoney/OpentracingBundle-core)\n![Codacy Badge](https://api.codacy.com/project/badge/Grade/fc044c88d4e046ab8813be04032a29a4)\n![Code Climate maintainability](https://img.shields.io/codeclimate/maintainability/auxmoney/OpentracingBundle-core)\n![Scrutinizer code quality (GitHub/Bitbucket)](https://img.shields.io/scrutinizer/quality/g/auxmoney/OpentracingBundle-core)\n![GitHub](https://img.shields.io/github/license/auxmoney/OpentracingBundle-core)\n\nThis collection of symfony bundles provides everything needed for a symfony application to enable distributed tracing.\n\nIt utilizes the [PHP implementation](https://github.com/opentracing/opentracing-php) of the [opentracing specification](https://opentracing.io/specification/) \nand wraps it in an opinionated fashion. It also aims to never disrupt your application, by not throwing exceptions and sending tracing data\nto the agent as late as possible in the Symfony lifecycle.\n\nThe core contains:\n* kernel/console event subscribers to automatically instrument the application, adding useful tags to root spans\n* convenience functions to create tracing spans manually, including logging messages and tagging spans\n* automatic tracing header propagation for PSR-18 clients\n* a convenience function for passing the tracing headers to PSR-7 requests or arrays manually\n\nAdditional bundles contain:\n* [a monolog processor](https://github.com/auxmoney/OpentracingBundle-Monolog) to enrich log contexts with the current span context\n* [Guzzle client](https://github.com/auxmoney/OpentracingBundle-Guzzle) automatic spanning and header propagation\n* [php-http/httplug-bundle](https://github.com/auxmoney/OpentracingBundle-HttplugBundle) automatic spanning and header propagation\n* [Doctrine DBAL](https://github.com/auxmoney/OpentracingBundle-Doctrine-DBAL) automatic spanning\n* [amqplib/RabbitMQ](https://github.com/auxmoney/OpentracingBundle-amqplib-RabbitMq) automatic spanning and header propagation\n* [eMAGTechLabs/RabbitMqBundle](https://github.com/auxmoney/OpentracingBundle-eMAGTechLabs-RabbitMqBundle) automatic spanning and header propagation\n\n## Installation\n\n### Choose tracer implementation\n\nThe core itself is only a library and should not be installed directly. You need to choose from different tracer implementation bundles, \nwhich will then use this library.\n\n#### Jaeger\n\n* require the dependencies:\n\n```bash\n    composer req auxmoney/opentracing-bundle-jaeger\n```\n\n* if not done already: spin up [development jaeger instance](https://www.jaegertracing.io/docs/latest/getting-started/) (All in One)\n\nNote: when setting up a reliable production environment, keep in mind using the agent approach, that Jaeger proposes. Especially having\nthe jaeger agent ideally available on `localhost` will prevent you from experiencing trace or span loss due to UDP packet size limitations\nby the involved networks.\n\n#### Zipkin\n\n* require the dependencies:\n\n```bash\n    composer req auxmoney/opentracing-bundle-zipkin\n```\n\n* if not done already: spin up [development zipkin instance](https://zipkin.io/pages/quickstart) (Docker)\n\n### Enable the bundle\n\nIf you are using [Symfony Flex](https://github.com/symfony/flex), you are all set!\n\nIf you are not using it, you need to manually enable the bundle:\n\n* add bundle to your application:\n\n```php\n    # Symfony 3: AppKernel.php\n    $bundles[] = new Auxmoney\\OpentracingBundle\\OpentracingBundle();\n```\n\n```php\n    # Symfony 4+: bundles.php\n    Auxmoney\\OpentracingBundle\\OpentracingBundle::class =\u003e ['all' =\u003e true],\n```\n\n## Configuration\n\nYou can optionally configure environment variables, however, the default configuration will run fine out of the box for a tracing agent on localhost.\nIf you cannot change environment variables in your project, you can alternatively overwrite the container parameters directly.\n\n| environment variable | container parameter | type | default | description |\n|---|---|---|---|---|\n| AUXMONEY_OPENTRACING_AGENT_HOST | auxmoney_opentracing.agent.host | `string` | `localhost` | hostname or IP of the agent |\n| AUXMONEY_OPENTRACING_AGENT_PORT | auxmoney_opentracing.agent.port | `string` | (depends on the chosen tracer) | port of the agent |\n| AUXMONEY_OPENTRACING_PROJECT_NAME | auxmoney_opentracing.project.name | `string` | `basename(kernel.project_dir)` |  passed to the tracer as tracer name / service name |\n| AUXMONEY_OPENTRACING_SAMPLER_CLASS | auxmoney_opentracing.sampler.class | `string` | (depends on the chosen tracer) | class of the using sampler |\n| AUXMONEY_OPENTRACING_SAMPLER_VALUE | auxmoney_opentracing.sampler.value | `string` | (depends on the chosen tracer and sampler) | must be a JSON decodable string, for the configuration of the chosen sampler |\n| AUXMONEY_OPENTRACING_RESPONSE_HEADER | auxmoney_opentracing.response.header | `string` | `true` | if HTTP responses should ship the trace id as header; set to `false` (as string) to deactivate |\n\n## Usage\n\n### Propagation of tracing headers\n\nFor [PSR-18](https://www.php-fig.org/psr/psr-18/) compatible clients, this bundle provides automatic tracing header propagation.\n\nFor [Guzzle](https://github.com/guzzle/guzzle) clients, the [Guzzle bundle](https://github.com/auxmoney/OpentracingBundle-Guzzle) provides automatic tracing header propagation.\n\n#### Manual propagation of tracing headers\n\nIf you use neither PSR-18 nor Guzzle, you need to inject the trace headers into every outgoing [PSR-7](https://www.php-fig.org/psr/psr-7/) compatible request. To do so, simply use\n\n```php\n    Auxmoney\\OpentracingBundle\\Service\\Tracing::injectTracingHeaders(Psr\\Http\\Message\\RequestInterface $request): Psr\\Http\\Message\\RequestInterface\n```\n\non the request and use the resulting request with your favorite request client.\n\nIf you are using a request that is not PSR-7 compatible, you can inject the headers directly into an array using\n\n```php\n    Auxmoney\\OpentracingBundle\\Service\\Tracing::injectTracingHeadersIntoCarrier(array $carrier): array\n```\n\npassing the array representing the headers of your request and use the resulting array with your favorite request client.\n\n### Automatic tracing\n\nOut of the box, the bundle will trace some spans automatically:\n* span of the kernel lifecycle (from `kernel.request` to `kernel.finish_request`)\n* span of controller lifecycles (from each `kernel.controller` to each `kernel.response`, including `kernel.exception`)\n* span of the command lifecycle (from `console.command` to `console.terminate`, including `console.error`)\n\nIn case of exceptions thrown, it will additionally log exception types and messages to a controller/command span.\n\n### Manual tracing\n\nYou can inject the tracing service automatically (via autowiring) or use the provided service alias `@auxmoney_opentracing`.\n\n#### Manual spanning\n\nYou can define spans manually, by using\n\n```php\n    Auxmoney\\OpentracingBundle\\Service\\Tracing::startActiveSpan(string $operationName, array $options = null): void\n```\n\nand \n\n```php\n    Auxmoney\\OpentracingBundle\\Service\\Tracing::finishActiveSpan(): void\n```\n\nrespectively.\n\n`$operationName` is the displayed name of the trace operation, `$options` is an associative array of tracing options; the main usage is \n`$options['tags']`, which is an associative array of user defined tags (key value pairs). See the\n[documentation for starting spans](https://github.com/opentracing/opentracing-php#using-startspanoptions) for more information.\n\n#### Tagging spans\n\nYou can set tags (key value pairs) to the currently active span with\n\n```php\n    Auxmoney\\OpentracingBundle\\Service\\Tracing::setTagOfActiveSpan(string $key, string|bool|int|float $value): void\n```\n\nYou should respect the [span conventions of the opentracing project](https://github.com/opentracing/specification/blob/master/semantic_conventions.md#span-tags-table)\nwhen setting tags to spans.\n\n#### Logging in spans\n\nYou can always attach logs (key value pairs) to the currently active span with\n\n```php\n    Auxmoney\\OpentracingBundle\\Service\\Tracing::logInActiveSpan(array $fields): void\n```\n\nYou should respect the [log conventions of the opentracing project](https://github.com/opentracing/specification/blob/master/semantic_conventions.md#log-fields-table)\nwhen logging fields.\n\n#### Baggage items\n\nYou can propagate baggage items (key value pairs) in-band across process boundaries with\n\n```php\n    Auxmoney\\OpentracingBundle\\Service\\Tracing::setBaggageItem(string $key, string $value): void\n```\n\nand retrieve them with \n\n```php\n    Auxmoney\\OpentracingBundle\\Service\\Tracing::getBaggageItem(string $key): ?string\n```\n\nYou should use this feature thoughtfully and with care. Every key and value is copied into every local and remote\nchild of the associated Span, and that can add up to a lot of network and cpu overhead.\n\n## Development\n\nBe sure to run\n\n```bash\n    composer run-script quality\n```\n\nevery time before you push code changes. The tools run by this script are also run in the CI pipeline.\n\n## Doc\n\nVarious informations regarding the bundle and its usage is available in the [doc section](./doc/README.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauxmoney%2Fopentracingbundle-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fauxmoney%2Fopentracingbundle-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauxmoney%2Fopentracingbundle-core/lists"}