digitalrevolution / symfony-trace-bundle
Add tracing to your Symfony application.
Installs: 14 843
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 1
Forks: 2
Open Issues: 2
Type:symfony-bundle
Requires
- php: >=8.1
- symfony/config: ^6.3||^7.0
- symfony/dependency-injection: ^6.3||^7.0
- symfony/framework-bundle: ^6.3||^7.0
- symfony/http-foundation: ^6.3||^7.0
- symfony/http-kernel: ^6.3||^7.0
Requires (Dev)
- digitalrevolution/accessorpair-constraint: ^2.1
- digitalrevolution/phpunit-extensions: ^1.2
- digitalrevolution/phpunit-file-coverage-inspection: ^v2.0.0
- digitalrevolution/utils: ^1.9
- phpmd/phpmd: ^2.14
- phpstan/extension-installer: ^1.3
- phpstan/phpstan: ^1.10
- phpstan/phpstan-phpunit: ^1.3
- phpstan/phpstan-strict-rules: ^1.5
- phpstan/phpstan-symfony: ^1.3
- phpunit/phpunit: ^10.4 || ^11.0
- ramsey/uuid: ^4.7
- roave/security-advisories: dev-latest
- sentry/sentry: ^4.2
- squizlabs/php_codesniffer: ^3.7
- symfony/browser-kit: ^6.3||^7.0
- symfony/css-selector: ^6.3||^7.0
- symfony/http-client: ^6.3||^7.0
- symfony/messenger: ^6.3||^7.0
- symfony/monolog-bridge: ^6.3||^7.0
- symfony/monolog-bundle: ^3.10
- symfony/phpunit-bridge: ^6.3||^7.0
- symfony/templating: ^6.3||^7.0
- symfony/twig-bundle: ^6.3||^7.0
- symfony/uid: ^6.3||^7.0
- symfony/yaml: ^6.3||^7.0
- twig/twig: ^3.8.0
Suggests
- ramsey/uuid: Ramsey's UUID generator
- sentry/sentry: Sentry.io integration
- symfony/http-client: Symfony's HTTP client
- symfony/messenger: Symfony's messenger
- symfony/uid: Symfony's UUID generator
README
Symfony Trace Bundle
Based on chrisguitarguy/RequestIdBundle
This adds trace ID's to your Symfony application. Why? It's a great way to add some additional information to logs and to present to users. The trace id will be available in:
- Monolog log messages
- Request -> Response
- Console command
- Twig as extension
- HttpClient requests (by default disabled)
- Messenger messages (by default disabled)
- Sentry reports (by default disabled)
Installation
Use Composer.
composer require digitalrevolution/symfony-trace-bundle
Then enable the bundle in your /config/bundles.php
:
# /config/bundles.php <?php return [ ... DR\SymfonyTraceBundle\SymfonyTraceBundle::class => ['all' => true], ];
Configuration
By default, the bundle will use the W3C TraceContext standard to receive and pass on the traceId.
For configuration details see: TraceContext configuration
It's also possible to configure the bundle to setup custom request/response headers and custom ID generators.
Read more about the available configuration options on TraceId configuration in the /docs pages.
How it Works
When a request arrives, it is inspected for request header containing a traceId. If present, the value in that header will be used throughout the rest of the bundle. This lets you use trace ID's from somewhere higher up in the stack (like in the web server itself).
If no trace ID is found, one is generated by the TraceIdGeneratorInterface
.
In tracecontext mode, the IDs are generated according to the TraceContext standard.
The default generator in traceId mode creates version 4 UUIDs.
On the way out, a response header can be set on the response as well using the value(s) described above.
The headers are configurable. See the configuration above. Internally a transaction ID is generator as well. This ID is used to identify a single request.
Monolog Integration
There's a monolog Processor that adds the trace ID and transaction ID to extra
array on the record.
This can be turned off by setting enable_monolog
to false
in the configuration.
To use the trace ID in your logs, include %extra.trace_id%
in your formatter.
To use the transaction ID in your logs, include %extra.transaction_id%
in your formatter.
Here's a configuration example from this bundle's tests.
# /config/services.php $services->set('trace_id_formatter', LineFormatter::class) ->arg('$format', "[%%datetime%%][%%extra.trace_id%%][%%extra.transaction_id%%] %%channel%%.%%level_name%%: %%message%% %%extra%%\n") ->arg('$dateFormat', "Y-m-d\TH:i:s");
# /config/packages/monolog.php $monolog->handler('main') ->type('stream') ->path('%kernel.logs_dir%/error.%kernel.environment%.log') ->level('debug') ->formatter('trace_id_formatter') ->channels()->elements(["!event"]);
Messenger Integration
When enabled, the full trace data of the dispatcher process, will be added to the Envelope
of the message. On the consumer
side the trace data will be applied to the running consumer process. Once the Envelope
has been handled, the values
will be reset to the original values of the consumer process (if any).
Twig Integration
By default, this bundle will add a global trace_id
and transaction_id
function to your twig
environment. To disable this set enable_twig
to false
in the bundle
configuration.
Here's an example of a template.
<!DOCTYPE html> <html> <head> <title>Hello, World</title> </head> <body> <h1>{{ trace_id() }}</h1> <h2>{{ transaction_id() }}</h2> </body> </html>
HttpClient integration
By default this bundle will check for services tagged with the http_client.trace_id
tag and decorate them with the TraceAwareHttpClient.
When tagDefaultClient
is enabled the default symfony http client will also be tagged and thus decorated.
This will add the trace header(s) to all outgoing requests for the tagged clients.
In traceId mode the header name can be changed with the header
configuration option.
Sentry integration
When enabled, the bundle will add trace_id
and transaction_id
tags to the Sentry reports.
About us
At 123inkt (Part of Digital Revolution B.V.), every day more than 50 development professionals are working on improving our internal ERP and our several shops. Do you want to join us? We are looking for developers.