Tracer des applications PHP

Installation et démarrage

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 RPM (RHEL/Centos 6+, Fedora 20+)
$ rpm -ivh datadog-php-tracer.rpm

# avec le paquet DEB (Debian Jessie+ , Ubuntu 14.04+)
$ 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’interface graphique.

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 :

L’APM PHP prend en charge les SAPI suivantes :

Les 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.

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.

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

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

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

Pour aller plus loin