Instrumentation Zero-code PHP

Prérequis

L’instrumentation automatique avec PHP nécessite :

Installer l’extension OpenTelemetry

L’extension peut être installée via pecl, pickle, PIE ou php-extension-installer (spécifique à docker). Il existe également des versions packagées de l’extension disponibles pour certains gestionnaires de paquets Linux.

Paquets Linux

Les paquets RPM et APK sont fournis par les sources suivantes :

#cet exemple est pour CentOS 7. La version PHP peut être changée en
#activant remi-<version>, exemple: "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

#Au moment de la rédaction, PHP 8.1 était la version PHP par défaut. Vous devrez peut-être
#changer "php81" si la valeur par défaut change. Vous pouvez alternativement choisir une version PHP
#avec "apk add php<version>", ex "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. Configurer l’environnement de développement. L’installation depuis les sources nécessite un environnement de développement approprié et quelques dépendances :

    sudo apt-get install gcc make autoconf

    brew install gcc make autoconf

  2. Compiler/installer l’extension. Avec votre environnement configuré, vous pouvez installer l’extension :

    pecl install opentelemetry

    php pickle.phar install opentelemetry

    install-php-extensions opentelemetry

  3. Ajouter l’extension à votre fichier php.ini :

    [opentelemetry]
extension=opentelemetry.so

  4. Vérifier que l’extension est installée et activée :

    php -m | grep opentelemetry

Installer le SDK et les bibliothèques d’instrumentation

Maintenant que l’extension est installée, installez le SDK OpenTelemetry et une ou plusieurs bibliothèques d’instrumentation.

L’instrumentation automatique est disponible pour un certain nombre de bibliothèques PHP couramment utilisées. Pour voir la liste complète, rendez vous sur la page: bibliothèques d’instrumentation sur packagist.

Supposons que votre application utilise Slim Framework et un client HTTP PSR-18, et que nous exporterons les traces avec le protocole OTLP.

Vous installeriez alors le SDK, un exportateur, et les paquets d’auto-instrumentation pour Slim Framework et PSR-18 :

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

Configuration

Lorsqu’elle est utilisée conjointement avec le SDK OpenTelemetry, vous pouvez utiliser des variables d’environnement ou le fichier php.ini pour configurer l’auto-instrumentation.

Configuration par variables d’environnement

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

Configuration php.ini

Ajoutez ce qui suit à php.ini, ou à un autre fichier ini qui sera traité par PHP :

OTEL_PHP_AUTOLOAD_ENABLED="true"
OTEL_SERVICE_NAME=your-service-name
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
OTEL_PROPAGATORS=baggage,tracecontext

Exécuter votre application

Une fois que tout ce qui précède soit installé et configuré, démarrez votre application comme vous le feriez normalement.

Les traces exportées vers le Collecteur OpenTelemetry dépendent des bibliothèques d’instrumentation que vous avez installées, et du chemin de code qui a été pris à l’intérieur de l’application. Dans l’exemple précédent (utilisant les bibliothèques d’instrumentation Slim Framework et PSR-18) vous devriez voir des spans tels que :

  • Un span racine représentant la transaction HTTP
  • Un span pour l’action qui a été exécutée
  • Un span pour chaque transaction HTTP que le client PSR-18 a envoyée

Notez que l’instrumentation du client PSR-18 ajoute des en-têtes de trace distribuée aux requêtes HTTP sortantes.

Comment ça fonctionne

L’extension permet d’enregistrer des fonctions d’observation en tant que code PHP contre des classes et méthodes, et d’exécuter ces fonctions avant et après l’exécution de la méthode observée.

S’il n’y a pas de bibliothèque d’instrumentation pour votre framework ou application, vous pouvez écrire la vôtre. L’exemple suivant fournit du code à instrumenter, puis illustre comment utiliser l’extension OpenTelemetry pour tracer l’exécution de ce code.

<?php

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

require 'vendor/autoload.php';

/* La classe à instrumenter */
class DemoClass
{
    public function run(): void
    {
        echo 'Hello, world';
    }
}

/* Le code d'auto-instrumentation */
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();
    }
);

/* Exécuter le code instrumenté, qui générera une trace */
$demo = new DemoClass();
$demo->run();

L’exemple précédent définit DemoClass, puis enregistre des fonctions de hook pre et post sur sa méthode run. Les fonctions de hook s’exécutent avant et après chaque exécution de la méthode DemoClass::run(). La fonction pre démarre et active un span, tandis que la fonction post le termine.

Si DemoClass::run() lève une exception, la fonction post l’enregistre sans affecter la propagation de l’exception.

Étapes suivantes

Après avoir configuré l’instrumentation automatique pour votre application, vous pourriez ajouter une instrumentation manuelle pour collecter des données de télémétrie personnalisées.

Pour plus d’exemples, voir opentelemetry-php-contrib/examples.


Dernière modification August 26, 2025: [fr] Translation of Zero Code PHP docs (#7393) (3375f448)