PHP的链路追踪（Tracing）系统：在Swoole/Hyperf中利用Context机制传递Trace ID - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

PHP 链路追踪：在 Swoole/Hyperf 中利用 Context 机制传递 Trace ID

大家好，今天我们来聊聊 PHP 链路追踪，以及如何在 Swoole/Hyperf 框架中，利用 Context 机制有效地传递 Trace ID，从而实现完整的请求链路监控。

1. 什么是链路追踪？

在微服务架构日渐流行的今天，一个请求往往会经过多个服务处理，最终才能返回给用户。如果其中一个服务出现问题，排查问题将会变得非常困难。链路追踪就是为了解决这个问题而生的。

链路追踪系统记录一个请求从开始到结束所经过的所有服务的调用关系和耗时，并将这些信息关联起来，形成一条完整的链路。通过分析这些链路数据，我们可以快速定位问题所在的服务，以及性能瓶颈。

链路追踪的核心概念包括：

Trace： 一个完整的请求链路。例如，用户发起一个购买请求，这个请求经过 API 网关、订单服务、支付服务、库存服务等，最终完成购买，这就是一个 Trace。
Span： Trace 中的一个独立的单元，通常代表一个服务的调用。例如，订单服务处理购买请求就是一个 Span。每个 Span 都有一个开始时间和结束时间，用于记录耗时。
Trace ID： 全局唯一的 ID，用于标识一个 Trace。所有属于同一个 Trace 的 Span 都拥有相同的 Trace ID。
Span ID： 在一个 Trace 中，每个 Span 都有一个唯一的 Span ID。
Parent Span ID： 指向父 Span 的 ID。通过 Parent Span ID，我们可以构建 Span 之间的父子关系，从而还原整个请求链路。

2. 为什么要使用链路追踪？

链路追踪带来的好处是显而易见的：

快速定位问题： 当请求出现问题时，通过链路追踪系统，可以快速定位到哪个服务出现了错误，大大缩短了问题排查时间。
性能分析： 可以分析每个 Span 的耗时，找出性能瓶颈，从而优化系统性能。
服务依赖分析： 可以了解服务之间的依赖关系，为服务拆分和治理提供依据。
监控告警： 可以设置告警规则，当请求链路的耗时超过阈值时，及时发出告警。

3. PHP 链路追踪面临的挑战

在传统的 PHP-FPM 模式下，由于 PHP 是无状态的，每个请求都会创建一个新的进程，因此传递 Trace ID 相对简单，可以通过全局变量、Session 等方式实现。

但是在 Swoole/Hyperf 框架中，情况变得复杂起来。Swoole/Hyperf 是基于协程的，这意味着一个进程可以处理多个请求。如果在不同的请求之间共享全局变量，就会导致数据污染。因此，传统的传递 Trace ID 的方式不再适用。

4. Swoole/Hyperf 中的 Context 机制

Hyperf 框架提供了一个强大的 Context 机制，可以用来存储和传递请求相关的数据。Context 类似于一个协程级别的全局变量，但是它与全局变量不同的是，Context 中的数据是与协程绑定的，每个协程都有自己的 Context，互不干扰。

Context 可以通过 HyperfContextContext 类进行操作。常用的方法包括：

Context::set(string $id, mixed $value): 设置 Context 中的值。
Context::get(string $id, mixed $default = null): 获取 Context 中的值。
Context::has(string $id): 判断 Context 中是否存在某个值。
Context::override(string $id, callable $callback): 在协程退出时，将Context里的数据还原。

5. 利用 Context 传递 Trace ID

下面我们来看一下如何在 Swoole/Hyperf 中利用 Context 机制传递 Trace ID。

步骤 1：生成 Trace ID

首先，我们需要生成一个全局唯一的 Trace ID。可以使用 UUID 或者其他算法来生成。

use RamseyUuidUuid;

function generateTraceId(): string
{
    return Uuid::uuid4()->toString();
}

步骤 2：创建 Middleware

创建一个 Middleware，用于在请求开始时生成 Trace ID，并将其存储到 Context 中。

<?php

declare(strict_types=1);

namespace AppMiddleware;

use PsrHttpMessageResponseInterface;
use PsrHttpMessageServerRequestInterface;
use PsrHttpServerMiddlewareInterface;
use PsrHttpServerRequestHandlerInterface;
use HyperfContextContext;

class TraceIdMiddleware implements MiddlewareInterface
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $traceId = generateTraceId();
        Context::set('trace_id', $traceId);

        // 将 Trace ID 添加到 Response Header 中，方便前端获取
        $response = $handler->handle($request);
        return $response->withHeader('X-Trace-Id', $traceId);
    }
}

步骤 3：注册 Middleware

在 config/autoload/middlewares.php 文件中注册该 Middleware。

<?php

declare(strict_types=1);

return [
    'http' => [
        AppMiddlewareTraceIdMiddleware::class,
    ],
];

步骤 4：在需要的地方获取 Trace ID

在需要 Trace ID 的地方，例如 Service 层、Repository 层，可以通过 Context::get('trace_id') 方法获取 Trace ID。

<?php

namespace AppService;

use HyperfContextContext;
use PsrLogLoggerInterface;
use HyperfDiAnnotationInject;

class UserService
{
    #[Inject]
    protected LoggerInterface $logger;

    public function getUser(int $id): array
    {
        $traceId = Context::get('trace_id');
        $this->logger->info('获取用户信息', ['id' => $id, 'trace_id' => $traceId]);

        // ...
        return ['id' => $id, 'name' => 'test', 'trace_id' => $traceId];
    }
}

步骤 5：传递 Trace ID 到下游服务

如果需要将 Trace ID 传递到下游服务，可以通过 HTTP Header 或者其他方式传递。例如，在使用 Guzzle 发起 HTTP 请求时，可以将 Trace ID 添加到 Header 中。

<?php

namespace AppService;

use GuzzleHttpClient;
use HyperfContextContext;

class OrderService
{
    public function createOrder(int $userId, array $products): array
    {
        $traceId = Context::get('trace_id');

        $client = new Client();
        $response = $client->post('http://order-service/orders', [
            'headers' => [
                'X-Trace-Id' => $traceId,
            ],
            'json' => [
                'user_id' => $userId,
                'products' => $products,
            ],
        ]);

        // ...
        return ['order_id' => 1, 'trace_id' => $traceId];
    }
}

6. 集成 OpenTelemetry 或 Jaeger

虽然我们已经实现了 Trace ID 的传递，但是这只是链路追踪的第一步。要实现完整的链路追踪，还需要将 Span 的信息收集起来，并发送到链路追踪系统中。

OpenTelemetry 和 Jaeger 是两个流行的链路追踪系统。它们都提供了 PHP SDK，可以方便地集成到 Swoole/Hyperf 项目中。

以 OpenTelemetry 为例，集成步骤如下：

安装 OpenTelemetry PHP SDK：

composer require open-telemetry/sdk
composer require open-telemetry/exporter-otlp

配置 OpenTelemetry：

创建一个配置文件 config/autoload/opentelemetry.php，配置 OpenTelemetry 的参数。

<?php

declare(strict_types=1);

use OpenTelemetrySDKTraceSamplerAlwaysOnSampler;

return [
    'enabled' => env('OPENTELEMETRY_ENABLED', false),
    'service_name' => env('OPENTELEMETRY_SERVICE_NAME', 'my-app'),
    'endpoint' => env('OPENTELEMETRY_ENDPOINT', 'http://localhost:4318'), // OTLP Endpoint
    'sampler' => AlwaysOnSampler::class, // 采样器，这里使用 AlwaysOnSampler，表示所有请求都采样
];

创建 OpenTelemetry Middleware：

创建一个 Middleware，用于在请求开始时创建 Span，并在请求结束时结束 Span。

<?php

declare(strict_types=1);

namespace AppMiddleware;

use PsrHttpMessageResponseInterface;
use PsrHttpMessageServerRequestInterface;
use PsrHttpServerMiddlewareInterface;
use PsrHttpServerRequestHandlerInterface;
use OpenTelemetryAPITraceTracerInterface;
use OpenTelemetryContextContext;
use HyperfDiAnnotationInject;

class OpenTelemetryMiddleware implements MiddlewareInterface
{
    #[Inject]
    protected TracerInterface $tracer;

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $span = $this->tracer->spanBuilder($request->getUri()->getPath())
            ->setStartTimestamp(microtime(true) * 1000000) // 设置开始时间戳
            ->startSpan();

        $context = $span->activate();

        try {
            $response = $handler->handle($request);
            $span->setStatus(OpenTelemetryAPITraceStatusCode::STATUS_OK);
            return $response;
        } catch (Throwable $e) {
            $span->setStatus(OpenTelemetryAPITraceStatusCode::STATUS_ERROR, $e->getMessage());
            throw $e;
        } finally {
            $span->end(microtime(true) * 1000000); // 设置结束时间戳
            Context::storage()->detach($context);
        }
    }
}

注册 OpenTelemetry Middleware：

在 config/autoload/middlewares.php 文件中注册该 Middleware。

<?php

declare(strict_types=1);

return [
    'http' => [
        AppMiddlewareTraceIdMiddleware::class, // 确保 TraceIdMiddleware 在 OpenTelemetryMiddleware 之前执行
        AppMiddlewareOpenTelemetryMiddleware::class,
    ],
];

配置依赖注入：
在 config/container.php 配置OpenTelemetry相关类的依赖注入。

<?php

declare(strict_types=1);

use OpenTelemetryAPITraceTracerInterface;
use OpenTelemetrySDKTraceTracerProvider;
use OpenTelemetrySDKTraceSpanProcessorSimpleSpanProcessor;
use OpenTelemetrySDKTraceExporterOtlpGrpcOtlpGrpcSpanExporter;
use PsrContainerContainerInterface;

return [
    TracerInterface::class => function (ContainerInterface $container) {
        $config = $container->get('config')->get('opentelemetry');
        if (!$config['enabled']) {
            return new OpenTelemetryAPITraceNoopTracer(); // 或者抛出异常，取决于你的需求
        }

        $exporter = new OtlpGrpcSpanExporter(endpoint: $config['endpoint']);
        $processor = new SimpleSpanProcessor($exporter);
        $tracerProvider = new TracerProvider(
            processors: [$processor],
            sampler: new $config['sampler']()
        );

        return $tracerProvider->getTracer(
            $config['service_name'],
            null,
            null,
            ['version' => '1.0.0'] // 可选，服务版本
        );
    },
];

7. 示例代码：完整的链路追踪

下面是一个完整的示例代码，演示如何在 Swoole/Hyperf 中使用 Context 机制传递 Trace ID，并集成 OpenTelemetry。

<?php

namespace AppController;

use AppServiceUserService;
use HyperfDiAnnotationInject;
use HyperfHttpServerAnnotationAutoController;
use PsrHttpMessageResponseInterface;

#[AutoController]
class IndexController
{
    #[Inject]
    protected UserService $userService;

    public function index(): ResponseInterface
    {
        $user = $this->userService->getUser(1);
        return response()->json($user);
    }
}

<?php

namespace AppService;

use HyperfContextContext;
use PsrLogLoggerInterface;
use HyperfDiAnnotationInject;
use AppServiceOrderService;

class UserService
{
    #[Inject]
    protected LoggerInterface $logger;

    #[Inject]
    protected OrderService $orderService;

    public function getUser(int $id): array
    {
        $traceId = Context::get('trace_id');
        $this->logger->info('获取用户信息', ['id' => $id, 'trace_id' => $traceId]);

        $order = $this->orderService->createOrder($id, [1, 2, 3]);

        return ['id' => $id, 'name' => 'test', 'trace_id' => $traceId, 'order' => $order];
    }
}

<?php

namespace AppService;

use GuzzleHttpClient;
use HyperfContextContext;

class OrderService
{
    public function createOrder(int $userId, array $products): array
    {
        $traceId = Context::get('trace_id');

        $client = new Client();
        $response = $client->post('http://order-service/orders', [
            'headers' => [
                'X-Trace-Id' => $traceId,
            ],
            'json' => [
                'user_id' => $userId,
                'products' => $products,
            ],
        ]);

        return ['order_id' => 1, 'trace_id' => $traceId];
    }
}

注意：

order-service 需要是一个真实存在的服务，并且能够接收 HTTP 请求，并返回响应。
需要在 order-service 中也配置 TraceIdMiddleware 和 OpenTelemetryMiddleware。

8. 链路追踪数据展示

配置完成后，启动 Swoole/Hyperf 项目，并访问 http://localhost:9501。然后，可以在 OpenTelemetry 或者 Jaeger 的 Web UI 中查看链路追踪数据。

9. 总结与展望

今天我们学习了如何在 Swoole/Hyperf 中利用 Context 机制传递 Trace ID，并集成 OpenTelemetry 链路追踪系统。通过使用 Context 机制，我们可以在协程环境下安全地传递请求相关的数据，从而实现完整的链路追踪。

未来，链路追踪技术将会更加普及，成为微服务架构中不可或缺的一部分。随着云计算和容器技术的不断发展，链路追踪系统将会更加智能化和自动化，能够帮助我们更好地监控和管理分布式系统。

Context机制是关键，OpenTelemetry集成链路追踪

Context机制在Swoole/Hyperf中解决了协程环境下的数据传递问题，是实现链路追踪的基础。而集成OpenTelemetry等成熟的链路追踪系统，可以帮助我们收集、分析和可视化链路数据，从而更好地监控和管理我们的应用。

PHP 链路追踪：在 Swoole/Hyperf 中利用 Context 机制传递 Trace ID

发表回复 取消回复

发表回复取消回复