怎样在Docker中配置OpenTelemetry运行Hyperf-php教程-PHP中文网

Hyperf 3.0 在 Docker 中集成 OpenTelemetry 的核心是使用 opentelemetry-php SDK + OTLP 协议替代 jaeger-client-php，需在主协程启动前初始化 TracerProvider、HTTP 中间件正确提取 traceparent、DB/Redis 调用显式继承 Span 上下文，并通过 OpenTelemetry Collector 统一导出至 Jaeger 等后端。

怎样在docker中配置opentelemetry运行hyperf

在 Docker 中为 Hyperf 应用配置 OpenTelemetry，核心是让 PHP 应用（通过 opentelemetry-php SDK）采集追踪数据，并将数据导出到兼容 OTLP 的后端（如 Jaeger、Zipkin 或 OpenTelemetry Collector）。Hyperf 本身不内置 OpenTelemetry 支持，需手动集成 SDK 并借助扩展（如 opentelemetry-ext 或自定义中间件/装饰器）实现自动 instrumentation。

1. 准备基础环境：Docker + Hyperf + OpenTelemetry PHP SDK

确保使用支持 OpenTelemetry 的 PHP 扩展或纯 PHP SDK。推荐方式是使用官方维护的 opentelemetry-php（v1.x），它支持 OTLP/gRPC 和 OTLP/HTTP 导出，且兼容 Swoole（Hyperf 底层）。

在 Dockerfile 中安装必要依赖：

# 基于 Hyperf 官方镜像（如 hyperf/hyperf:8.2-alpine-v4）
FROM hyperf/hyperf:8.2-alpine-v4
<h1>安装 gRPC 扩展（用于 OTLP/gRPC，可选；若用 HTTP 则无需）</h1><p>RUN apk add --no-cache grpc-dev && \
pecl install grpc && \
docker-php-ext-enable grpc</p><h1>安装 OpenTelemetry PHP SDK（通过 Composer）</h1><p>WORKDIR /var/www
COPY composer.* ./
RUN composer install --no-dev --optimize-autoloader -n</p><h1>复制应用代码</h1><p>COPY . .
</p>

2. 配置 OpenTelemetry SDK（PHP 端）

在 Hyperf 启动流程中初始化全局 TracerProvider。推荐在 config/autoload/opentelemetry.php 中定义配置，并通过 Di 或 Bootstrap 注入。

关键步骤：

创建 TracerProvider，使用 OtlpExporter（gRPC 或 HTTP）
设置采样策略（如 AlwaysOnSampler 或 ParentBased）
注册全局 Tracer 实例供中间件或服务调用
可选：启用自动 HTTP 请求、MySQL、Redis 等插件（需额外安装 opentelemetry-instrumentation-* 包）

示例初始化代码（放在 app/Bootstrap/OpenTelemetryBootstrap.php）：

use OpenTelemetry\API\Globals;
use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\SDK\Trace\Export\BatchSpanProcessor;
use OpenTelemetry\Exporter\Otlp\OtlpExporter;
use OpenTelemetry\SDK\Trace\Sampling\AlwaysOnSampler;
<p>$exporter = new OtlpExporter(
'<a href="https://www.php.cn/link/edb518e0388521905d2302d973250478">https://www.php.cn/link/edb518e0388521905d2302d973250478</a>', // 使用 HTTP/JSON 方式（更易调试）
null,
['Content-Type' => 'application/json']
);
$processor = new BatchSpanProcessor($exporter);
$tracerProvider = new TracerProvider(new AlwaysOnSampler(), $processor);</p><p>Globals::setTracerProvider($tracerProvider);
</p>

并在 bin/hyperf.php 启动前加载该 Bootstrap。

Docker Container Cleaner

CLI工具，用于清理已停止的Docker容器、未使用的镜像、卷和网络，释放磁盘空间。

下载

3. 在 Hyperf 中注入追踪逻辑

Hyperf 默认不自动埋点，需手动或半自动添加 Span。常用方式：

HTTP Server 中间件：在请求入口创建 root span，注入 trace context 到 ServerRequestInterface，并结束 span 在响应后
装饰器/注解：对 Controller 方法或 Service 方法加注解，用 AOP 自动包裹 span
数据库/Redis 客户端增强：利用 Hyperf 的 Pool 或 Proxy 机制，在执行 SQL/命令前后记录 span

简单中间件示例（app/Middleware/TracingMiddleware.php）：

use OpenTelemetry\API\Trace\Span;
use OpenTelemetry\API\Trace\Tracer;
use OpenTelemetry\API\Globals;
<p>class TracingMiddleware implements MiddlewareInterface
{
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
$tracer = Globals::getTracerProvider()->getTracer('hyperf-app');
$span = $tracer->spanBuilder($request->getMethod() . ' ' . $request->getUri()->getPath())
->setParent(Context::getCurrent())
->startSpan();
Context::storage()->set(Span::class, $span);</p><pre class="brush:php;toolbar:false;">    try {
        $response = $handler->handle($request);
        $span->setStatus(StatusCode::STATUS_OK);
        return $response;
    } catch (\Throwable $e) {
        $span->setStatus(StatusCode::STATUS_ERROR, $e->getMessage());
        throw $e;
    } finally {
        $span->end();
    }
}

}

4. Docker Compose 编排 OpenTelemetry Collector 和后端

不建议 PHP 直连 Jaeger/Zipkin，而是通过 OpenTelemetry Collector 统一接收、处理、转发。它支持多协议、采样、过滤、打标等能力。

示例 docker-compose.yml：

version: '3.8'
services:
  app:
    build: .
    environment:
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
    depends_on:
      - otel-collector
<p>otel-collector:
image: otel/opentelemetry-collector:0.115.0
command: ["--config=/etc/otel-collector-config.yaml"]
volumes:</p>

./otel-collector-config.yaml:/etc/otel-collector-config.yaml ports:
"4317:4317" # OTLP/gRPC
"4318:4318" # OTLP/HTTP
"8888:8888" # Prometheus metrics

jaeger: image: jaegertracing/all-in-one:1.55 ports:

"16686:16686" # UI
"14250:14250" # gRPC for collector

配套 otel-collector-config.yaml 示例（将 traces 转发至 Jaeger）：

receivers:
otlp:
protocols:
http:
grpc:
<p>processors:
batch:</p><p>exporters:
jaeger:
endpoint: jaeger:14250
tls:
insecure: true</p><p>service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [jaeger]
</p>

配置完成后，启动 docker-compose up，访问 http://localhost:16686 即可查看 Hyperf 请求链路。