razorpay/opencensus-php

opencensus-php Docker镜像文档

概述

opencensus-php是基于官方PHP镜像构建的Docker镜像，预集成了OpenCensus PHP库。OpenCensus是一个开源分布式追踪框架，旨在帮助开发者收集、分析和导出分布式系统中的性能数据。该镜像简化了PHP应用集成分布式追踪的流程，无需手动安装依赖，可直接用于生产或开发环境，支持将追踪数据导出至主流后端系统（如Jaeger、Zipkin、Stackdriver等）。

核心功能与特性

主要功能

• 分布式追踪基础：支持创建追踪跨度（Span）、传播上下文（Context）、记录时间戳和事件，实现跨服务请求链路追踪。
• 多后端数据导出：内置导出器支持主流追踪系统，包括Jaeger、Zipkin、Stackdriver Trace、AWS X-Ray等。
• 灵活采样策略：提供多种采样算法（如全量采样、固定速率采样、概率采样），可根据需求控制追踪数据量。
• 上下文管理：自动处理PHP进程内及跨服务的上下文传播，支持HTTP、gRPC等协议。

特性

• 轻量级集成：对PHP应用性能影响小，资源占用低。
• 框架兼容性：兼容主流PHP框架（如Laravel、Symfony、Lumen）及原生PHP应用。
• 可配置化：通过环境变量或配置文件灵活调整导出目标、采样率、服务名称等参数。
• 标准化数据格式：遵循OpenTelemetry（原OpenCensus）数据模型，确保与上下游系统兼容性。

使用场景

适用场景

• 微服务架构中的PHP服务：追踪跨服务调用链路，定位服务间性能瓶颈。
• 分布式系统调试：通过追踪数据还原请求路径，诊断跨服务异常（如超时、错误）。
• 性能监控：收集服务响应时间、调用频率等指标，分析系统性能趋势。
• 多团队协作开发：统一追踪标准，便于不同团队间的服务依赖可视化。

使用方法

基本使用示例

拉取镜像

从Docker Hub拉取最新版本镜像：

bash
docker pull opencensus/php:latest

启动容器

以Jaeger为导出后端的基本示例：

bash
docker run -d \
  --name opencensus-php-example \
  -e OPENCENSUS_TRACER_EXPORTER=jaeger \
  -e OPENCENSUS_EXPORTER_JAEGER_AGENT_HOST=jaeger-agent \
  -e OPENCENSUS_EXPORTER_JAEGER_SERVICE_NAME=php-service \
  -e OPENCENSUS_SAMPLER=always_on \
  -v $(pwd)/app:/app \
  -p 8080:80 \
  opencensus/php:latest \
  php -S 0.0.0.0:80 /app/index.php

Docker Compose配置示例

配合Jaeger后端的Docker Compose示例（docker-compose.yml）：

yaml
version: '3'
services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"  # Jaeger UI
      - "6831:6831/udp" # Jaeger Agent (Thrift compact)
    environment:
      - COLLECTOR_ZIPKIN_HOST_PORT=:9411

  php-app:
    image: opencensus/php:latest
    depends_on:
      - jaeger
    environment:
      - OPENCENSUS_TRACER_EXPORTER=jaeger
      - OPENCENSUS_EXPORTER_JAEGER_AGENT_HOST=jaeger
      - OPENCENSUS_EXPORTER_JAEGER_AGENT_PORT=6831
      - OPENCENSUS_EXPORTER_JAEGER_SERVICE_NAME=php-app
      - OPENCENSUS_SAMPLER=probability
      - OPENCENSUS_SAMPLER_RATE=0.5  # 50%采样率
    volumes:
      - ./app:/app
    ports:
      - "8080:80"
    command: php -S 0.0.0.0:80 /app/index.php

启动服务：

bash
docker-compose up -d

PHP应用集成示例

在PHP应用中使用OpenCensus追踪请求（app/index.php）：

php
<?php
require_once __DIR__ . '/vendor/autoload.php';

// 初始化追踪器（镜像已自动配置，无需手动初始化）
$tracer = Opencensus\Trace\Tracer::instance();

// 创建根跨度
$span = $tracer->startSpan('php-app-root');
$tracer->inScope($span);

try {
    // 模拟业务逻辑
    usleep(100000); // 100ms延迟
    
    // 创建子跨度（如数据库调用）
    $dbSpan = $tracer->startSpan('database-query');
    $tracer->inScope($dbSpan);
    usleep(50000); // 模拟数据库查询耗时
    $dbSpan->end();
    
} finally {
    $span->end(); // 确保根跨度结束
}

echo "Hello, OpenCensus!\n";
?>

配置参数

环境变量配置

通过环境变量调整镜像行为，常用参数如下：

自定义配置文件

如需更复杂配置，可挂载自定义opencensus.yaml配置文件至容器/etc/opencensus/目录：

bash
docker run -v $(pwd)/opencensus.yaml:/etc/opencensus/opencensus.yaml ...

配置文件格式参考OpenCensus PHP官方文档。

注意事项

• 性能影响：启用追踪会产生一定性能开销（主要为网络IO和CPU），建议通过采样策略控制数据量。
• 版本兼容性：镜像基于PHP 7.2+构建，支持PHP 7.2~8.2版本，使用时需匹配应用的PHP版本。
• 依赖要求：若使用特定导出器（如Stackdriver），需确保网络可访问对应后端服务。