Nouvelles annonces sur les technologies sans serveur et réseau ainsi que sur le RUM (Real-User Monitoring) dévoilées à la conférence Dash ! Nouvelles annonces dévoilées à la conférence Dash !

Tracer des applications PHP

Installation et démarrage

Si vous avez déjà un compte Datadog, vous trouverez des instructions détaillées dans nos guides intégrés à l'application pour les configurations basées sur un host et basées sur un conteneur.

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 en passant par l’Agent Datadog.

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

Assurez-vous que l’APM est activé dans le fichier de configuration de 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 téléchargé, installez le paquet avec l’une des commandes ci-dessous.

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

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

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

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’UI. Si, une fois ce délai passé, elles n’apparaissent toujours pas, [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

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

Même si Datadog ne prend pas officiellement en charge votre framework Web, une instrumentation manuelle n’est pas forcément nécessaire. Datadog enregistre les requêtes Web génériques et crée des traces génériques pour celles-ci. Toutefois, lorsque vous utilisez l’un des frameworks pris en charge, Datadog définit des métadonnées plus pertinentes, ce qui facilite la navigation dans vos services.

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 si disponibles
  • Le nombre total de traces (p. ex. les requêtes Web) transmises via le système

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.

Compatibilité

L’APM PHP prend en charge les versions PHP suivantes :

VersionType de prise en charge
7.3.xPrise en charge complète
7.2.xPrise en charge complète
7.1.xPrise en charge complète
7.0.xPrise en charge complète
5.6.xPrise en charge complète
5.4.xPrise en charge complète

L’APM PHP prend en charge les SAPI suivantes :

SAPIType de prise en charge
apache2handlerPrise en charge complète
cliPrise en charge complète
fpmPrise en charge complète

Intégrations

Compatibilité des frameworks Web

Si le framework Web que vous utilisez ne figure pas dans la liste ci-dessous, vous pouvez toujours consulter les traces pour vos requêtes Web depuis l’interface. Toutefois, il est possible que certaines métadonnéees et spans très spécifiques à ce framework Web ne s’affichent pas.

ModuleVersionsType de prise en charge
CakePHP2.xPrise en charge complète
CodeIgniter2.xPHP 7
Laravel4.2, 5.xPrise en charge complète
Lumen5.2+Prise en charge complète
Slim3.xPrise en charge complète
Symfony3.3, 3.4, 4.xPrise en charge complète
WordPress4.xPHP 7
Zend Framework1.12Prise en charge complète
CodeIgniter3.xDisponible prochainement
DrupalDisponible prochainement
Magento2Disponible prochainement
Phalcon1.3, 3.4Disponible prochainement
Slim2.xDisponible prochainement
Yii1.1Disponible prochainement

Votre framework préféré n’est pas disponible ? Datadog élargit continuellement la liste des frameworks pris en charge. Contactez l’équipe Datadog pour obtenir de l’aide.

Compatibilité des bibliothèques CLI

Le tracing depuis le CLI SAPI est désactivé par défaut. Pour activer le tracing des scripts CLI PHP, définissez DD_TRACE_CLI_ENABLED=true.

ModuleVersionsType de prise en charge
Console CakePHP2.xPrise en charge complète
Laravel Artisan5.xPrise en charge complète
Console SymfonyDisponible prochainement

Votre bibliothèque CLI préférée n’est pas disponible ? Datadog élargit continuellement la liste des bibliothèques prises en charge. Contactez l’équipe Datadog pour obtenir de l’aide.

Compatibilité des datastores

ModuleVersionsType de prise en charge
Amazon RDS (avec PDO ou MySQLi)(Toute version de PHP prise en charge)Prise en charge complète
Elasticsearch1.xPrise en charge complète
EloquentVersions prises en charge par LaravelPrise en charge complète
Memcached(Toute version de PHP prise en charge)Prise en charge complète
MongoDB1.4.xPrise en charge complète
MySQLi(Toute version de PHP prise en charge)Prise en charge complète
PDO (MySQL, PostgreSQL, MariaDB)(Toute version de PHP prise en charge)Prise en charge complète
Predis1.1Prise en charge complète
AWS CouchbaseAWS PHP SDK 3Disponible prochainement
AWS DynamoDBAWS PHP SDK 3Disponible prochainement
AWS ElastiCacheAWS PHP SDK 3Disponible prochainement
Doctrine ORM2Disponible prochainement
ODBC(Toute version de PHP prise en charge)Disponible prochainement
PHPredis4Disponible prochainement
Solarium4.2Disponible prochainement

Votre datastore préféré n’est pas disponible ? Datadog élargit continuellement la liste des datastores pris en charge. Contactez l’équipe Datadog pour obtenir de l’aide.

Compatibilité des bibliothèques

ModuleVersionsType de prise en charge
Curl(Toute version de PHP prise en charge)Prise en charge complète
Guzzle5.xPrise en charge complète
Guzzle6.xPrise en charge complète
BeanstalkdDisponible prochainement
ReactPHPDisponible prochainement

Vos bibliothèques préférées ne sont pas disponibles ? Datadog élargit continuellement la liste des bibliothèques prises en charge. Contactez l’équipe Datadog pour obtenir de l’aide.

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

Défini avec SetEnv depuis la configuration du serveur, le host virtuel, le répertoire ou le fichier .htaccess.

SetEnv DD_TRACE_DEBUG true

NGINX

Défini avec fastcgi_param depuis les contextes http, server, ou location.

fastcgi_param DD_TRACE_DEBUG true;

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_HOSTlocalhostLe hostname de l’Agent
DD_AUTOFINISH_SPANSfalseDéfinit si les spans doivent être automatiquement finalisées ou non lorsque le traceur est vidé
DD_TRACE_CLI_ENABLEDfalseActive le tracing de scripts PHP depuis le CLI
DD_DISTRIBUTED_TRACINGtrueDéfinit si le tracing distribué doit être activé ou non
DD_INTEGRATIONS_DISABLEDnullListe au format CSV des extensions désactivées ; p. ex. curl,mysqli
DD_PRIORITY_SAMPLINGtrueActive ou non l’échantillonnage prioritaire.
DD_SAMPLING_RATE1.0Le taux d’échantillonnage des traces. Entre 0.0 et 1.0 (par défaut)
DD_SERVICE_NAME``Le nom par défaut de l’application
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 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_PORT8126Le port de l’Agent
DD_TRACE_AGENT_TIMEOUT500Délai d’expiration du transfert de la requête de l’Agent (en millisecondes)
DD_TRACE_AGENT_CONNECT_TIMEOUT100Le temps maximum autorisé pour la configuration de la connexion de l’Agent (en millisecondes)
DD_TRACE_ANALYTICS_ENABLEDfalseFlag pour activer les analyses de traces pour les spans pertinentes dans les intégrations Web
DD_TRACE_DEBUGfalseActive le mode debugging pour le traceur
DD_TRACE_ENABLEDtrueActiver le traceur partout
DD_TRACE_GLOBAL_TAGS``Tags à appliquer à toutes les spans : p. ex. key1:value1,key2:value2
DD_TRACE_REPORT_HOSTNAMEfalseActive la transmission du hostname sur la span racine
DD_TRACE_RESOURCE_URI_MAPPINGnullFichier CSV comprenant les règles de mappage de l’URL au nom de la ressource, p. ex. : /foo/*,/bar/$*/baz ; voir la section Mappage personnalisé de l’URL à la ressource
DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLEDfalseActive les URL en tant que noms de ressources ; voir la section Mappage des noms de ressources aux URI normalisées
DD_<INTÉGRATION>_ANALYTICS_ENABLEDfalseFlag pour activer les analyses de traces pour les spans pertinentes dans une intégration spécifique

Mappage des noms de ressources aux URI normalisées

Cette fonctionnalité est en bêta publique. Si vous avez besoin d'aide, contactez l'assistance Datadog.

Lorsque le paramètre DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED=true est défini, 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/?
Mappage personnalisé de l’URL à la ressource

Lorsque les noms de ressources d’URL sont activés, le mappage d’URL personnalisé se configure via DD_TRACE_RESOURCE_URI_MAPPING. Ce paramètre accepte une liste CSV de règles de mappage. Les wildcards * (modification gourmande avec remplacement par le caractère ?) et $* (modification gourmande sans remplacement) sont pris en charge. Exemple : DD_TRACE_RESOURCE_URI_MAPPING=/foo/*,/bar/$*/baz.

Les règles sont appliquées dans leur ordre d’affichage dans DD_TRACE_RESOURCE_URI_MAPPING. Les règles moins gourmandes doivent figurer avant les règles gourmandes. Exemple : /foo/$*/bar,/foo/*.

Le wildcard * wildcard est remplacé par ?.

Règle de mappageURL (requête GET)Nom de la ressource
/foo/*/foo/barGET /foo/?
/foo/*/bar/foo/baz/faz/barGET /foo/?/bar
/foo-*-bar/foo-secret-barGET /foo-?-bar

Le wildcard $* est mis en correspondance sans être remplacé.

Règle de mappageURL (requête GET)Nom de la ressource
/state/$*/show/state/kentucky/showGET /state/kentucky/show
/widget/*/type/$*/widget/foo-id/type/greenGET /widget/?/type/green

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.

Pour aller plus loin