tencent cloud

文档反馈

通过 OpenTelemetry-PHP 接入 PHP 应用(推荐)

最后更新时间:2024-11-01 17:52:58
    说明:
    OpenTelemetry 是工具、API 和 SDK 的集合,用来检测、生成、收集和导出遥测数据(指标、日志和跟踪),帮助用户分析软件的性能和行为。关于 OpenTelemetry 的更多信息请参考 OpenTelemetry 官方网站
    OpenTelemetry 社区活跃,技术更迭迅速,广泛兼容主流编程语言、组件与框架,为云原生微服务以及容器架构的链路追踪能力广受欢迎。
    本文将通过相关操作介绍如何通过社区的 OpenTelemetry-PHP 方案接入 PHP 应用。
    OpenTelemetry-PHP 方案对于 PHP 系的常用依赖库和框架,例如 Slim 等,提供了自动埋点,在不需要修改代码的情况下就能实现链路信息的上报。其他支持自动埋点的依赖库和框架请参考 OpenTelemetry 社区提供的 完整列表

    前提条件

    安装如下工具:
    PECL
    composer
    并确保 shell 中可以运行以下命令:
    php -v
    composer -v

    自动接入

    PHP 8.0+
    目前自动埋点支持的框架列表详情请参见 OpenTelemetry 官方文档

    手动接入

    PHP 7.4+

    Demo 应用

    示例代码 index.php 是一个 HTTP Server 使用 PDO 连接 MySQL 数据库数据库操作,对应的 MySQL 务请自行搭建,或直接购买云产品。
    1. 初始化应用
    mkdir <project-name> && cd <project-name>
    
    composer init \\
    --no-interaction \\
    --stability beta \\
    --require slim/slim:"^4" \\
    --require slim/psr7:"^1"
    composer update
    2. 编写业务代码
    在<project-name>目录下创建一个index.php文件,添加如下内容。
    以下内容将使用一个 HTTP Server 接口模拟使用 PDO 连接 MySQL 进行一次搜索操作。
    <?php use Psr\\Http\\Message\\ResponseInterface as Response; use Psr\\Http\\Message\\ServerRequestInterface as Request; use Slim\\Factory\\AppFactory; require __DIR__ . '/vendor/autoload.php'; $app = AppFactory::create(); $app->get('/getID', function (Request $request, Response $response) { $dbms = 'mysql'; // 数据库类型 $host = 'localhost'; // 数据库主机名 $dbName = 'Mydb'; // 使用的数据库 $user = 'root'; // 数据库连接用户名 $pass = ''; // 对应的密码 $dsn = "$dbms:host=$host;dbname=$dbName"; try { $dbh = new PDO($dsn, $user, $pass); // 初始化一个PDO对象 echo "连接成功<br/>"; foreach ($dbh->query('SELECT id from userInfo') as $row) { $response->getBody()->write($row[0] . "<br/>"); } $dbh = null; } catch (PDOException $e) { die ("Error!: " . $e->getMessage() . "<br/>"); } return $response; }); $app->run();

    前置步骤:获取接入点和 Token

    1. 登录 腾讯云可观测平台 控制台。
    2. 在左侧菜单栏中选择应用性能监控 > 应用监控,单击应用列表 > 接入应用
    3. 在右侧弹出的数据接入抽屉框中,单击 PHP 语言。
    4. 接入 PHP 应用页面,选择您所要接入的地域以及业务系统
    5. 选择接入协议类型OpenTelemetry
    6. 上报方式选择您所想要的上报方式,获取您的接入点Token
    说明:
    内网上报:使用此上报方式,您的服务需运行在腾讯云 VPC。通过 VPC 直接联通,在避免外网通信的安全风险同时,可以节省上报流量开销。
    外网上报:当您的服务部署在本地或非腾讯云 VPC 内,可以通过此方式上报数据。请注意外网通信存在安全风险,同时也会造成一定上报流量费用。

    自动接入方案 (推荐)

    步骤1:构建 OpenTelemetry PHP Extension

    说明:
    如果已经构建过 OpenTelemetry PHP extension,可跳过当前步骤。
    1. 下载构建 OpenTelemetry PHP extension 所需要的工具:
    macOS
    brew install gcc make autoconf
    Linux(apt)
    sudo apt-get install gcc make autoconf
    2. 使用 PECL 构建 OpenTelemetry PHP 扩展:
    pecl install opentelemetry
    注意:
    构建成功时输出内容的最后几行如下(路径可能不完全一致):
    Build process completed successfully
    Installing '/opt/homebrew/Cellar/php/8.2.8/pecl/2020829/opentelemetry.so'
    install ok: channel://pecl.php.net/opentelemetry-1.0.3
    Extension opentelemetry enabled in php.ini
    3. 启用 OpenTelemetry PHP 扩展。
    说明:
    如果上一步输出了Extension opentelemetry enabled in php.ini,表明已经启用,请跳过当前步骤。
    php.ini文件中添加如下内容:
    [opentelemetry]
    extension=opentelemetry.so
    php.ini文件可能存在的位置:
    OS
    PATH
    Linux
    /etc/php.ini /usr/bin/php5/bin/php.ini /etc/php/php.ini /etc/php5/apache2/php.ini
    Mac OSX
    /private/etc/php.ini
    Windows (with XAMPP installed)
    C:/xampp/php/php.ini
    4. 验证是否构建并启用成功。
    方法一:
    php -m | grep opentelemetry
    预期输出:
    opentelemetry
    方法二:
    php --ri opentelemetry
    预期输出:
    opentelemetry
    opentelemetry support => enabled
    extension version => 1.0.3
    5. 为应用添加 OpenTelemetry PHP 自动埋点需要的额外依赖。
    pecl install grpc # 这一步构建时间较长
    composer require \\ open-telemetry/sdk \\ open-telemetry/exporter-otlp \\ open-telemetry/transport-grpc \\
    php-http/guzzle7-adapter \\
    open-telemetry/opentelemetry-auto-slim \\
    open-telemetry/opentelemetry-auto-pdo
    open-telemetry/sdk:OpenTelemetry PHP SDK。
    open-telemetry/exporter-otlp:OpenTelemetry PHP OTLP 协议数据上报所需的依赖。
    open-telemetry/opentelemetry-auto-slim:OpenTelemetry PHP 针对 Slim 框架实现的自动埋点包。
    open-telemetry/opentelemetry-auto-pdo:OpenTelemetry PHP 针对 PHP DataObject 实现的自动埋点包。
    说明:
    这里导入 open-telemetry/opentelemetry-auto-slimopen-telemetry/opentelemetry-auto-pdo 包是因为示例 demo 中使用了 PDO 和 Slim 框架,可以根据具体业务进行调整。如果业务中组件需要 OpenTelemetry 自动埋点,需要在项目中导入对应的自动埋点包,自动埋点包导入方式具体详情请参见 OpenTelemetry 官方文档

    步骤2:运行应用

    1. 执行以下命令:
    env OTEL_PHP_AUTOLOAD_ENABLED=true \\
    OTEL_TRACES_EXPORTER=otlp \\
    OTEL_METRICS_EXPORTER=none \\
    OTEL_LOGS_EXPORTER=none \\
    OTEL_EXPORTER_OTLP_PROTOCOL=grpc \\
    OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint> \\ # 此处替换成步骤1中获得的接入点
    OTEL_RESOURCE_ATTRIBUTES="service.name=<service-name>,token=<token>" \\ # 此处<service-name>改为自定义服务名,<token>替换成步骤1中获得的token
    OTEL_PROPAGATORS=baggage,tracecontext \\
    php -S localhost:8080
    2. 在浏览器中访问以下链接:
    http://localhost:8080/getID
    每次进入该页面,OpenTelemetry 都会自动创建 Trace,并将链路数据上报至 APM。

    接入验证

    启动 PHP 应用后,通过8080端口访问对应的接口,例如 https://localhost:8080/getID。在有正常流量的情况下,应用性能监控 > 应用监控 > 应用列表 中将展示接入的应用,应用性能监控 > 应用监控 > 应用详情 > 实例监控中将展示接入的应用实例。由于可观测数据的处理存在一定延时,如果接入后在控制台没有查询到应用或实例,请等待30秒左右。

    自定义埋点(可选)

    当自动埋点不满足您的场景或者需要增加业务层埋点时,您可参照下述内容,使用 OpenTelemetry PHP SDK 添加自定义埋点。本文仅展示最基本的自定义埋点方式,OpenTelemetry 社区提供了更多灵活的自定义埋点方式,具体使用方法可参考 OpenTelemetry 社区提供的 PHP 自定义埋点文档
    <?php use OpenTelemetry\\API\\Globals; // 必须的包 require __DIR__ . '/vendor/autoload.php'; function wait(): void { // 通过Globals包获取当前已经配置的providers
    $tracerProvider = Globals::tracerProvider(); $tracer = $tracerProvider->getTracer( 'instrumentation-scope-name', //name (required) 'instrumentation-scope-version', //version 'http://example.com/my-schema', //schema url ['foo' => 'bar'] //attributes );
    // 自定义埋点 $span = $tracer->spanBuilder("wait")->startSpan();
    // 业务代码 sleep(5)
    // 自定义埋点结束
    $span->end(); } wait();

    手动接入方案

    若 PHP 应用版本不能满足8.0+,但能满足7.4+,可以选择手动埋点上报。本文仅展示最基本的手动埋点方式,OpenTelemetry 社区提供了更多灵活的手动埋点方式,具体使用方法可参考 OpenTelemetry 社区提供的 PHP 手动接入文档

    导入 OpenTelemetry PHP SDK 以及 OpenTelemetry gRPC Explorer 所需依赖

    1. 下载 PHP HTTP 客户端库,用于链路数据上报。
    composer require guzzlehttp/guzzle
    2. 下载 OpenTelemetry PHP SDK。
    composer require \\
    open-telemetry/sdk \\
    open-telemetry/exporter-otlp
    3. 下载使用 gRPC 上报数据时所需依赖。
    pecl install grpc # 如果之前已经下载过grpc,可以跳过这一步
    composer require open-telemetry/transport-grpc

    编写 OpenTelemetry 初始化工具类

    index.php文件所在目录中创建opentelemetry_util.php文件。并在文件中添加如下代码:
    <?php
    // 包含设置应用名、Trace导出方式、Trace上报接入点,并创建全局TraceProvide
    
    use OpenTelemetry\\API\\Globals;
    use OpenTelemetry\\API\\Trace\\Propagation\\TraceContextPropagator;
    use OpenTelemetry\\Contrib\\Otlp\\SpanExporter;
    use OpenTelemetry\\SDK\\Common\\Attribute\\Attributes;
    use OpenTelemetry\\SDK\\Common\\Export\\Stream\\StreamTransportFactory;
    use OpenTelemetry\\SDK\\Resource\\ResourceInfo;
    use OpenTelemetry\\SDK\\Resource\\ResourceInfoFactory;
    use OpenTelemetry\\SDK\\Sdk;
    use OpenTelemetry\\SDK\\Trace\\Sampler\\AlwaysOnSampler;
    use OpenTelemetry\\SDK\\Trace\\Sampler\\ParentBased;
    use OpenTelemetry\\SDK\\Trace\\SpanProcessor\\SimpleSpanProcessor;
    use OpenTelemetry\\SDK\\Trace\\SpanProcessor\\BatchSpanProcessorBuilder;
    use OpenTelemetry\\SDK\\Trace\\TracerProvider;
    use OpenTelemetry\\SemConv\\ResourceAttributes;
    use OpenTelemetry\\Contrib\\Grpc\\GrpcTransportFactory;
    use OpenTelemetry\\Contrib\\Otlp\\OtlpUtil;
    use OpenTelemetry\\API\\Signals;
    
    // OpenTelemetry 初始化配置(需要在PHP应用初始化时就进行OpenTelemetry初始化配置)
    function initOpenTelemetry()
    {
    // 1. 设置 OpenTelemetry 资源信息
    $resource = ResourceInfoFactory::emptyResource()->merge(ResourceInfo::create(Attributes::create([
    ResourceAttributes::SERVICE_NAME => '<your-service-name>', // 应用名,必填,如php-opentelemetry-demo
    ResourceAttributes::HOST_NAME => '<your-host-name>' // 主机名,选填
    'token' => '<your-token>' // 替换成步骤1中获得的 Token
    ])));
    // 2. 创建将 Span 输出到控制台的 SpanExplorer
    // $spanExporter = new SpanExporter(
    // (new StreamTransportFactory())->create('php://stdout', 'application/json')
    // );
    // 2. 创建通过 gRPC 上报 Span 的 SpanExplorer
    $transport = (new GrpcTransportFactory())->create('<grpc-endpoint>' . OtlpUtil::method(Signals::TRACE)); # 替换成步骤1中获得的接入点信息
    $spanExporter = new SpanExporter($transport);
    // 3. 创建全局的 TraceProvider,用于创建 tracer
    $tracerProvider = TracerProvider::builder()
    ->addSpanProcessor(
    (new BatchSpanProcessorBuilder($spanExporter))->build()
    )
    ->setResource($resource)
    ->setSampler(new ParentBased(new AlwaysOnSampler()))
    ->build();
    Sdk::builder()
    ->setTracerProvider($tracerProvider)
    ->setPropagator(TraceContextPropagator::getInstance())
    ->setAutoShutdown(true) // PHP 程序退出后自动关闭 tracerProvider,保证链路数据都被上报
    ->buildAndRegisterGlobal(); // 将 tracerProvider 添加到全局
    
    }
    ?>

    修改应用代码,使用 OpenTelemetry API 创建 Span

    1. index.php文件中导入所需包:
    <?php
    
    use OpenTelemetry\\API\\Globals; use OpenTelemetry\\API\\Trace\\StatusCode; use OpenTelemetry\\API\\Trace\\SpanKind; use OpenTelemetry\\SDK\\Common\\Attribute\\Attributes; use OpenTelemetry\\SDK\\Trace\\TracerProvider; use Psr\\Http\\Message\\ResponseInterface as Response; use Psr\\Http\\Message\\ServerRequestInterface as Request; use Slim\\Factory\\AppFactory;
    
    require __DIR__ . '/opentelemetry_util.php';
    2. 调用initOpenTelemetry方法完成初始化,需要在 PHP 应用初始化时就进行 OpenTelemetry 初始化配置:
    // OpenTelemetry 初始化,包含设置应用名、Trace导出方式、Trace上报接入点,并创建全局TraceProvider
    initOpenTelemetry();
    3. rolldice接口中创建 Span。
    /**
    * 1. 接口功能:模拟扔骰子,返回一个1-6之间的随机正整数
    * 并演示如何创建Span、设置属性、事件、带有属性的事件
    */
    $app->get('/rolldice', function (Request $request, Response $response) {
    // 获取 tracer
    $tracer = \\OpenTelemetry\\API\\Globals::tracerProvider()->getTracer('my-tracer');
    // 创建 Span; 设置span kind,不设置默认为KIND_INTERNAL
    $span = $tracer->spanBuilder("/rolldice")->setSpanKind(SpanKind::KIND_SERVER)->startSpan();
    // 为 Span 设置属性
    $span->setAttribute("http.method", "GET");
    // 为 Span 设置事件
    $span->addEvent("Init");
    // 设置带有属性的事件
    $eventAttributes = Attributes::create([
    "key1" => "value",
    "key2" => 3.14159,
    ]);
    
    // 业务代码
    $result = random_int(1,6);
    $response->getBody()->write(strval($result));
    
    $span->addEvent("End");
    // 销毁 Span
    $span->end();
    
    return $response;
    });
    4. 创建嵌套 Span。
    新建一个rolltwodices接口,模拟扔两个骰子,返回两个1-6之间的随机正整数。以下代码演示如何创建嵌套的 Span:
    $app->get('/rolltwodices', function (Request $request, Response $response) {
    // 获取 tracer
    $tracer = \\OpenTelemetry\\API\\Globals::tracerProvider()->getTracer('my-tracer');
    // 创建 Span
    $parentSpan = $tracer->spanBuilder("/rolltwodices/parent")->setSpanKind(SpanKind::KIND_SERVER)->startSpan();
    $scope = $parentSpan->activate();
    
    $value1 = random_int(1,6);
    
    $childSpan = $tracer->spanBuilder("/rolltwodices/parent/child")->startSpan();
    // 业务代码
    $value2 = random_int(1,6);
    $result = "dice1: " . $value1 . ", dice2: " . $value2;
    
    // 销毁 Span
    $childSpan->end();
    $parentSpan->end();
    $scope->detach();
    
    $response->getBody()->write(strval($result));
    return $response;
    });
    5. 使用 Span 记录代码中发生的异常。
    新建error接口,模拟接口发生异常。以下代码演示如何在代码发生异常时使用 Span 记录状态:
    $app->get('/error', function (Request $request, Response $response) {
    // 获取 tracer
    $tracer = \\OpenTelemetry\\API\\Globals::tracerProvider()->getTracer('my-tracer');
    // 创建 Span
    $span3 = $tracer->spanBuilder("/error")->setSpanKind(SpanKind::KIND_SERVER)->startSpan();
    try {
    // 模拟代码发生异常
    throw new \\Exception('exception!');
    } catch (\\Throwable $t) {
    // 设置Span状态为error
    $span3->setStatus(\\OpenTelemetry\\API\\Trace\\StatusCode::STATUS_ERROR, "expcetion in span3!");
    // 记录异常栈轨迹
    $span3->recordException($t, ['exception.escaped' => true]);
    } finally {
    $span3->end();
    $response->getBody()->write("error");
    return $response;
    }
    });

    运行应用

    1. 执行以下命令:
    php -S localhost:8080
    2. 在浏览器中访问以下链接:
    http://localhost:8080/rolldice
    http://localhost:8080/rolltwodices
    http://localhost:8080/error
    每次访问页面,OpenTelemetry 会创建链路数据,并将链路数据上报至 APM。

    接入验证

    启动 PHP 应用后,通过8080端口访问对应的接口,例如 https://localhost:8080/getID。在有正常流量的情况下,应用性能监控 > 应用监控 > 应用列表 中将展示接入的应用,应用性能监控 > 应用监控 > 应用详情 > 实例监控中将展示接入的应用实例。由于可观测数据的处理存在一定延时,如果接入后在控制台没有查询到应用或实例,请等待30秒左右。
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持