Інструментування PHP без коду

Вимоги

Автоматичне інструментування з PHP вимагає:

• PHP 8.0 або вище
• Розширення OpenTelemetry PHP
• Автозавантаження Composer
• OpenTelemetry SDK
• Одна або більше бібліотек інструментування
• Конфігурація

Встановлення розширення OpenTelemetry

Розширення можна встановити через pecl, pickle або php-extension-installer (специфічно для docker). Також є пакетовані версії розширення, доступні для деяких менеджерів пакетів Linux.

Пакунки Linux

Пакунки RPM та APK надаються наступними джерелами:

• Репозиторій Remi - RPM
• Alpine Linux - APK (наразі в testing гілці)

• RPM
• APK

#цей приклад для CentOS 7. Версію PHP можна змінити
#включивши remi-<version>, наприклад "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", якщо стандарт зміниться. Ви також можете вибрати версію PHP
#з "apk add php<version>", наприклад "apk add php83".
echo "@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing" >> /etc/apk/repositories
apk add php php81-pecl-opentelemetry@testing
php --ri opentelemetry

PECL

1. Налаштуйте середовище розробки. Встановлення з вихідного коду вимагає належного середовища розробки та деяких залежностей:

   • Linux (apt)
   • macOS (homebrew)

   sudo apt-get install gcc make autoconf
   

   brew install gcc make autoconf
   

2. Збірка/встановлення розширення. Після налаштування середовища ви можете встановити розширення:

   • pecl
   • pickle
   • php-extension-installer (docker)

   pecl install opentelemetry
   

   php pickle.phar install opentelemetry
   

   install-php-extensions opentelemetry
   

3. Додайте розширення до вашого файлу php.ini:

   [opentelemetry]
   extension=opentelemetry.so
   

4. Перевірте, що розширення встановлено та увімкнено:

   php -m | grep opentelemetry
   

Встановлення SDK та бібліотек інструментування

Після встановлення розширення, встановіть OpenTelemetry SDK та одну або більше бібліотек інструментування.

Автоматичне інструментування доступне для багатьох популярних бібліотек PHP. Для повного списку дивіться бібліотеки інструментування на packagist.

Припустимо, що ваш додаток використовує Slim Framework та PSR-18 HTTP клієнт. Тоді ви встановите SDK та відповідні пакети автоінструментування для них:

composer require \
    open-telemetry/sdk \
    open-telemetry/opentelemetry-auto-slim \
    open-telemetry/opentelemetry-auto-psr18

Конфігурація

При використанні разом з 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.ini

Додайте наступне до php.ini, або іншого ini файлу, який буде оброблений PHP:

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

Запуск вашого застосунку

Після того, як все вищезазначене встановлено та налаштовано, запустіть ваш застосунок як зазвичай.

Трасування, яке ви побачите, експортоване до OpenTelemetry Collector, залежить від бібліотек інструментування, які ви встановили, та шляху коду, який був виконаний всередині застосунку. У попередньому прикладі, використовуючи Slim Framework та PSR-18 бібліотеки інструментування, ви повинні очікувати побачити такі відрізки, як:

• Кореневий відрізок, що представляє HTTP транзакцію
• Відрізок для дії, яка була виконана
• Відрізок для кожної HTTP транзакції, яку відправив PSR-18 клієнт

Зверніть увагу, що інструментування PSR-18 клієнта додає заголовки розподіленого трасування до вихідних HTTP запитів.

Як це працює

Розширення дозволяє реєструвати функції спостерігачів як PHP код для класів та методів, і виконувати ці функції до та після виконання спостережуваного методу.

Якщо немає бібліотеки інструментування для вашого фреймворку або застосунку, ви можете написати свою власну. Наступний приклад надає деякий код для інструментування, а потім ілюструє, як використовувати розширення OpenTelemetry для трасування виконання цього коду.

<?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();

Попередній приклад визначає DemoClass, а потім реєструє pre та post функції хуків на його методі run. Функції хуків виконуються до та після кожного виконання методу DemoClass::run(). Функція pre починає та активує відрізок, тоді як функція post завершує його.

Якщо DemoClass::run() викидає виключення, функція post записує його без впливу на поширення виключення.

Наступні кроки

Після того, як ви налаштували автоматичне інструментування для вашого застосунку або сервісу, ви можете додати ручне інструментування для збору користувацьких телеметричних даних.

Для більшої кількості прикладів дивіться opentelemetry-php-contrib/examples.