La version minimale requise de PHP pour la dernière version de dd-trace-php est PHP 7. Si vous utilisez PHP 5, vous pouvez toujours utiliser le traceur PHP jusqu’à la version 0.99. PHP 5 est en fin de vie depuis la version 1.0 de la bibliothèque PHP.
Pour obtenir la liste complète des frameworks et versions PHP pris en charge (y compris les anciennes versions et les versions de maintenance), consultez la page relative aux exigences de compatibilité.
Remarque : Seul APM est pris en charge sur Windows. Ne pas utiliser les --enable-appsec et --enable-profiling drapeaux lors du traçage des applications PHP sur Windows.
Cette commande installe l’extension sur tous les binaires PHP trouvés sur l’hôte ou dans le conteneur. Si --php-bin est omis, l’installateur s’exécute en mode interactif et demande à l’utilisateur de sélectionner les binaires à installer. La valeur de --php-bin peut être un chemin vers un binaire spécifique si dd-trace-php doit être installé uniquement sur ce binaire.
Redémarrez PHP (PHP-FPM ou le SAPI Apache) et visitez un point de terminaison activé pour le traçage de votre application. Pour voir les traces générées, allez à la page des traces APM.
Lorsque vous ne spécifiez pas --enable-appsec, l’extension AppSec se charge brièvement au démarrage et n’est pas activée par défaut. Elle court-circuite immédiatement, entraînant une surcharge de performance négligeable.
Il peut falloir quelques minutes avant que les traces n'apparaissent dans l'interface utilisateur. Si les traces n'apparaissent toujours pas après quelques minutes, créez un phpinfo() page depuis la machine hôte et faites défiler vers le bas jusqu'au `ddtrace`. Les vérifications de diagnostic échouées apparaissent dans cette section pour aider à identifier d'éventuels problèmes.
Apache ZTS :
Si le binaire PHP CLI est construit en tant que NTS (non thread-safe), tandis qu'Apache utilise une version ZTS (Zend thread-safe) de PHP, vous devez modifier manuellement le chargement de l'extension pour le binaire ZTS. Exécution /path/to/php-zts --ini pour trouver où se trouve le fichier de Datadog, .ini ajoutez ensuite le -zts suffixe du nom de fichier. Par exemple, à partir de extension=ddtrace-20210902.so par extension=ddtrace-20210902-zts.so.
SELinux :
Si les politiques SELinux httpd sont configurées sur l'hôte, la fonctionnalité du SDK peut être limitée, à moins que l'écriture et l'exécution de fichiers temporaires ne soient explicitement autorisées dans la configuration SELinux :
Le traçage est automatiquement activé par défaut. Une fois l’extension installée, ddtrace trace votre application et envoie les traces à l’Agent.
Datadog prend en charge tous les frameworks web dès le départ. L’instrumentation automatique fonctionne en modifiant l’exécution de PHP pour envelopper 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 :
Temps d’exécution de la méthode
Données de trace pertinentes, telles que l’URL et les codes de réponse d’état pour les requêtes web ou les requêtes SQL pour l’accès à la base de données
Exceptions non gérées, y compris les traces de pile si disponibles
Un nombre total de traces (par exemple, des requêtes web) circulant dans le système
Configuration
Si nécessaire, configurez le SDK pour envoyer des données de télémétrie de performance d’application comme vous le souhaitez, y compris la configuration du Tagging de Service Unifié. Consultez Configuration de la bibliothèque pour plus de détails.
Une fois l’installation terminée, redémarrez PHP (PHP-FPM ou le SAPI Apache).
Remarque : Si vous utilisez la mise en cache de deuxième niveau dans OPcache en définissant le paramètre opcache.file_cache, supprimez le dossier de cache.
Suppression
Pour supprimer le tracer PHP :
Pour php-fpm, arrêtez le service php-fpm, sinon arrêtez le serveur web Apache.
Dissociez les fichiers 98-ddtrace.ini et 99-ddtrace-custom.ini de votre dossier de configuration PHP.
Pour php-fpm, redémarrez le service php-fpm, sinon redémarrez le serveur web Apache.
Remarque : Si vous utilisez la mise en cache de deuxième niveau dans OPcache en définissant le paramètre opcache.file_cache, supprimez le dossier de cache.
Résolution des problèmes d’un plantage d’application
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 ou une trace Valgrind et de contacter l’assistance Datadog.
Installez les symboles de débogage
Pour que les core dumps soient lisibles, les symboles de débogage pour les binaires PHP doivent être installés sur le système qui exécute PHP.
Pour vérifier si les symboles de débogage sont installés pour PHP ou PHP-FPM, utilisez gdb.
Installez gdb :
apt|yum install -y gdb
Exécutez gdb avec le binaire d’intérêt. Par exemple, pour PHP-FPM :
gdb php-fpm
Si la sortie de gdb contient une ligne similaire au texte ci-dessous, alors les symboles de débogage sont déjà installés.
...
Reading symbols from php-fpm...Reading symbols from /usr/lib/debug/path/to/some/file.debug...done.
...
Si la sortie gdb contient une ligne similaire au texte ci-dessous, alors les symboles de débogage doivent être installés :
...
Reading symbols from php-fpm...(no debugging symbols found)...done.
...
Centos
Installez le paquet yum-utils qui fournit le programme debuginfo-install :
yum install -y yum-utils
Trouvez le nom du package pour vos binaires PHP, il peut varier en fonction de la méthode d’installation de PHP :
yum list installed | grep php
Installez les symboles de débogage. Par exemple pour le paquet php-fpm :
debuginfo-install -y php-fpm
Note : Si le dépôt qui fournit les binaires PHP n’est pas activé par défaut, il peut être activé lors de l’exécution de la commande debuginfo-install. Exemple :
# ... leave here all the pre-existing packages
# add a `deb` deb http://deb.debian.org/debian-debug/ $RELEASE-debug main
# For example for buster
debhttp://deb.debian.org/debian-debug/buster-debugmain
Mettez à jour apt :
apt update
Essayez d’abord les noms de paquets canoniques pour les symboles de débogage. Par exemple, si le nom du paquet est php7.2-fpm, essayez :
apt install -y php7.2-fpm-dbgsym
# if the above does not work
apt install -y php7.2-fpm-dbg
Si les symboles de débogage ne peuvent pas être trouvés, utilisez l’outil utilitaire find-dbgsym-packages. Installez le binaire :
apt install -y debian-goodies
Tentez de trouver les symboles de débogage soit depuis le chemin complet vers le binaire, soit depuis l’id d’un processus en cours d’exécution :
find-dbgsym-packages /usr/sbin/php-fpm7.2
Installez le nom du package résultant, si trouvé :
Si PHP a été installé à partir de ppa:ondrej/php, éditez le fichier source apt /etc/apt/sources.list.d/ondrej-*.list en ajoutant le composant main/debug.
Avant :
deb http://ppa.launchpad.net/ondrej/php/ubuntu <version> main
Après :
deb http://ppa.launchpad.net/ondrej/php/ubuntu <version> main main/debug
Mettez à jour et installez les symboles de débogage. Par exemple, pour PHP-FPM 7.2 :
apt update
apt install -y php7.2-fpm-dbgsym
PHP installé à partir d’un autre paquet
Trouvez le nom du package pour vos binaires PHP, il peut varier en fonction de la méthode d’installation de PHP :
apt list --installed | grep php
Remarque : Dans certains cas, php-fpm peut être un méta-paquet qui fait référence au véritable paquet, par exemple php7.2-fpm dans le cas de PHP-FPM 7.2. Dans ce cas, le nom du paquet est ce dernier.
Essayez d’abord les noms de paquets canoniques pour les symboles de débogage. Par exemple, si le nom du paquet est php7.2-fpm essayez :
apt install -y php7.2-fpm-dbgsym
# if the above does not work
apt install -y php7.2-fpm-dbg
Si les paquets -dbg et -dbgsym ne peuvent pas être trouvés, activez les dépôts ddebs. Des informations détaillées sur la façon d’installer les symboles de débogage à partir de ddebs peuvent être trouvées dans la documentation d’Ubuntu.
Par exemple, pour Ubuntu 18.04+, activez le dépôt ddebs :
echo "deb http://ddebs.ubuntu.com $(lsb_release -cs) main restricted universe multiverse" | tee -a /etc/apt/sources.list.d/ddebs.list
echo "deb http://ddebs.ubuntu.com $(lsb_release -cs)-updates main restricted universe multiverse" | tee -a /etc/apt/sources.list.d/ddebs.list
Obtenir un vidage mémoire pour les applications PHP peut être délicat, surtout sur PHP-FPM. Voici quelques conseils pour vous aider à obtenir un vidage mémoire :
Déterminez si PHP-FPM a généré un vidage mémoire en consultant le journal des erreurs de l’application :
Recherchez (SIGSEGV - core dumped) car un message comme celui-ci signifie qu’il a été vidé : WARNING: [pool www] child <pid> exited on signal 11 (SIGSEGV - core dumped) after <duration> seconds from start.
Recherchez (SIGSEGV) car un message comme celui-ci indique que le cœur n’a pas été vidé : WARNING: [pool www] child <pid> exited on signal 11 (SIGSEGV) after <duration> seconds from start.
Localisez le vidage mémoire en exécutant cat /proc/sys/kernel/core_pattern. La valeur par défaut est généralement core, ce qui signifie qu’un fichier nommé core sera généré dans le dossier racine du web.
Si aucun vidage système n’a été généré, vérifiez les configurations suivantes et modifiez-les en fonction de vos besoins :
Si /proc/sys/kernel/core_pattern contient un chemin incluant des répertoires imbriqués, assurez-vous que le chemin complet du répertoire existe.
Si l’utilisateur exécutant les travailleurs de pool PHP-FPM est autre que root (un nom d’utilisateur courant est www-data), donnez à cet utilisateur des permissions d’écriture dans le répertoire des vidages mémoire.
Assurez-vous que la valeur de /proc/sys/fs/suid_dumpable n’est pas 0. Réglez-le sur 1 ou 2 à moins que vous n’exécutiez le pool de travailleurs PHP-FPM en tant que root. Vérifiez vos options avec votre administrateur système.
Assurez-vous d’avoir un rlimit_core approprié dans la section de configuration du pool PHP-FPM. Vous pouvez le définir sur illimité : rlimit_core = unlimited.
Assurez-vous d’avoir un ulimit approprié configuré dans votre système. Vous pouvez le définir sur illimité : ulimit -c unlimited.
Si votre application s’exécute dans un conteneur Docker, les modifications de /proc/sys/* doivent être effectuées sur la machine hôte. Contactez votre administrateur système pour connaître les options qui s’offrent à vous. Si vous le pouvez, essayez de recréer le problème dans vos environnements de test ou de staging.
Obtenir un vidage mémoire depuis un conteneur Docker
Utilisez les informations ci-dessous pour savoir comment obtenir un core dump dans un conteneur Docker :
Le conteneur Docker doit s’exécuter en tant que conteneur privilégié, et la valeur ulimit pour les fichiers de vidage mémoire doit être définie à son maximum comme indiqué dans les exemples ci-dessous.
Si vous utilisez la commande docker run, ajoutez les arguments --privileged et --ulimit core=99999999999
Si vous utilisez docker compose, ajoutez ce qui suit au fichier docker-compose.yml :
privileged:trueulimits:core:99999999999
Lors de l’exécution du conteneur (et avant de démarrer l’application PHP), vous devez exécuter les commandes suivantes :
Pour obtenir plus de détails sur le crash, exécutez l’application avec Valgrind. Contrairement aux vidages mémoire, cette approche fonctionne toujours dans un conteneur non privilégié.
Remarque : Une application qui s'exécute via Valgrind est de plusieurs ordres de grandeur plus lente que lorsqu'elle s'exécute nativement. Cette méthode est recommandée pour les environnements non productifs.
Installez Valgrind avec votre gestionnaire de paquets. Exécutez l’application avec Valgrind de manière à générer quelques requêtes.
La trace Valgrind résultante est imprimée par défaut sur l’erreur standard, suivez la documentation officielle pour imprimer sur une cible différente. La sortie attendue est similaire à l’exemple ci-dessous pour un processus PHP-FPM :
Certains problèmes sont causés par des facteurs externes, il peut donc être utile d’avoir un strace.
Remarque : Une application qui s'exécute via strace est plusieurs ordres de grandeur plus lente que lorsqu'elle s'exécute nativement. Cette méthode est recommandée pour les environnements non productifs.
Installez strace avec votre gestionnaire de paquets. Lors de la génération d’un strace à envoyer au support Datadog, assurez-vous d’utiliser l’option -f pour suivre les processus enfants.
