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.

digitalrevolution / symfony-trace-bundle

Maintainers

Details