Tracer des applications PHP
Rapport de recherche Datadog : Bilan sur l'adoption de l'informatique sans serveur Rapport : Bilan sur l'adoption de l'informatique sans serveur

Tracer des applications PHP

Exigences de compatibilité

Pour obtenir la liste complète des versions de langage et des bibliothèques prises en charge, consultez la page Exigences de compatibilité.

Installation et démarrage

Suivre la documentation intégrée à l’application (conseillé)

Suivez les instructions de démarrage rapide fournies dans l’application Datadog pour profiter d’une expérience optimale, et notamment :

  • Obtenir des instructions détaillées en fonction de la configuration de votre déploiement (hosts, Docker, Kubernetes ou Amazon ECS) ;
  • Définir les tags service, env et version de façon dynamique ;
  • Activer la fonctionnalité App Analytics durant la configuration.

Pour connaître la définition des termes utilisés dans l’APM, consultez la documentation officielle.

Pour découvrir comment effectuer des contributions open source au traceur PHP, consultez le guide relatif aux contributions.

Configurer l’Agent Datadog

Le traceur de l’APM PHP envoie les données de trace par l’intermédiaire de l’Agent Datadog.

Installez et configurez l’Agent Datadog. Consultez la documentation supplémentaire relative au tracing d’applications Docker ou au tracing d’applications Kubernetes.

Pour les versions 7.18.0 et ultérieures de l’Agent, l’APM est activé par défaut pour tous les environnements. Si vous exécutez une version plus ancienne de l’Agent, vérifiez que vous avez activé l’APM pour l’Agent.

Installer l’extension

Installez l’extension PHP à l’aide de l’un des paquets pré-compilés pour les distributions prises en charge.

Une fois le paquet téléchargé, installez-le avec l’une des commandes ci-dessous.

# avec le paquet RPM (RHEL/Centos 6+, Fedora 20+)
rpm -ivh datadog-php-tracer.rpm

# avec le paquet DEB (Debian Jessie ou ultérieur, Ubuntu 14.04+ sur les versions de PHP prises en charge)
dpkg -i datadog-php-tracer.deb

# avec le paquet APK (Alpine)
apk add datadog-php-tracer.apk --allow-untrusted

L’extension sera installée pour la version de PHP par défaut. Si vous souhaitez installer l’extension pour une version spécifique de PHP, utilisez la variable d’environnement DD_TRACE_PHP_BIN pour définir l’emplacement du binaire PHP cible avant de lancer l’installation.

export DD_TRACE_PHP_BIN=$(which php-fpm7)

Redémarrez PHP (PHP-FPM ou le SAPI Apache), puis consultez un endpoint de votre application pour lequel le tracing est activé. Affichez l’interface de l’APM pour visualiser les traces.

Remarque : quelques minutes peuvent s’écouler avant que les traces soient visibles dans l’interface utilisateur. Si elles n’apparaissent toujours pas une fois ce délai passé, exécutez le script de diagnostic dd-doctor.php depuis la machine du host afin d’identifier les éventuels problèmes.

Si vous ne trouvez pas votre distribution, vous pouvez installer manuellement l’extension PHP.

Instrumentation automatique

Par défaut, le tracing est automatiquement activé. Une fois l’extension installée, ddtrace trace votre application et envoie les traces à l’Agent.

Par défaut, Datadog prend en charge tous les frameworks Web. L’instrumentation automatique fonctionne en modifiant l’exécution de PHP pour wrapper certaines fonctions et méthodes afin de les tracer. Le traceur PHP prend en charge l’instrumentation automatique pour plusieurs bibliothèques.

L’instrumentation automatique capture :

  • Le temps d’exécution de la méthode
  • Les données de trace pertinentes, telles que l’URL et les codes de réponse de statut pour les requêtes Web ou les requêtes SQL pour l’accès à la base de données
  • Les exceptions non traitées, y compris les traces de pile le cas échéant
  • Le nombre total de traces (p. ex. les requêtes Web) transmises via le système

Remarque : si votre application n’utilise pas Composer ni un chargeur automatique enregistré avec spl_autoload_register(), définissez la variable d’environnement DD_TRACE_NO_AUTOLOADER=true pour activer l’instrumentation automatique.

Modifier le hostname de l’Agent

Configurez vos traceurs d’applications de façon à envoyer des traces à un hostname d’Agent personnalisé :

Le traceur PHP recherche automatiquement les variables ENV DD_AGENT_HOST et DD_TRACE_AGENT_PORT puis s’initialise avec celles-ci.

Consultez la configuration du traceur pour découvrir comment définir ces variables.

Configuration

Le traceur PHP peut être configuré à l’aide de variables d’environnement.

Remarque : si vous utilisez l’instrumentation automatique du code (la méthode conseillée), rappelez-vous que le code instrumenté s’exécute avant le code utilisateur. Par conséquent, les variables d’environnement ci-dessous doivent être définies au niveau du serveur et mises à disposition de l’environnement d’exécution PHP avant l’exécution de tout code utilisateur. Par exemple, putenv() et les fichiers .env ne fonctionneraient pas.

Apache

Pour Apache avec php-fpm, utilisez le répertoire env de votre fichier de configuration www.conf pour configurer le traceur PHP. Exemple :

; Example of passing the host environment variable SOME_ENV
; to the PHP process as DD_AGENT_HOST
env[DD_AGENT_HOST] = $SOME_ENV
; Example of passing the value 'my-app' to the PHP
; process as DD_SERVICE
env[DD_SERVICE] = my-app

Vous pouvez également utiliser SetEnv depuis la configuration du serveur, le host virtuel, le répertoire ou le fichier .htaccess.

SetEnv DD_TRACE_DEBUG true

NGINX

Pour NGINX, utilisez la directive env dans le fichier www.conf de php-fpm. Exemple :

; Example of passing the host environment variable SOME_ENV
; to the PHP process as DD_AGENT_HOST
env[DD_AGENT_HOST] = $SOME_ENV
; Example of passing the value 'my-app' to the PHP
; process as DD_SERVICE
env[DD_SERVICE] = my-app

Remarque : si vous avez activé l’APM pour votre serveur NGINX, assurez-vous d’avoir correctement configuré le paramètre opentracing_fastcgi_propagate_context pour que le tracing distribué fonctionne correctement. Consultez la configuration de l’APM NGINX pour obtenir plus d’informations.

Serveur CLI PHP

Défini depuis la ligne de commande pour démarrer le serveur.

DD_TRACE_DEBUG=true php -S localhost:8888

Configuration des variables d’environnement

Variable d’environnementValeur par défautRemarque
DD_AGENT_HOSTlocalhostNom du host de l’Agent
DD_AUTOFINISH_SPANSfalseDéfinit si les spans doivent être automatiquement finalisées ou non lorsque le traceur est vidé
DD_DISTRIBUTED_TRACINGtrueDéfinit si le tracing distribué doit être activé ou non
DD_ENVnullDéfinit l’environnement de l’application, par exemple prod, pre-prod ou encore stage. Ajouté dans la version 0.47.0.
DD_PRIORITY_SAMPLINGtrueActive ou désactive l’échantillonnage prioritaire
DD_SERVICEnullLe nom de l’app par défaut. Pour les versions < 0.47.0, il s’agit de DD_SERVICE_NAME.
DD_SERVICE_MAPPINGnullModifie le nom par défaut d’une intégration APM. Vous pouvez remplacer le nom de plusieurs intégrations à la fois. Utilisez par exemple DD_SERVICE_MAPPING=pdo:payments-db,mysqli:orders-db (voir la section Noms des intégrations).
DD_TRACE_AGENT_ATTEMPT_RETRY_TIME_MSEC5000Délai de nouvelle tentative du disjoncteur configurable basé sur IPC (en millisecondes)
DD_TRACE_AGENT_CONNECT_TIMEOUT100Délai maximum autorisé pour la configuration de la connexion de l’Agent (en millisecondes)
DD_TRACE_AGENT_CONNECT_TIMEOUT100Délai d’expiration de la connexion de l’Agent (en millisecondes)
DD_TRACE_AGENT_MAX_CONSECUTIVE_FAILURES3Nombre maximal de tentatives du disjoncteur configurable basé sur IPC (en millisecondes)
DD_TRACE_AGENT_PORT8126Port de l’Agent
DD_TRACE_AGENT_TIMEOUT500Délai d’expiration du transfert de la requête de l’Agent (en millisecondes)
DD_TRACE_AGENT_URLnullL’URL de l’Agent, qui l’emporte sur DD_AGENT_HOST et sur DD_TRACE_AGENT_PORT. Exemple : https://localhost:8126. Ajoutée dans la version 0.47.1.
DD_TRACE_ANALYTICS_ENABLEDfalseFlag pour activer la fonction App Analytics pour les spans pertinentes dans les intégrations Web
DD_TRACE_AUTO_FLUSH_ENABLEDfalseVider automatiquement le traceur lorsque toutes les spans sont finalisées ; définir sur true conjointement à DD_TRACE_GENERATE_ROOT_SPAN=0 pour tracer les processus à exécution longue
DD_TRACE_CLI_ENABLEDfalseActive le tracing de scripts PHP depuis le CLI
DD_TRACE_DEBUGfalseActive le mode debugging pour le traceur
DD_TRACE_ENABLEDtrueActive le traceur partout
DD_TRACE_GENERATE_ROOT_SPANtrueGénérer automatiquement une span de premier niveau ; définir sur false conjointement à DD_TRACE_AUTO_FLUSH_ENABLED=1 pour tracer les processus à exécution longue
DD_TAGSnullTags à appliquer à toutes les spans, p. ex. : key1:value1,key2:value2. Ajoutés dans la version 0.47.0
DD_TRACE_HTTP_CLIENT_SPLIT_BY_DOMAINfalseDéfinir le nom de service des requêtes HTTP sur host-<hostname>. Par exemple, un appel curl_exec() vers https://datadoghq.com prendra le nom de service host-datadoghq.com au lieu du nom de service par défaut curl.
DD_TRACE_<INTÉGRATION>_ANALYTICS_ENABLEDfalseFlag pour activer App Analytics pour les spans pertinentes dans une intégration spécifique (voir la section Noms des intégrations). Pour les versions antérieures à la version 0.47.1, il s’agit du paramètre DD_<INTÉGRATION>_ANALYTICS_ENABLED.
DD_TRACE_<INTÉGRATION>_ANALYTICS_SAMPLE_RATE1.0Définit le taux d’échantillonnage d’App Analytics pour les spans pertinentes dans une intégration spécifique (voir la section Noms des intégrations). Pour les versions antérieures à la version 0.47.1, il s’agit du paramètre DD_<INTÉGRATION>_ANALYTICS_SAMPLE_RATE.
DD_TRACE_<INTÉGRATION>_ENABLEDtrueActive ou désactive une intégration. Par défaut, toutes les intégrations sont activées (voir la section Noms des intégration). Pour les versions antérieures à la version 0.47.1, il s’agit du paramètre DD_INTEGRATIONS_DISABLED, qui accepte une liste d’intégrations à désactiver au format CSV, p. ex. : curl,mysqli.
DD_TRACE_MEASURE_COMPILE_TIMEtrueEnregistre la durée de compilation de la requête (en millisecondes) dans la span de premier niveau
DD_TRACE_NO_AUTOLOADERfalseDéfinissez cette variable d’environnement sur true afin d’activer l’instrumentation automatique pour les applications qui n’utilisent pas de chargeur automatique
DD_TRACE_RESOURCE_URI_FRAGMENT_REGEXnullListe d’expressions regex au format CSV qui identifie les fragments de chemin correspondant aux ID (voir la section Mapper les noms de ressources à un URI normalisé).
DD_TRACE_RESOURCE_URI_MAPPING_INCOMINGnullListe de mappages d’URI au format CSV afin de normaliser les noms de ressources pour les requêtes entrantes (voir la section Mapper les noms de ressources à un URI normalisé).
DD_TRACE_RESOURCE_URI_MAPPING_OUTGOINGnullListe de mappages d’URI au format CSV afin de normaliser les noms de ressources pour les requêtes sortantes (voir la section Mapper les noms de ressources à un URI normalisé).
DD_TRACE_SAMPLE_RATE1.0Taux d’échantillonnage des traces (entre 0.0 et 1.0 par défaut). Pour les versions inférieures à 0.36.0, ce paramètre est DD_SAMPLING_RATE.
DD_TRACE_SAMPLING_RULESnullChaîne encodée au format JSON pour configurer le taux d’échantillonnage. Exemples : définir le taux d’échantillonnage sur 20 % : [{"sample_rate": 0.2}]. Définir le taux d’échantillonnage sur 10 % pour les services commençant par « a » et pour les noms de span commençant par « b » et définir le taux d’échantillonnage sur 20 % pour tous les autres services : [{"service": "a.*", "name": "b", "sample_rate": 0.1}, {"sample_rate": 0.2}] (voir la section Noms des intégrations).
DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLEDtrueActiver les URL en tant que noms de ressources (voir la section Mapper les noms de ressources à une URL normalisée).
DD_VERSIONnullDéfinit la version d’une application dans les traces et logs, par exemple : 1.2.3, 6c44da20, 2020.02.13. Ajoutée dans la version 0.47.0.

Noms des intégrations

Le tableau ci-dessous répertorie les noms de service par défaut pour chaque intégration. Modifiez les noms de service avec DD_SERVICE_MAPPING.

Utilisez ces noms lorsque vous définissez un paramètre pour une intégration spécifique, tel que DD_TRACE_<INTÉGRATION>_ANALYTICS_ENABLED. Exemple pour Laravel : DD_TRACE_LARAVEL_ANALYTICS_ENABLED.

IntégrationService Name
CakePHPcakephp
CodeIgnitercodeigniter
cURLcurl
ElasticSearchelasticsearch
Eloquenteloquent
Guzzleguzzle
Laravellaravel
Lumenlumen
Memcachedmemcached
Mongomongo
Mysqlimysqli
PDOpdo
PhpRedisphpredis
Predispredis
Slimslim
Symfonysymfony
WordPresswordpress
Yiiyii
ZendFrameworkzendframework

Mapper les noms de ressources à une URL normalisée

Paramètre obsolète : À partir de la version 0.47.0, l'ancien paramètre DD_TRACE_RESOURCE_URI_MAPPING est obsolète. Il continuera à fonctionner pendant un certain temps, mais nous vous conseillons vivement d'utiliser les nouveaux paramètres spécifiés dans ce paragraphe pour éviter tout problème une fois l'ancien paramètre supprimé. Notez que la configuration de l'un des paramètres suivants : DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX, DD_TRACE_RESOURCE_URI_MAPPING_INCOMING ou DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING activera la nouvelle approche de normalisation des ressources, et toutes les valeurs spécifiées dans DD_TRACE_RESOURCE_URI_MAPPING seront ignorées.

Pour les intégrations de serveur et client HTTP, l’URL est utilisée afin de créer le nom de ressource de la trace, en suivant le format <MÉTHODE_REQUÊTE_HTTP> <URL_NORMALISÉE>. La chaîne de requête est supprimée de l’URL. Cela vous permet de gagner en visibilité sur les frameworks personnalisés qui ne sont pas instrumentés automatiquement en normalisant les URL et en regroupant les endpoints génériques sous une unique ressource.

Requête HTTPNom de la ressource
GET request to /foo?a=1&b=2GET /foo
POST request to /bar?foo=barPOST /bar

Les ID numériques, les UUID (avec et sans tiret) et les hachages hexadécimaux de 32 à 512 octets sont automatiquement remplacés par le caractère ?.

URL (requête GET)Nom de la ressource
/user/123/showGET /user/?/show
/widget/b7a992e0-3300-4030-8617-84553b11c993GET /widget/?
/api/v2/b7a992e033004030861784553b11c993/123GET /api/v2/?/?
/book/0dbf3596GET /book/?

Vous pouvez désactiver cette fonctionnalité avec DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED=false.

Mappage personnalisé de l’URL à la ressource

Certains cas ne sont pas couverts par la normalisation automatique appliquée.

URL (requête GET)Nom de la ressource attendu
/using/prefix/id123/for/idGET /using/prefix/?/for/id
/articles/slug-of-titleGET /articles/?
/cities/new-york/riversGET /cities/?/rivers
/nested/cities/new-york/riversGET /nested/cities/?/rivers

Deux catégories de scénarios ne sont pas couvertes par la normalisation automatique :

  • Le fragment de chemin à normaliser présente un format reproductible et peut se trouver partout dans l’URL, par exemple id<number> dans l’exemple ci-dessus. Ce scénario est couvert par le paramètre DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX ci-dessous.
  • Le fragment de chemin peut être n’importe quoi, et le fragment de chemin précédent indique qu’une valeur doit être normalisée. Par exemple, /cities/new-york nous indique que new-york doit être normalisé, car c’est le nom d’une ville. Ce scénario est couvert par les paramètres DD_TRACE_RESOURCE_URI_MAPPING_INCOMING et DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING respectivement pour les requêtes entrantes et sortantes.
DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX

Ce paramètre est une liste au format CSV d’expressions regex appliquées indépendamment à chaque fragment de chemin. Par exemple, si le paramètre DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX est défini sur ^id\d+$ pour le premier exemple /using/prefix/id123/for/id, les expressions regex seront appliquées à tous les fragments using, prefix, id123, for et id. Le nom de ressource normalisé final sera GET /using/prefix/?/for/id.

Notez que plusieurs expressions régulières séparées par une virgule peuvent être ajoutées : ^id\d+$,code\d+$. La virgule , n’étant pas échappée, elle ne peut pas être utilisée dans l’expression régulière.

DD_TRACE_RESOURCE_URI_MAPPING_INCOMING et DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING

Ce paramètre est une liste d’expressions au format CSV qui peut contenir une wildcard *. Par exemple, si vous ajoutez l’expression cities/*, cela signifie que chaque fois que le fragment cities est trouvé lors de l’analyse d’une URL, alors le fragment suivant (le cas échéant) sera remplacé par ?. Les expressions sont appliquées à toutes les profondeurs ; par conséquent, la règle suivante entraînera la normalisation de /cities/new-york et /nested/cities/new-york dans le tableau ci-dessus.

Les expressions peuvent être appliquées à une partie d’un fragment spécifique. Par exemple, path/*-fix normalisera l’URL /some/path/changing-fix/nested en /some/path/?-fix/nested

Notez que DD_TRACE_RESOURCE_URI_MAPPING_INCOMING s’applique uniquement aux requêtes entrantes (par exemple, les frameworks Web), tandis que DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING s’applique uniquement aux requêtes sortantes (par exemple, les requêtes curl et guzzle).

Mise à niveau

Pour mettre à niveau le traceur PHP, téléchargez la dernière version et suivez les mêmes étapes que lors de l’installation de l’extension.

Remarque : si vous utilisez une mise en cache secondaire dans OPcache en définissant le paramètre opcache.file_cache, supprimez le dossier de cache.

Suppression

Pour supprimer le tracer PHP :

  1. Pour php-fpm, arrêtez le service php-fpm ou le serveur Web Apache.
  2. Dissociez les fichiers 98-ddtrace.ini and 99-ddtrace-custom.ini de votre dossier de configuration PHP.
  3. Pour php-fpm, redémarrez le service php-fpm ou le serveur Web Apache.

Remarque : si vous utilisez une mise en cache secondaire dans OPcache en définissant le paramètre opcache.file_cache, supprimez le dossier de cache.

Pour aller plus loin