自动仪表化

使用PHP进行自动仪表化至少需要PHP 8.0，以及OpenTelemetry PHP 扩展。该扩展可以注册观察者函数（作为PHP代码）到类和方法，并在观察到的方法运行之前和之后执行这些函数。

重要

仅安装OpenTelemetry扩展本身不会生成跟踪。您还必须安装SDK和一个或多个仪表化包以供您使用的框架和库，或者自己编写。

您还必须使用composer自动加载，因为这是所有自动仪表化包用来注册自身的机制。

示例

<?php

use OpenTelemetry\API\Common\Instrumentation\CachedInstrumentation;
use OpenTelemetry\API\Trace\Span;
use OpenTelemetry\API\Trace\StatusCode;
use OpenTelemetry\Context\Context;

require 'vendor/autoload.php';

class DemoClass
{
    public function run(): void
    {
        echo 'Hello, world';
    }
}

OpenTelemetry\Instrumentation\hook(
    class: DemoClass::class,
    function: 'run',
    pre: static function (DemoClass $demo, array $params, string $class, string $function, ?string $filename, ?int $lineno) {
        static $instrumentation;
        $instrumentation ??= new CachedInstrumentation('example');
        $span = $instrumentation->tracer()->spanBuilder('democlass-run')->startSpan();
        Context::storage()->attach($span->storeInContext(Context::getCurrent()));
    },
    post: static function (DemoClass $demo, array $params, $returnValue, ?Throwable $exception) {
        $scope = Context::storage()->scope();
        $scope->detach();
        $span = Span::fromContext($scope->context());
        if ($exception) {
            $span->recordException($exception);
            $span->setStatus(StatusCode::STATUS_ERROR);
        }
        $span->end();
    }
);

$demo = new DemoClass();
$demo->run();

在这里，我们提供了 pre 和 post 函数，它们在 DemoClass::run 方法之前和之后执行。 pre 函数开始并激活一个 span，post 函数结束这个 span。如果 DemoClass::run() 抛出异常，post 函数会记录它，但不会影响异常传递。

安装

该扩展可以通过pecl、pickle或php-extension-installer（仅限于docker）进行安装。某些Linux发行版的包管理器也提供了已打包的扩展版本。

Linux 包

以下是提供 RPM 和 APK 包的来源：

Remi repository - RPM
Alpine Linux - APK（目前在_testing_分支中）

#此示例适用于CentOS 7，可以通过启用 remi-<version> 更改 PHP 版本，例如"yum config-manager --enable remi-php83"
yum update -y
yum install -y epel-release yum-utils
yum install -y http://rpms.remirepo.net/enterprise/remi-release-7.rpm
yum-config-manager --enable remi-php81
yum install -y php php-pecl-opentelemetry

php --ri opentelemetry

#在撰写本文时，PHP 8.1 是默认的 PHP 版本。如果默认版本发生更改，您可能需要更改 "php81"。
#您也可以使用 "apk add php<version>"，例如 "apk add php83" 选择一个 PHP 版本。
echo "@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing" >> /etc/apk/repositories
apk add php php81-pecl-opentelemetry@testing
php --ri opentelemetry

PECL

设置开发环境。从源代码安装需要适当的开发环境和一些依赖项：
```
sudo apt-get install gcc make autoconf
```
```
brew install gcc make autoconf
```
构建/安装扩展。在设置好环境后，您可以安装扩展：
```
pecl install opentelemetry
```
```
php pickle.phar install opentelemetry
```
```
install-php-extensions opentelemetry
```

将扩展添加到您的 php.ini 文件中：

[opentelemetry]
extension=opentelemetry.so

验证扩展是否已安装和启用：
```
php -m | grep opentelemetry
```

无代码配置自动仪表化

当与OpenTelemetry SDK一起使用时，您可以使用环境变量或php.ini来配置自动仪表化：

OTEL_PHP_AUTOLOAD_ENABLED=true \
OTEL_SERVICE_NAME=your-service-name \
OTEL_TRACES_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317 \
OTEL_PROPAGATORS=baggage,tracecontext \
php myapp.php

手动设置自动仪表化

<?php
OpenTelemetry\API\Common\Instrumentation\Globals::registerInitializer(function (Configurator $configurator) {
    $propagator = TraceContextPropagator::getInstance();
    $spanProcessor = new BatchSpanProcessor(/*params*/);
    $tracerProvider = (new TracerProviderBuilder())
        ->addSpanProcessor($spanProcessor)
        ->setSampler(new ParentBased(new AlwaysOnSampler()))
        ->build();

    ShutdownHandler::register([$tracerProvider, 'shutdown']);

    return $configurator
        ->withTracerProvider($tracerProvider)
        ->withPropagator($propagator);
});

//instrumentation libraries can access the configured providers (or a no-op implementation) via `Globals`
$tracer = Globals::tracerProvider()->getTracer('example');
//or, via CachedInstrumentation which uses `Globals` internally
$instrumentation = new CachedInstrumentation('example');
$tracerProvider = $instrumentation->tracer();

支持的库和框架

自动仪表化附带了许多用于常用PHP库的仪表化库。完整列表请参见在packagist上的仪表化库。

后续步骤

在为您的应用程序或服务配置自动仪表化后，您可能希望添加手动仪表化以收集自定义遥测数据。

最后修改 December 13, 2023: improve glossary translation (46f8201b)