包简介

Add tracing to your Symfony application.

README 文档

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 only enabled for tagged clients)
Messenger messages (by default enabled)
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 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.

# /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

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.

<!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

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:

// 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.

digitalrevolution/symfony-trace-bundle 适用场景与选型建议

digitalrevolution/symfony-trace-bundle 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 97.98k 次下载、GitHub Stars 达 8，最近一次更新时间为 2023 年 12 月 18 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 digitalrevolution/symfony-trace-bundle 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 digitalrevolution/symfony-trace-bundle 我们能提供哪些服务？

定制开发 / 二次开发

基于 digitalrevolution/symfony-trace-bundle 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

digitalrevolution/symfony-trace-bundle

包简介