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信息，如方法、路径或状态码，但在某些情况下，用户希望在span中添加更多基于请求的信息（例如，request_id或查询参数）。在这种情况下，可以通过扩展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测试中运行，但它也可以在本地重现。