README

这个 symfony 组件集合为 symfony 应用程序提供启用分布式跟踪所需的一切。

它使用 PHP 实现 的 opentracing 规范，并以有见地的形式进行包装。它还旨在不会干扰您的应用程序，通过不在 Symfony 生命周期中尽可能晚地抛出异常并将跟踪数据发送到代理来实现。

核心包含

• kernel/console 事件订阅者，用于自动检测应用程序，向根跨度添加有用的标签
• 便利函数以手动创建跟踪跨度，包括记录消息和标记跨度
• PSR-18 客户端的自动跟踪头传播
• 一个便利函数，用于手动将跟踪头传递给 PSR-7 请求或数组

额外的组件包含

• monolog 处理器，用于使用当前跨度上下文丰富日志上下文
• Guzzle 客户端 自动创建跨度并传播头信息
• php-http/httplug-bundle 自动创建跨度并传播头信息
• Doctrine DBAL 自动创建跨度
• amqplib/RabbitMQ 自动创建跨度并传播头信息
• eMAGTechLabs/RabbitMqBundle 自动创建跨度并传播头信息

安装

选择跟踪实现

核心本身只是一个库，不应直接安装。您需要从不同的跟踪实现组件中选择，然后它们将使用此库。

Jaeger

• 要求依赖关系

    composer req auxmoney/opentracing-bundle-jaeger

• 如果没有已经完成：启动 开发 Jaeger 实例（全部包含在内）

注意：在设置可靠的生成环境时，请记住使用 Jaeger 提出的代理方法。特别是理想情况下在 localhost 上拥有 jaeger 代理将防止您因为涉及网络对 UDP 数据包大小的限制而丢失跟踪或跨度。

Zipkin

• 要求依赖关系

    composer req auxmoney/opentracing-bundle-zipkin

• 如果没有已经完成：启动 开发 Zipkin 实例（Docker）

启用组件

如果您正在使用 Symfony Flex，那么您已经准备好了！

如果您没有使用它，您需要手动启用组件

• 将组件添加到您的应用程序中

    # Symfony 3: AppKernel.php
    $bundles[] = new Auxmoney\OpentracingBundle\OpentracingBundle();

    # Symfony 4+: bundles.php
    Auxmoney\OpentracingBundle\OpentracingBundle::class => ['all' => true],

配置

您可以选择配置环境变量，但是默认配置将针对本地主机上的跟踪代理正常工作。如果无法更改项目中环境变量，您可以替换直接覆盖容器参数。

使用

跟踪头的传播

对于 PSR-18 兼容的客户端，此组件提供自动跟踪头传播。

对于 Guzzle 客户端，Guzzle 扩展包 提供了自动跟踪头传播。

手动传播跟踪头

如果您既不使用 PSR-18 也不使用 Guzzle，您需要将跟踪头注入到每个发出的 PSR-7 兼容请求中。要做到这一点，只需使用

    Auxmoney\OpentracingBundle\Service\Tracing::injectTracingHeaders(Psr\Http\Message\RequestInterface $request): Psr\Http\Message\RequestInterface

请求，并使用您的首选请求客户端的结果请求。

如果您使用的是不兼容 PSR-7 的请求，您可以直接使用以下方法将头信息注入到数组中

    Auxmoney\OpentracingBundle\Service\Tracing::injectTracingHeadersIntoCarrier(array $carrier): array

传递代表您请求头部的数组，并使用您的首选请求客户端的结果数组。

自动跟踪

默认情况下，此扩展包将自动跟踪一些跨度

• 内核生命周期跨度（从 kernel.request 到 kernel.finish_request）
• 控制器生命周期跨度（从每个 kernel.controller 到每个 kernel.response，包括 kernel.exception）
• 命令生命周期跨度（从 console.command 到 console.terminate，包括 console.error）

在抛出异常的情况下，它还会将异常类型和消息记录到控制器/命令跨度中。

手动跟踪

您可以自动注入跟踪服务（通过自动装配）或使用提供的服务别名 @auxmoney_opentracing。

手动跨度

您可以通过使用以下方法手动定义跨度

    Auxmoney\OpentracingBundle\Service\Tracing::startActiveSpan(string $operationName, array $options = null): void

和

    Auxmoney\OpentracingBundle\Service\Tracing::finishActiveSpan(): void

分别。

$operationName 是跟踪操作的显示名称，$options 是跟踪选项的关联数组；主要用法是 $options['tags']，这是一个用户定义标签的关联数组（键值对）。有关启动跨度的更多信息，请参阅 文档。

标记跨度

您可以使用以下方法设置当前活动跨度的标签（键值对）

    Auxmoney\OpentracingBundle\Service\Tracing::setTagOfActiveSpan(string $key, string|bool|int|float $value): void

设置跨度标签时，应遵守 opentracing 项目的跨度约定。

在跨度中记录

您可以通过以下方式始终将日志（键值对）附加到当前活动跨度

    Auxmoney\OpentracingBundle\Service\Tracing::logInActiveSpan(array $fields): void

在记录字段时，应遵守 opentracing 项目的日志约定。

行李物品

您可以使用以下方法在进程边界内带内传播行李物品（键值对）

    Auxmoney\OpentracingBundle\Service\Tracing::setBaggageItem(string $key, string $value): void

并使用以下方法检索它们

    Auxmoney\OpentracingBundle\Service\Tracing::getBaggageItem(string $key): ?string

您应谨慎且谨慎地使用此功能。每个键和值都会复制到相关 Span 的每个本地和远程子代，这可能导致大量的网络和 CPU 负载。

开发

请确保在每次推送代码更改之前运行

    composer run-script quality

该脚本运行的工具也在 CI 管道中运行。

文档

有关扩展包及其使用的各种信息可在 文档部分 中找到。