Activation et configuration du traçage PHP

Pour désactiver le traçage par l'intermédiaire d'une variable d'environnement, définissez la variable d'environnement INSTANA_CONFIG_PATH au chemin absolu du fichier YAML contenant votre configuration.

Par exemple, pour désactiver le suivi de tous les appels de bases de données (à l'exception de MongoDB ) et de tous les cadres de journalisation, copiez le code suivant dans un fichier YAML distinct :

tracing:
  disable:
    - databases: true
    - mongodb: false
    - logging: true
 

Définissez la variable d'environnement INSTANA_CONFIG_PATH au chemin absolu du fichier YAML dans lequel le contenu est placé comme suit :

INSTANA_CONFIG_PATH=<your YAML file>
 

Pour désactiver le traçage via la configuration de l'agent Instana, désactivez les traces dans la section com.instana.tracing.disable du fichier de l'agent configuration.yaml .

Pour désactiver le suivi de tous les appels de base de données (à l'exception de Redis ) et de tous les cadres de journalisation, mettez à jour la section com.instana.tracing dans le fichier configuration.yaml de votre agent, comme indiqué dans l'exemple suivant :

com.instana.tracing:
  disable:
    - databases: true
    - redis: false
    - logging: true
 

Pour plus d'informations sur la personnalisation de la configuration, voir Désactivation du suivi.

La désactivation du traçage pour une catégorie désactive la génération de span pour toutes les bibliothèques de cette catégorie. Voir la liste suivante des catégories supportées par PHP Tracer :

• Bases de données
• infrastructures
• messagerie
• protocoles
• Journalisation
• Création de modèles
• Autres (Aucune clé de catégorie n'est disponible pour les autres)

Les règles de désactivation des travées sont appliquées dans l'ordre de priorité suivant, du plus élevé au plus bas :

1. Désactivation des règles d'épandage à partir du fichier de configuration qui est transmis par la variable d'environnement INSTANA_CONFIG_PATH la variable d'environnement.
2. Désactivation du span configurée dans le paramètre instana.disabled_instrumentation ini.
3. Désactivation des règles d'épandage à partir du fichier de l'agent configuration.yaml .

Cette priorité est appliquée au niveau de l'élément. Si un moteur d'exécution PHP détecte plusieurs configurations dans une fonctionnalité, il applique les règles de désactivation du span à partir de la configuration ayant la priorité la plus élevée. Par exemple, si un moteur d'exécution PHP a les règles suivantes de désactivation de la portée, définies par la variable d'environnement INSTANA_CONFIG_PATH variable d'environnement :

com.instana.tracing:
  disable:
    - logging: true
    - databases: true
    - redis: false
 

Et le même runtime a le paramètre ini suivant :

instana.disabled_instrumentation=24 ; disables redis (16) and curl (8) instrumentations
 

Avec cet exemple de configuration, le traceur PHP fonctionne comme suit :

• Le suivi de toutes les bibliothèques de journalisation est désactivé.
• Le suivi de toutes les bases de données est désactivé, à l'exception de Redis.

Le paramètre instana.disabled_instrumentation ini est ignoré car la variable d'environnement est prioritaire INSTANA_CONFIG_PATH a la priorité sur la variable d'environnement. Par conséquent, tous les instruments qui ne sont pas désactivés par le fichier de configuration spécifié par la variable d'environnement INSTANA_CONFIG_PATH sont activées.

Si les règles de désactivation du span sont définies à la fois par la variable d'environnement INSTANA_CONFIG_PATH et le fichier configuration.yaml de l'agent, les règles du fichier configuration.yaml sont ignorées.

Le capteur PHP détecte tout changement dans le fichier de l'agent configuration.yaml et effectue une copie de la section com.instana.tracing.disable dans un fichier distinct situé à l'adresse <System Temp>/instana-php/instana_span_filer_config.yaml. Le chemin absolu du fichier généré est défini dans le paramètre instana.span_filter_config_file ini afin que PHP Tracer puisse détecter et appliquer toute modification ultérieure du fichier configuration.yaml sans avoir à redémarrer l'exécution de PHP. Par conséquent, le programme d'exécution PHP doit avoir un accès en lecture au dossier temp du système, si vous configurez des règles de désactivation de span par le biais du fichier de l'agent configuration.yaml .

Les sous-sections suivantes fournissent les étapes supplémentaires qui sont nécessaires dans certains environnements pour que l'exécution de PHP ait un accès suffisant au dossier temp du système.

Le script de notification s'exécute une fois par exécution de PHP, ce qui signifie que le script peut ne pas être déclenché pour tous les processus exécutant le même fichier exécutable PHP. Pour charger l'extension PHP Tracing en mémoire, vous devez vous assurer que votre script redémarre tous les processus s'exécutant à partir de ce fichier exécutable PHP.

Lorsque ce script est configuré et exécuté avec succès, il remplace le mécanisme par défaut de redémarrage automatique. Contrairement au mécanisme par défaut, le script est exécuté pour tout SAPI, ce qui permet d'automatiser les redémarrages dans les environnements PHP-CGI. Si vous souhaitez désactiver complètement les redémarrages automatiques, configurez un script vide.

Le capteur PHP définit les variables d'environnement suivantes pour l'exécution du script :

INSTANA_EXT_VERSION_OLD = the version of the tracing extension currently in memory
INSTANA_EXT_VERSION_NEW = the version of the tracing extension after a restart
INSTANA_PID_HOST = the PID of the process on the host, e.g. your Apache, PHP-FPM or PHP-CGI
INSTANA_PID_CONTAINER = the PID the host process has in a container (if applicable)
INSTANA_CONTAINER = the ID/name of the container the process is running in (if applicable)
 

L'exemple suivant montre un script qui enregistre les modifications de l'extension dans un fichier et redémarre Apache :

#!/bin/bash
echo "Found new tracing extension." >> php_update.log;
echo "INSTANA_EXT_VERSION_OLD=$INSTANA_EXT_VERSION_OLD" >> php_update.log;
echo "INSTANA_EXT_VERSION_NEW=$INSTANA_EXT_VERSION_NEW" >> php_update.log;
echo "INSTANA_PID_HOST=$INSTANA_PID_HOST" >> php_update.log;
echo "INSTANA_PID_CONTAINER=$INSTANA_PID_CONTAINER" >> php_update.log;
echo "INSTANA_CONTAINER=$INSTANA_CONTAINER" >> php_update.log;
echo "restarting apache" >> php_update.log;
apachectl -k graceful >> php_update.log;
 

Si votre Apache fonctionne dans un conteneur, remplacez la dernière ligne de l'exemple de script par la ligne suivante :

docker exec $INSTANA_CONTAINER apachectl -k graceful;
 

Pour PHP-FPM, vous pouvez envoyer une adresse SIGUSR2 pour le redémarrer de manière gracieuse, comme le montre l'exemple suivant :

docker exec $INSTANA_CONTAINER kill -USR2 $INSTANA_PID_CONTAINER;
 

Un redémarrage en douceur charge l'extension PHP en mémoire sans redémarrer le processus principal. Ce chargement fonctionne donc même lorsque le processus s'exécute en tant que PID 1 à l'intérieur du conteneur. Si vous ne pouvez ou ne voulez pas utiliser l'approche du redémarrage, vous pouvez également créer un instantané de l'instance du conteneur en cours d'exécution, l'arrêter et ouvrir facilement une nouvelle instance :

#!/bin/bash
IMAGE_HASH=$(docker inspect --format='{{.Config.Image}}' $INSTANA_CONTAINER)
IMAGE_NAME=$(docker images | grep $IMAGE_HASH | awk '{print $1}')
IMAGE_TAG="instana-php-$INSTANA_EXT_VERSION_NEW"
docker commit $INSTANA_CONTAINER $IMAGE_NAME:$IMAGE_TAG &&
docker stop $INSTANA_CONTAINER &&
docker run -d --rm $IMAGE_NAME:$IMAGE_TAG
 

Cette action utilise l'ID du conteneur transmis au script pour trouver le nom de l'image du conteneur. Il commute ensuite le conteneur en cours d'exécution dans une nouvelle image qui est étiquetée avec le nouveau numéro de version de l'extension PHP. Il arrête alors le conteneur d'origine et démarre un conteneur à partir de l'image nouvellement étiquetée. Bien que cette action déclenche à nouveau la routine d'installation dans le capteur PHP, elle ne déclenche pas à nouveau le script de notification car l'extension est déjà installée.

Ces exemples supposent que vous utilisez Docker comme moteur de conteneur. Mais comme le script shell déclenché est entièrement sous votre contrôle, vous pouvez y mettre toute la logique dont vous avez besoin pour que les redémarrages automatiques fonctionnent dans votre configuration.

Pour désactiver l'installation automatique de l'extension PHP Tracing dans les environnements d'exécution PHP nouvellement détectés, remplacez tracing.installExtension par false dans la section com.instana.plugin.php dans le fichier de l'agent configuration.yaml :

com.instana.plugin.php:
  tracing:
    enabled: true
    installExtension: false
 

Si vous utilisez Plesk, vous devez exécuter plesk bin php_handler --reread.

Si vous ne voyez pas de traces apparaître dans l'interface utilisateur Instana pour les applications PHP, effectuez les étapes suivantes :

1. Vérifiez les conditions préalables suivantes :

   • Le capteur PHP est activé. Pour plus d'informations, voir Désactiver le traçage PHP.
   • L'extension binaire PHP Tracing est disponible. Pour plus d'informations, voir Désactiver l'extension PHP Tracing.
   • L'extension PHP Tracing est activée dans le fichier de configuration de l'agent. Pour plus d'informations, voir Suppression du fichier d'extension PHP Tracing.

2. Rechargez l'extension PHP Tracing en exécutant la commande suivante reload sur le service qui exécute les applications PHP :

   • Pour Apache :

     systemctl reload apache2
      

   • Pour PHP-FPM :

     systemctl reload php<version>-fpm
      

     Remplacez <version> dans la commande reload par la version réelle installée dans le système.

Si vous ne voyez toujours pas de traces dans l'interface utilisateur d'Instana et que votre système d'exploitation inclut SELinux par défaut ou l'ajoute à l'environnement à des fins de sécurité, SELinux peut être à l'origine du problème.

L'extension PHP Tracer communique avec le démon PHP sur le socket Unix TCP <socket path> et avec l'agent Instana sur le port TCP/IP 42699. Lorsque SELinux est configuré en mode "enforcing", il empêche l'extension PHP et le démon de communiquer entre eux, à moins que SELinux ne soit configuré pour l'autoriser.

Pour vérifier si SELinux est à l'origine du problème, vérifiez sur /var/log/audit/audit.log les dénis silencieux enregistrés pour le démon PHP. Vous pouvez également effectuer un test de fumée en suivant les étapes suivantes :

1. Désactiver temporairement SELinux.
2. Redémarrer le démon PHP.

Si SELinux est identifié comme la cause du problème, vous pouvez le résoudre en utilisant l'une des options suivantes :

• Configurez SELinux pour permettre à PHP Tracer de communiquer : Avec SELinux, vous pouvez suivre vos propres politiques de sécurité et configurer une politique personnalisée pour permettre la communication. Pour plus d'informations sur la création et la modification de la politique SELinux, voir les liens suivants :

  • CentOS Documentation SELinux
  • Documentation SELinux RHEL

• Réglez SELinux sur le mode permissif : Dans ce mode, vos services peuvent fonctionner sans restrictions. Vous pouvez rétablir les paramètres par défaut en redémarrant le serveur. Pour mettre SELinux en mode permissif, voir SELinux mode permissif.

• Désactiver SELinux : Instana ne vous encourage pas activement à désactiver les logiciels de sécurité. Une approche correcte et sûre consiste à créer une politique SELinux. Toutefois, si vous décidez de désactiver SELinux, consultez la section Désactiver Linux.

Par défaut, la journalisation est désactivée. Pour l'activer, suivez les étapes suivantes.

• Activer la journalisation en utilisant des variables d'environnement.

1. Pour définir le niveau de journalisation sur débogage, définissez INSTANA_DEBUG sur TRUE ou INSTANA_LOG_LEVEL=4

• Activer la journalisation en utilisant le fichier INI.

1. Localisez un fichier nommé zzz-instana.ini dans le répertoire scan de votre installation PHP. Par exemple, l'exécution de php --ini | grep zzz-instana.ini ou php-fpm<version> -i | grep zzz-instana.ini révèle son emplacement.

2. Ajouter la ligne instana.log_level=4 à zzz-instana.ini.

3. Lorsque vous exécutez le moteur d'exécution PHP de votre choix, assurez-vous que la journalisation est présente dans la sortie et que l'extension est activée. Par exemple, vous pouvez exécuter php --ri instana ou php-fpm<version> -i | grep instana pour vérifier.

   Exemple :

   [instana.INFO] Initializing, logging at level 4
    

4. Rechargez l'extension de traçage PHP comme décrit ici. Si vous sautez cette étape, il n'y aura pas d'enregistrement.

Les journaux sont acheminés vers le moteur d'exécution PHP dans lequel l'extension de traçage PHP est installée. De ce fait, sa localisation précise dépend fortement de sa configuration. Les emplacements habituels sont /var/log/apache2/error.log pour Apache2 et /var/log/php<version>-fpm.log pour PHP-FPM.

Pour installer manuellement l'extension PHP Tracing, suivez les étapes suivantes :

1. Téléchargez l'extension Instana PHP Tracing comme suit :

   1. Téléchargez le script shell à partir du dépôt suivant :

      https://artifact-public.instana.io/artifactory/shared/com/instana/php/instana-ext-download-script/php-instana-ext-download-script.sh
       

   2. Exécutez le script shell pour télécharger l'extension adaptée à votre environnement. La commande suivante montre les options disponibles :

      ./php-instana-ext-download-script.sh -a <aarch64/x86_64> -l <musl/glibc> -p <PHP version> -t <NTS/ZTS> -d <serverless/native> -s <OpenSSL version> -v <Instana extension version>
       

      • Pour la version de PHP, indiquez les numéros de version majeure et mineure. Par exemple, pour télécharger l'extension Instana pour PHP 8.4.12, exécutez le script shell avec le drapeau -p 8.4.

      • Pour la version OpenSSL, utilisez l'option -s ssl1 pour télécharger l'extension qui supporte OpenSSL 1.1 ou utilisez -s ssl3 pour télécharger l'extension qui supporte OpenSSL 3.x.

      • Pour la version de l'extension Instana, la valeur par défaut est release, ce qui permet de télécharger la dernière version disponible. Utilisez l'option -v pour télécharger l'artefact pour une version spécifique. Par exemple, exécutez le script avec -v 4.7.0 pour télécharger l'extension avec la version 4.7.0.

      • Pour voir toutes les options disponibles pour le script, exécutez la commande suivante :

        ./php-instana-ext-download-script.sh
         

2. Installez l'extension comme suit :

   1. Déplacez le fichier .so téléchargé dans le répertoire de l'extension PHP CLI.

   2. Créez un fichier INI, zzz-instana.ini, comme le montre l'exemple suivant, et enregistrez-le dans le répertoire INI additionnel de PHP CLI. Remplacez <hostIP> par l'adresse IP de l'hôte de l'agent Instana afin que l'agent soit accessible depuis l'environnement PHP.

      ; this file was automatically generated by Instana
      ;
      ; any changes made to this file are expected to be overwritten when
      ; a new version of the Instana PHP Tracer extension is installed
      [instana]
      extension=<php cli extension dir path where extension.so file is placed>
      instana.socket=<hostIP>:16816
      instana.agent_endpoint=http://<hostIP>:42699
      instana.use_agent_endpoint=1
      instana.auto_profile_socket=tcp://<hostIP>:42699
      instana.enable_auto_profile=0
      instana.secrets_matcher=contains-ignore-case
      instana.secrets_list="key,pass,secret"
      instana.extra_http_headers=
      instana.pid_in_root_namespace=<pid of PHP process in hostnamespace>
      instana.enable_cli=1
       

En suivant les étapes décrites dans Désactivation du traçage PHP, vous désactivez complètement le traçage PHP, y compris la suppression de l'extension PHP Tracing de votre moteur d'exécution PHP.

Si vous rencontrez des erreurs au cours de cette procédure et que vous souhaitez désactiver manuellement le suivi de PHP et désinstaller l'extension PHP Tracing, procédez comme suit :

1. Assurez-vous que le traçage PHP est désactivé dans le fichier de l'agent configuration.yaml comme suit :

   com.instana.plugin.php:
     tracing:
       enabled: false
    

   Cette configuration empêche le capteur PHP de réinstaller à nouveau l'extension PHP Tracing.

2. Désactivez l'extension PHP Tracing dans votre configuration PHP INI. Voir Désactivation de l'extension PHP Tracing.

3. Supprimez le fichier d'extension PHP Tracing de votre système. Voir Suppression du fichier d'extension PHP Tracing.