# Instrumentation Zero-code PHP ## Prérequis {#requirements} L'instrumentation automatique avec PHP nécessite : - PHP 8.0 ou supérieur - [l'extension PHP OpenTelemetry](https://github.com/open-telemetry/opentelemetry-php-instrumentation) - [Composer autoloading](https://getcomposer.org/doc/01-basic-usage.md#autoloading) - [le SDK OpenTelemetry](https://packagist.org/packages/open-telemetry/sdk) - Une ou plusieurs [des bibliothèques d'instrumentation](/ecosystem/registry/?component=instrumentation&language=php) - [une configuration](#configuration) ## Installer l'extension OpenTelemetry {#install-the-opentelemetry-extension} L'extension peut être installée via pecl, [pickle](https://github.com/FriendsOfPHP/pickle), [PIE](https://github.com/php/pie) ou [php-extension-installer](https://github.com/mlocati/docker-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 {#linux-packages} Les paquets RPM et APK sont fournis par les sources suivantes : - [Dépôt Remi](https://blog.remirepo.net/pages/PECL-extensions-RPM-status) - RPM - [Alpine Linux](https://pkgs.alpinelinux.org/packages?name=*pecl-opentelemetry) - APK (actuellement dans la [branche _testing_](https://wiki.alpinelinux.org/wiki/Repositories#Testing)) 
#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` : ```ini [opentelemetry] extension=opentelemetry.so ``` 4. Vérifier que l'extension est installée et activée : ```sh php -m | grep opentelemetry ``` ## Installer le SDK et les bibliothèques d'instrumentation {#install-sdk-and-instrumentation-libraries} 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](https://packagist.org/search/?query=open-telemetry&tags=instrumentation). 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 : ```shell 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 {#environment-configuration} ```sh 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 {#phpini-configuration} Ajoutez ce qui suit à `php.ini`, ou à un autre fichier `ini` qui sera traité par PHP : ```ini 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 {#run-your-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](/docs/concepts/context-propagation/#propagation) aux requêtes HTTP sortantes. ## Comment ça fonctionne {#how-it-works} 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 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 {#next-steps} Après avoir configuré l'instrumentation automatique pour votre application, vous pourriez ajouter une [instrumentation manuelle](/docs/languages/php/instrumentation) pour collecter des données de télémétrie personnalisées. Pour plus d'exemples, voir [opentelemetry-php-contrib/examples](https://github.com/open-telemetry/opentelemetry-php-contrib/tree/main/examples).