Pour obtenir la liste complète des versions de langage et des bibliothèques prises en charge, consultez la page Exigences de compatibilité.
Suivez les instructions de démarrage rapide fournies dans l’application Datadog pour profiter d’une expérience optimale, et notamment :
service, env et version de façon dynamique ;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.
Installez et configurez l’Agent Datadog de façon à ce qu’il reçoive des traces à partir de votre application instrumentée. Par défaut, l’Agent Datadog est activé dans votre fichier datadog.yaml, sous apm_enabled: true, et écoute le trafic des traces sur localhost:8126. Pour les environnements conteneurisés, suivez les liens ci-dessous afin d’activer la collecte de traces au sein de l’Agent Datadog.
Définissez apm_non_local_traffic: true dans votre fichier de configuration principal datadog.yaml.
Consultez les instructions de configuration spécifiques pour vous assurer que l’Agent est configuré de façon à recevoir des traces dans un environnement conteneurisé :
Après avoir instrumenté votre application, le client de tracing envoie, par défaut, les traces à localhost:8126. S’il ne s’agit pas du host et du port adéquats, modifiez-les en définissant les variables d’environnement ci-dessous :
DD_AGENT_HOST et DD_TRACE_AGENT_PORT
Consultez la configuration des variables d’environnement pour découvrir comment définir ces variables.
DD_SITE dans l’Agent Datadog sur Pour configurer l’APM Datadog dans AWS Lambda, consultez la documentation dédiée au tracing de fonctions sans serveur.
Le tracing est disponible pour un certain nombre d’environnements, tels que Heroku, Cloud Foundry, AWS Elastic Beanstalk et l'extension Azure App Services.
Pour les autres environnements, veuillez consulter la documentation relative aux intégrations pour l’environnement qui vous intéresse. Contactez l’assistance si vous rencontrez des problèmes de configuration.
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. Si elles n’apparaissent toujours pas une fois ce délai passé, créez une page phpinfo() depuis la machine du host et faites défiler jusqu’à la section « ddtrace ». Vous y trouverez les checks de diagnostic qui ont échoué, pour vous aider à 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.
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 :
; Exemple pour passer la variable d'environnement de host SOME_ENV
; au processus PHP en tant que DD_AGENT_HOST
env[DD_AGENT_HOST] = $SOME_ENV
; Exemple pour passer la valeur 'my-app' au processus PHP
; en tant que 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
Pour NGINX, utilisez la directive env dans le fichier www.conf de php-fpm. Exemple :
; Exemple pour passer la variable d'environnement de host SOME_ENV
; au processus PHP en tant que DD_AGENT_HOST
env[DD_AGENT_HOST] = $SOME_ENV
; Exemple pour passer la valeur 'my-app' au processus PHP
; en tant que 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.
Défini depuis la ligne de commande pour démarrer le serveur.
DD_TRACE_DEBUG=true php -S localhost:8888
DD_AGENT_HOSTlocalhostDD_AUTOFINISH_SPANSfalseDD_DISTRIBUTED_TRACINGtrueDD_ENVnullprod, pre-prod ou encore stage. Ajoutée avec la version 0.47.0.DD_PRIORITY_SAMPLINGtrueDD_SERVICEnullDD_SERVICE_NAME.DD_SERVICE_MAPPINGnullDD_SERVICE_MAPPING=pdo:payments-db,mysqli:orders-db (voir la section Noms des intégrations).DD_TRACE_AGENT_ATTEMPT_RETRY_TIME_MSEC5000DD_TRACE_AGENT_CONNECT_TIMEOUT100DD_TRACE_AGENT_CONNECT_TIMEOUT100DD_TRACE_AGENT_MAX_CONSECUTIVE_FAILURES3DD_TRACE_AGENT_PORT8126DD_TRACE_AGENT_TIMEOUT500DD_TRACE_AGENT_URLnullDD_AGENT_HOST et sur DD_TRACE_AGENT_PORT. Exemple : https://localhost:8126. Ajoutée avec la version 0.47.1.DD_TRACE_AUTO_FLUSH_ENABLEDfalsetrue conjointement à DD_TRACE_GENERATE_ROOT_SPAN=0 pour tracer les processus à exécution longue.DD_TRACE_CLI_ENABLEDfalseDD_TRACE_DEBUGfalseDD_TRACE_ENABLEDtrueDD_TRACE_GENERATE_ROOT_SPANtruefalse conjointement à DD_TRACE_AUTO_FLUSH_ENABLED=1 pour tracer les processus à exécution longue.DD_TAGSnullkey1:value1,key2:value2. Ajoutée avec la version 0.47.0.DD_TRACE_HEADER_TAGSnullDD_TRACE_HTTP_CLIENT_SPLIT_BY_DOMAINfalsehost-<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_REDIS_CLIENT_SPLIT_BY_HOSTfalseredis-<hostname>. Ajoutée avec la version 0.51.0.DD_TRACE_<INTEGRATION>_ENABLEDtrue0.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_TIMEtrueDD_TRACE_NO_AUTOLOADERfalsetrue afin d’activer l’instrumentation automatique pour les applications qui n’utilisent pas de chargeur automatique.DD_TRACE_RESOURCE_URI_FRAGMENT_REGEXnullDD_TRACE_RESOURCE_URI_MAPPING_INCOMINGnullDD_TRACE_RESOURCE_URI_MAPPING_OUTGOINGnullDD_TRACE_SAMPLE_RATE1.00.0 et 1.0 par défaut). Pour les versions inférieures à 0.36.0, il s’agit du paramètre DD_SAMPLING_RATE.DD_TRACE_SAMPLING_RULESnull'[{"sample_rate": 0.2}]'. Pour 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). Veuillez noter que vous devez ajouter des apostrophes (') autour de l’objet JSON pour éviter les problèmes d’échappement des guillemets doubles (").DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLEDtrueDD_VERSIONnull1.2.3, 6c44da20, 2020.02.13. Ajoutée avec la version 0.47.0.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>_ENABLED. Exemple pour Laravel : DD_TRACE_LARAVEL_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 |
| PhpRedis | phpredis |
| Predis | predis |
| Slim | slim |
| Symfony | symfony |
| WordPress | wordpress |
| Yii | yii |
| ZendFramework | zendframework |
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 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.
Certains cas ne sont pas couverts par la normalisation automatique appliquée.
| URL (requête GET) | Nom de ressource attendu |
|---|---|
/using/prefix/id123/for/id | GET /using/prefix/?/for/id |
/articles/slug-of-title | GET /articles/? |
/cities/new-york/rivers | GET /cities/?/rivers |
/nested/cities/new-york/rivers | GET /nested/cities/?/rivers |
Deux catégories de scénarios ne sont pas couvertes par la normalisation automatique :
id<nombre>. Dans cette situation, vous pouvez utiliser le paramètre DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX./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_REGEXCe paramètre correspond à une ou plusieurs expressions régulières, au format CSV, 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 chemin /using/prefix/id123/for/id, les expressions régulières sont appliquées à tous les fragments using, prefix, id123, for et id.
| URL | Expression régulière | Nom de ressource attendu |
|---|---|---|
/using/prefix/id123/for/id | ^id\d+$ | GET /using/prefix/?/for/id |
Puisque cette variable est au format CSV, le caractère , (virgule) n’est pas échappé. Il ne peut donc pas être utilisé dans vos expressions régulières.
DD_TRACE_RESOURCE_URI_MAPPING_INCOMING et DD_TRACE_RESOURCE_URI_MAPPING_OUTGOINGCe paramètre correspond à une liste de patterns au format CSV qui peut contenir un wildcard *. Par exemple, si vous ajoutez le pattern cities/*, chaque fois que le fragment cities est trouvé lors de l’analyse d’une URL, le fragment suivant (le cas échéant) est alors remplacé par ?. Les patterns sont appliqués à 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).
open_basedirSi vous utilisez le paramètre open_basedir, /opt/datadog-php doit être ajouté à la liste des répertoires autorisés.
Lorsque l’application est exécutée dans un conteneur Docker, le chemin /proc/self doit également être ajouté à la liste des répertoires autorisés.
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.
Une fois l’installation terminée, redémarrez PHP (PHP-FPM ou le SAPI 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 supprimer le tracer PHP :
98-ddtrace.ini et 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.
Si jamais le traceur PHP entraîne le crash de votre application, généralement en raison d’une erreur de segmentation, il est préférable d’obtenir un core dump et de contacter l’assistance Datadog.
Il peut s’avérer difficile d’obtenir un core dump pour les applications PHP, notamment pour PHP-FPM. Voici quelques conseils pour vous aider à obtenir un core dump :
(SIGSEGV - core dumped), afin de trouver un message confirmant l’enregistrement d’un core dump. Exemple : WARNING: [pool www] child <pid> exited on signal 11 (SIGSEGV - core dumped) after <duration> seconds from start.(SIGSEGV), afin de trouver un message confirmant le non-enregistrement d’un core dump. Exemple : WARNING: [pool www] child <pid> exited on signal 11 (SIGSEGV) after <duration> seconds from start.cat /proc/sys/kernel/core_pattern. La valeur par défaut étant généralement core, un fichier core est donc généré dans le dossier racine Web.Si aucun core dump n’a été généré, vérifiez les configurations suivantes et modifiez-les en fonction de vos besoins :
/proc/sys/kernel/core_pattern contient un chemin comprenant des répertoires imbriqués, assurez-vous que le chemin d’accès avec les répertoires complets existe.root (www-data est généralement utilisé), attribuez à cet utilisateur des autorisations d’écriture dans le répertoire des core dumps./proc/sys/fs/suid_dumpable n’est pas 0. Définissez-la sur 1 ou 2, sauf si vous exécutez le pool de workers PHP-FPM en tant que root. Vérifiez vos options avec votre administrateur système.rlimit_core est adéquate dans la configuration du pool PHP-FPM. Vous pouvez retirer cette limite, avec rlimit_core = unlimited.ulimit est adéquate dans votre système. Vous pouvez retirer cette limite, avec ulimit -c unlimited./proc/sys/*, vous devez effectuer les changements sur la machine du host. Contactez votre administrateur système pour découvrir les différentes options qui s’offrent à vous. Si vous le pouvez, essayez de reproduire le problème dans vos environnements staging ou test.Documentation, liens et articles supplémentaires utiles:
