https://github.com/123inkt/symfony-trace-bundle
Add request ID's to your Symfony application.
https://github.com/123inkt/symfony-trace-bundle
console logging messenger monolog request-id trace-id traceability twig
Last synced: about 2 months ago
JSON representation
Add request ID's to your Symfony application.
- Host: GitHub
- URL: https://github.com/123inkt/symfony-trace-bundle
- Owner: 123inkt
- License: mit
- Created: 2023-11-27T21:30:44.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2024-03-15T07:19:11.000Z (over 1 year ago)
- Last Synced: 2024-03-15T17:14:24.240Z (over 1 year ago)
- Topics: console, logging, messenger, monolog, request-id, trace-id, traceability, twig
- Language: PHP
- Homepage:
- Size: 95.7 KB
- Stars: 2
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[](https://php.net/)
[](https://symfony.com/doc/current/validation.html)
# Symfony Trace Bundle
*Based on [chrisguitarguy/RequestIdBundle](https://github.com/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 only enabled for tagged clients)
- Messenger messages (by default enabled)
- Sentry reports (by default disabled)
## Installation
Use [Composer](https://getcomposer.org/).
```
composer require digitalrevolution/symfony-trace-bundle
```
Then enable the bundle in your `/config/bundles.php`:
```php
# /config/bundles.php
['all' => true],
];
```
## Configuration
By default, the bundle will use the [W3C TraceContext](https://www.w3.org/TR/trace-context/) standard to receive and pass on the traceId.
For configuration details see: [TraceContext configuration](docs/configuration/tracecontext.md)
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](docs/configuration/traceid.md) 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](#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 `monolog.enabled` 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.
```php
# /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");
```
```php
# /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
By default, 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 `twig.enabled` to `false` in the bundle
configuration.
Here's an example of a template.
```html
Hello, World
{{ trace_id() }}
{{ transaction_id() }}
```
## 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
By default sentry has its own trace id and transaction id which will be propagated through the Sentry SDK. However this traceId will be different
than the one generated by this bundle. To fully integrate with Sentry you have to set `$config->sentry()->enabled(true)` for this bundle and
disable Sentry's own tracing by setting `$sentry->tracing()->enabled(false);` in your Sentry configuration.
**Example:**
```php
// config/packages/sentry.php
return static function (SentryConfig $sentry): void {
$sentry->tracing()->enabled(false);
};
// config/packages/symfony_trace_bundle.php
return static function (SymfonyTraceConfig $config): void {
$config->sentry()->enabled(true);
};
```
This will ensure that the traceId and transactionId generated by this bundle will be used in 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](https://www.werkenbij123inkt.nl/zoek-op-afdeling/it).