README

Symfony应用的Zipkin集成

安装

composer require jcchavezs/zipkin-instrumentation-symfony

入门

此Symfony包提供了一个内核监听器，可用于跟踪HTTP请求。为了使用它，您需要通过在您的 app/config/services.yml 或其他任何 依赖注入 声明中添加来声明监听器。

services:
  tracing_kernel_listener:
    class: ZipkinBundle\KernelListener
    arguments:
      - "@zipkin.default_http_server_tracing"
      - "@zipkin.route_mapper"
      - "@logger"
    tags:
      - { name: kernel.event_listener, event: kernel.request, priority: 2560 }
      - { name: kernel.event_listener, event: kernel.response, priority: -2560 }
      - { name: kernel.event_listener, event: kernel.exception }
      - { name: kernel.event_listener, event: kernel.terminate }

@zipkin.default_tracing 是一个基于配置（添加到 app/config/config.yml）构建的 Zipkin\DefaultTracing 实例。

zipkin:
  noop: false # if set to true, no request will be traced
  service_name: my_service # the name of the service
  sampler:
    type: percentage
    percentage: 0.1

采样器

除了 always 和 never 之外，还有三种其他采样策略：按路径、按路由 和 按百分比，但是您也可以使用自己的采样器。

需要注意的是，采样决策在两种情况下做出：a) 当一个新的跟踪正在开始时，b) 当提取的上下文不包括采样决策时。

按路径

这是针对您想要基于URL路径做出采样决策的情况。

zipkin:
  ...
  sampler:
    type: path
    path:
      included_paths:
        - "/my/resource/[0-9]"
      excluded_paths:
        - "/another/path/"

此采样器使用 Symfony\Component\HttpFoundation\RequestStack，这意味着它不适用于事件循环环境。对于事件循环环境，请在HTTP服务器跟踪中使用 requestSampler。

按路由

这是针对您想要基于symfony路由做出采样决策的情况。

zipkin:
  ...
  sampler:
    type: route
    route:
      included_routes:
        - "my_route"
      excluded_routes:
        - "another_route"

此采样器使用 Symfony\Component\HttpFoundation\RequestStack，这意味着它不适用于事件循环环境。对于事件循环环境，请在HTTP服务器跟踪中使用 requestSampler。

按百分比

这是针对您只想对请求的一部分进行采样（即“采样率”）的情况。

zipkin:
  ...
  sampler:
    type: percentage
    percentage: 0.1

自定义采样器

只要它实现了 Zipkin\Sampler 接口，您就可以传递一个自定义采样器。您只需要使用服务容器中声明的 id。

zipkin:
  ...
  sampler:
    type: custom
    custom: my_service_name

报告者

默认情况下，该包报告到 Log 报告者，它包装了 @logger。

HTTP报告者

这是最常见的情况，它报告到Zipkin的HTTP后端。

zipkin:
  ...
  reporter:
    type: http
    http:
      endpoint_url: http://zipkin:9411/api/v2/spans
      timeout: ~

默认标签

您可以为由跟踪器创建的每个span添加标签。当您需要添加实例名称之类的标签时，此功能非常有用。

services:
  tracing_kernel_listener:
    class: ZipkinBundle\KernelListener
    arguments:
      - "@zipkin.default_http_server_tracing"
      - "@zipkin.route_mapper"
      - "@logger"
      - { instance: %instance_name% }
    tags:
      - { name: kernel.event_listener, event: kernel.request, priority: 2560 }
      - { name: kernel.event_listener, event: kernel.response, priority: -2560 }
      - { name: kernel.event_listener, event: kernel.exception }
      - { name: kernel.event_listener, event: kernel.terminate }

自定义跟踪

尽管此包提供了基于 zipkin 节点下配置参数的跟踪器，但是只要它实现了 Zipkin\Tracing 接口，您就可以将您自己的 跟踪组件 注入到内核监听器。

services:
  tracing_kernel_listener:
    class: ZipkinBundle\KernelListener
    arguments:
      - "@my_own_http_server_tracing"
      - "@zipkin.route_mapper"
      - "@logger"
    tags:
      - { name: kernel.event_listener, event: kernel.request, priority: 2560 }
      - { name: kernel.event_listener, event: kernel.response, priority: -2560 }
      - { name: kernel.event_listener, event: kernel.exception }
      - { name: kernel.event_listener, event: kernel.terminate }

Span自定义

默认情况下，span包含常用的HTTP信息，如方法、路径或状态码，但在某些情况下，用户可能希望根据请求（例如，request_id 或查询参数）在span中添加更多信息。在这种情况下，可以通过扩展 HttpServerParser 来访问请求并标记span。

services:
  search.http_server_tracing:
    class: Zipkin\Instrumentation\Http\Server\HttpServerTracing
    arguments:
      - "@zipkin.default_tracing"
      - "@zipkin.route_mapper"
      - "@search_http_parser" # my own parser

  tracing_kernel_listener:
    class: ZipkinBundle\KernelListener
    arguments:
      - "@search.http_server_tracing"
      - "@logger"
      - { instance: %instance_name% }
    tags:
      - { name: kernel.event_listener, event: kernel.request, priority: 2560 }
      - { name: kernel.event_listener, event: kernel.response, priority: -2560 }
      - { name: kernel.event_listener, event: kernel.exception }
      - { name: kernel.event_listener, event: kernel.terminate }

  search_http_parser:
    class: My\Search\HttpServerParser

并且解析器将如下所示

namespace My\Search;

use Zipkin\Instrumentation\Http\Server\DefaultHttpServerParser;
use Zipkin\Instrumentation\Http\Server\Response;
use Zipkin\Instrumentation\Http\Server\Request;
use Zipkin\Propagation\TraceContext;
use Zipkin\SpanCustomizer;

final class HttpServerParser extends DefaultHttpServerParser {
    public function request(Request $request, TraceContext $context, SpanCustomizer $span): void {
        parent::request($request, $context, $span);
        if (null !== ($searchKey = $request->getHeader('search_key'))) {
            $span->tag('search_key', $searchKey);
        }
    }
}

HTTP客户端

此包包含一个HTTP客户端适配器。有关更多详细信息，请参阅 此文档。

贡献

所有贡献和反馈都受欢迎。

单元测试

使用以下命令运行单元测试：

composer test

端到端测试

在每次构建时，我们都会对 symfony 应用程序运行一个端到端（E2E）测试。

此测试在我们的 CI 测试中运行，但它也可以在本地重现。