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"

按百分比

这是针对那些只想采样请求的一部分（即“采样率”）的情况

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

E2E测试

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

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

shiishiji / zipkin-instrumentation-symfony

维护者

详细信息