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 les configurations 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.
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.
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-untrustedL’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’UI. 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.
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 :
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.
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.
L’APM PHP prend en charge les versions suivantes de PHP :
| Version | Type de prise en charge |
|---|---|
| 7.4.x | Prise en charge complète |
| 7.3.x | Prise en charge complète |
| 7.2.x | Prise en charge complète |
| 7.1.x | Prise en charge complète |
| 7.0.x | Prise en charge complète |
| 5.6.x | Prise en charge complète |
| 5.4.x | Prise en charge complète |
L’APM PHP prend en charge les SAPI suivants :
| SAPI | Type de prise en charge |
|---|---|
| apache2handler | Prise en charge complète |
| cli | Prise en charge complète |
| fpm-fcgi | Prise en charge complète |
| cgi-fcgi | Prise en charge complète |
Par défaut, Datadog prend en charge tous les frameworks Web PHP. Vous pouvez ainsi visualiser les traces des spans des bibliothèques prises en charge, par exemple pour des clients de base de données et HTTP.
Le tableau suivant énumère plusieurs frameworks et versions pour lesquels Datadog peut surveiller des traces.
Fraweworks Web :
| Module | Versions | Type de prise en charge |
|---|---|---|
| CakePHP | 2.x | Toutes les versions PHP |
| CodeIgniter | 2.x, 3.x | PHP 7+ |
| Laravel | 4.2, 5.x, 6.x | Toutes les versions PHP |
| Lumen | 5.2+ | Toutes les versions PHP |
| Slim | 3.x | Toutes les versions PHP |
| Symfony | 3.3, 3.4, 4.x | Toutes les versions PHP |
| WordPress | 4.x, 5.x | PHP 7+ |
| Zend Framework | 1.12 | Toutes les versions PHP |
| Yii | 1.1, 2.0 | Toutes les versions PHP |
| Drupal | Toutes les versions PHP | |
| Magento | 2 | Toutes les versions PHP |
| Phalcon | 1.3, 3.4 | Toutes les versions PHP |
| Slim | 2.x | Toutes les versions PHP |
| Neos Flow | 1.1 | Toutes les versions PHP |
| FuelPHP | 1.1 | PHP 7+ |
Attention : même si votre framework Web n’est pas répertorié, il est par défaut pris en charge avec la dernière version du traceur.
Vous souhaitez utiliser davantage de métadonnées de span et de fonctionnalités internes des frameworks ? Datadog élargit continuellement la prise en charge du tracing avancé pour les frameworks Web PHP. Contactez l’équipe Datadog pour obtenir de l’aide.
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.
| Module | Versions | Type de prise en charge |
|---|---|---|
| Console CakePHP | 2.x | Prise en charge complète |
| Laravel Artisan | 5.x | Prise en charge complète |
| Console Symfony | Disponible 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.
| Module | Versions | Type de prise en charge |
|---|---|---|
| Amazon RDS (avec PDO ou MySQLi) | (Toute version de PHP prise en charge) | Prise en charge complète |
| Elasticsearch | 1.x | Prise en charge complète |
| Eloquent | Versions prises en charge par Laravel | Prise en charge complète |
| Memcached | (Toute version de PHP prise en charge) | Prise en charge complète |
| MongoDB | 1.4.x | Prise 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 |
| Predis | 1.1 | Prise en charge complète |
| AWS Couchbase | AWS PHP SDK 3 | Disponible prochainement |
| AWS DynamoDB | AWS PHP SDK 3 | Disponible prochainement |
| AWS ElastiCache | AWS PHP SDK 3 | Disponible prochainement |
| Doctrine ORM | 2 | Disponible prochainement |
| ODBC | (Toute version de PHP prise en charge) | Disponible prochainement |
| PHPredis | 4 | Disponible prochainement |
| Solarium | 4.2 | Disponible 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.
| Module | Versions | Type de prise en charge |
|---|---|---|
| Curl | (Toute version de PHP prise en charge) | Prise en charge complète |
| Guzzle | 5.x | Prise en charge complète |
| Guzzle | 6.x | Prise en charge complète |
| Beanstalkd | Disponible prochainement | |
| ReactPHP | Disponible 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.
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.
Pour Apache avec php-fpm, utilisez le répertoire env de votre fichier de configuration www.conf pour configurer le traceur PHP. Exemple :
env[DD_AGENT_HOST] = $FROM_HOST_ENV
env[DD_TRACE_DEBUG] = trueVous pouvez également utiliser SetEnv depuis la configuration du serveur, le host virtuel, le répertoire ou le fichier .htaccess.
SetEnv DD_TRACE_DEBUG truePour NGINX, utilisez le répertoire env dans le fichier www.conf de php-fpm. Exemple :
env[DD_AGENT_HOST] = $FROM_HOST_ENV
env[DD_TRACE_DEBUG] = trueDéfini depuis la ligne de commande pour démarrer le serveur.
DD_TRACE_DEBUG=true php -S localhost:8888| Variable d’environnement | Valeur par défaut | Remarque |
|---|---|---|
DD_AGENT_HOST | localhost | Nom du host de l’Agent |
DD_AUTOFINISH_SPANS | false | Définit si les spans doivent être automatiquement finalisées ou non lorsque le traceur est vidé |
DD_DISTRIBUTED_TRACING | true | Définit si le tracing distribué doit être activé ou non |
DD_INTEGRATIONS_DISABLED | null | Liste au format CSV des intégrations à désactiver, p. ex. : curl,mysqli (voir la section Noms des intégrations). |
DD_PRIORITY_SAMPLING | true | Active ou désactive l’échantillonnage prioritaire |
DD_SERVICE_NAME | null | Nom par défaut de l’application |
DD_SERVICE_MAPPING | null | Modifie 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_MSEC | 5000 | Délai de nouvelle tentative du disjoncteur configurable basé sur IPC (en millisecondes) |
DD_TRACE_AGENT_CONNECT_TIMEOUT | 100 | Délai maximum autorisé pour la configuration de la connexion de l’Agent (en millisecondes) |
DD_TRACE_AGENT_CONNECT_TIMEOUT | 100 | Délai d’expiration de la connexion de l’Agent (en millisecondes) |
DD_TRACE_AGENT_MAX_CONSECUTIVE_FAILURES | 3 | Nombre maximal de tentatives du disjoncteur configurable basé sur IPC (en millisecondes) |
DD_TRACE_AGENT_PORT | 8126 | Port de l’Agent |
DD_TRACE_AGENT_TIMEOUT | 500 | Délai d’expiration du transfert de la requête de l’Agent (en millisecondes) |
DD_TRACE_ANALYTICS_ENABLED | false | Flag pour activer la fonction App Analytics pour les spans pertinentes dans les intégrations Web |
DD_TRACE_AUTO_FLUSH_ENABLED | false | Vider 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_ENABLED | false | Active le tracing de scripts PHP depuis le CLI |
DD_TRACE_DEBUG | false | Active le mode debugging pour le traceur |
DD_TRACE_ENABLED | true | Active le traceur partout |
DD_TRACE_GENERATE_ROOT_SPAN | true | Gé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_TRACE_GLOBAL_TAGS | null | Tags à appliquer à toutes les spans, p. ex. : key1:value1,key2:value2. |
DD_TRACE_HTTP_CLIENT_SPLIT_BY_DOMAIN | false | Dé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_MEASURE_COMPILE_TIME | true | Enregistre la durée de compilation de la requête (en millisecondes) dans la span de premier niveau |
DD_TRACE_NO_AUTOLOADER | false | Dé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_REPORT_HOSTNAME | false | Active la transmission du hostname sur la span racine |
DD_TRACE_RESOURCE_URI_MAPPING | null | Règles de mappage de l’URL au nom de la ressource au format CSV, par exemple : /foo/*,/bar/$*/baz (voir la section Mappage personnalisé de l’URL à la ressource) |
DD_TRACE_SAMPLE_RATE | 1.0 | Taux 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_RULES | null | Chaî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_ENABLED | true | Activer les URL en tant que noms de ressources (voir la section Mapper les noms de ressources à une URL normalisée). |
DD_<INTÉGRATION>_ANALYTICS_ENABLED | false | Flag pour activer App Analytics pour les spans pertinentes dans une intégration spécifique (voir la section Noms des intégrations). |
DD_<INTÉGRATION>_ANALYTICS_SAMPLE_RATE | 1.0 | Définir le taux d’échantillonnage App Analytics pour les spans pertinentes dans une intégration spécifique (voir la section 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_<INTÉGRATION>_ANALYTICS_ENABLED. Exemple pour Laravel : DD_LARAVEL_ANALYTICS_ENABLED.
| Intégration | Service Name |
|---|---|
| CakePHP | cakephp |
| CodeIgniter | codeigniter |
| cURL | curl |
| ElasticSearch | elasticsearch |
| Eloquent | eloquent |
| Guzzle | guzzle |
| Laravel | laravel |
| Lumen | lumen |
| Memcached | memcached |
| Mongo | mongo |
| Mysqli | mysqli |
| PDO | pdo |
| Predis | predis |
| Slim | slim |
| Symfony | symfony |
| WordPress | wordpress |
| Yii | yii |
| ZendFramework | zendframework |
Par défaut, 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 HTTP | Nom de la ressource |
|---|---|
GET request to /foo?a=1&b=2 | GET /foo |
POST request to /bar?foo=bar | POST /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/show | GET /user/?/show |
/widget/b7a992e0-3300-4030-8617-84553b11c993 | GET /widget/? |
/api/v2/b7a992e033004030861784553b11c993/123 | GET /api/v2/?/? |
/book/0dbf3596 | GET /book/? |
Vous pouvez désactiver cette fonctionnalité avec DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED=false.
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 * et $* sont pris en charge. DD_TRACE_RESOURCE_URI_MAPPING=/foo/*,/bar/$*/baz est donc valide. Dans ce contexte, * est une correspondance gourmande avec un caractère de remplacement ?, et $* forme une correspondance gourmande sans remplacement.
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 mappage | URL (requête GET) | Nom de la ressource |
|---|---|---|
/foo/* | /foo/bar | GET /foo/? |
/foo/*/bar | /foo/baz/faz/bar | GET /foo/?/bar |
/foo-*-bar | /foo-secret-bar | GET /foo-?-bar |
Le wildcard $* est mis en correspondance sans être remplacé.
| Règle de mappage | URL (requête GET) | Nom de la ressource |
|---|---|---|
/state/$*/show | /state/kentucky/show | GET /state/kentucky/show |
/widget/*/type/$* | /widget/foo-id/type/green | GET /widget/?/type/green |
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.
Pour supprimer le tracer PHP :
98-ddtrace.ini and 99-ddtrace-custom.ini de votre dossier de configuration PHP.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.
Documentation, liens et articles supplémentaires utiles:
Sur cette page
