Activation et configuration du traçage d' PHP

Utilisez l'une des méthodes suivantes pour définir la configuration permettant de désactiver le traçage :

• Fichier de configuration personnalisé
• Instana fichier configuration.yaml d'agent

Pour plus d'informations sur la priorité de configuration, consultez la section « Priorité de configuration pour la désactivation des segments ».

Pour plus d'informations sur la syntaxe de configuration permettant de désactiver le span, consultez la section « Désactivation du traçage ».

La désactivation du traçage pour une catégorie désactive la génération de balises span pour toutes les bibliothèques appartenant à cette catégorie. Consultez la liste suivante des catégories prises en charge 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)

Vous pouvez utiliser tous les identifiants d'instrumentation répertoriés dans le tableau des bibliothèques et frameworks à instrumentation automatique pour configurer des règles de désactivation des spans pour des types de spans spécifiques.

Les règles de désactivation des spans sont appliquées selon l'ordre de priorité suivant, classées de la plus élevée à la plus faible :

1. Applique les règles de désactivation issues du fichier de configuration personnalisé transmis via la INSTANA_CONFIG_PATH variable d'environnement.
2. La désactivation de Span est configurée dans le fichier instana.disabled_instrumentation INI.
3. Règles de désactivation de Span issues du fichier de configuration.yaml l'agent.

Si un moteur d'exécution d' PHP s détecte plusieurs configurations, il n'applique que les règles de désactivation des segments issues de la configuration ayant la priorité la plus élevée.

Par exemple, si un moteur d'exécution PHP dispose des règles de désactivation des spans suivantes, définies via INSTANA_CONFIG_PATH une variable d'environnement :

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

Et ce même exécutable comporte le paramètre INI suivant :

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

Avec cette configuration type, l'outil Tracer d' PHP fonctionne comme suit :

• La traçabilité est désactivée pour toutes les bibliothèques de journalisation.
• La fonction de traçage est désactivée pour toutes les bases de données, à l'exception d' Redis.

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

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

Configurez les traces de pile à l'aide de fichiers de configuration personnalisés, de variables d'environnement ou de la configuration de l'agent d' Instana.

Utilisez l'une des méthodes suivantes pour configurer les traces de pile :

• Fichier de configuration personnalisé
• Variables d'environnement
• Instana fichier d'agent configuration.yaml

Pour plus d'informations sur l'ordre de priorité entre les différentes méthodes de configuration, consultez la section « Ordre de priorité de la configuration pour les traces de pile ».

Utilisez la syntaxe « YAML » pour configurer les paramètres de niveau et de profondeur de la trace de pile.

Utilisez la syntaxe suivante d' YAML s pour définir la configuration de la trace de pile :

# Use 'tracing' section if using custom configuration file
# Use 'com.instana.tracing' section if using agent configuration.yaml file
tracing:
  global:
    stack-trace: <string>
    stack-trace-length: <int>

La configuration de la trace de pile est appliquée selon un ordre de priorité allant des fichiers de configuration personnalisés à la configuration de l'agent.

La configuration de la trace de pile est appliquée selon l'ordre de priorité suivant, classé du plus élevé au plus faible :

1. Configuration de la trace de pile à partir du fichier de configuration personnalisé transmis via la variable d'environnement INSTANA_CONFIG_PATH.
2. La configuration de la trace de pile est définie via les variables d'environnement INSTANA_STACK_TRACE et INSTANA_STACK_TRACE_LENGTH.
3. La longueur de la trace de pile est définie via instana.backtrace_limit un paramètre INI.
4. Configuration de la trace d'appel provenant du fichier de l'agent configuration.yaml .

La priorité est évaluée et appliquée séparément pour le mode de trace de pile et les paramètres de longueur de trace de pile, selon les différentes méthodes de configuration énumérées dans la section précédente.

Configurez les services systemd à l'aide de la directive « PrivateTmp » afin de permettre à PHP Tracer d'accéder à la configuration de YAML.

Si votre exécutable PHP est un service systemd configuré avec la PrivateTmp directive, les processus PHP disposent alors de leur propre répertoire temporaire, isolé du répertoire temporaire du système hôte. Le capteur « PHP » ne peut pas écrire dans le répertoire temporaire du processus; par conséquent, le traceur « PHP » ne peut pas lire la configuration « YAML » dans ces environnements d'exécution « PHP ».

Si la désactivation de PrivateTmp ce paramètre dans le service systemd « PHP » ne répond pas à vos besoins, vous pouvez utiliser à la place un fichier de configuration personnalisé pour définir les règles de désactivation et de filtrage des spans ainsi que les traces de pile, sans avoir à désactiver ce paramètre PrivateTmp dans le service systemd « PHP ».

Sinon, si votre environnement d'exécution d' PHP n'a pas besoin de l'isolation du système de fichiers temporaires offerte par le PrivateTmp paramètre, vous pouvez désactiver PrivateTmp ce dernier pour le service systemd « PHP » en suivant les étapes ci-dessous et continuer à utiliser le fichier de l'agent configuration.yaml pour configurer les règles de désactivation des spans, les règles de filtrage des spans et les traces de pile :

1. Modifiez le fichier de service systemd « PHP » en exécutant la commande suivante :

   sudo systemctl edit <systemd-service-unit-name>
   # systemd service names are usually named like apache2.service, php8.3-fpm.service, etc.,

2. Définissez la PrivateTmp directive sur false dans la [Service] section :

   [Service]
   PrivateTmp=false

3. Recharger la configuration de systemd

   systemctl daemon-reload

4. Redémarrez le service systemd pour que les modifications prennent effet.

Les processus de travail IIS n'ont parfois pas accès au dossier temporaire d' Windows. Cet accès insuffisant au dossier temporaire est dû au fait que l'identité du pool d'applications utilisée pour exécuter les processus de travail ne dispose pas des autorisations de lecture ou d'écriture suffisantes pour accéder à ce dossier. Pour résoudre ce problème d'accès, procédez comme suit :

1. Vérifiez l'identité de votre pool d'applications en exécutant la commande suivante dans le terminal d' PowerShell :

   & $env:windir\system32\inetsrv\appcmd.exe list apppool <your AppPool> /text:processModel.identityType
    

2. Si l'identité n'est pas correcte ApplicationPoolIdentity, exécutez la commande suivante pour la mettre à jour :

   & $env:windir\system32\inetsrv\appcmd.exe set AppPool <your AppPool> -processModel.identityType:ApplicationPoolIdentity
    

3. Redémarrez votre pool d'applications pour que les modifications prennent effet :

   & $env:windir\system32\inetsrv\appcmd.exe recycle apppool <your AppPool>
    

   Le serveur IIS détecte le pool d'applications s'exécutant sous cette identité ApplicationPoolIdentityet crée un utilisateur virtuel portant le nom de votre pool d'applications.

4. Pour accorder au moteur d'exécution d' PHP, c'est-à-dire aux processus de travail IIS, un accès en lecture au <SYSTEM_TEMP> répertoire, utilisez la commande suivante :

   
   icacls "<SYSTEM_TEMP>" /grant "IIS APPPOOL\<your AppPool>:(OI)(CI)R" /T /C
    

Le script de notification s'exécute une fois par instance d' PHP, ce qui signifie qu'il se peut qu'il ne soit pas déclenché pour tous les processus exécutant le même fichier exécutable d' PHP. Pour charger l'extension de traçage « PHP » en mémoire, vous devez vous assurer que votre script redémarre tous les processus exécutés à partir du fichier exécutable « PHP ».

Lorsque ce script est configuré et exécuté avec succès, il remplace le mécanisme par défaut pour les redémarrages automatiques. Contrairement au mécanisme par défaut, le script s'exécute pour n'importe quel SAPI; il peut donc être utilisé pour automatiser les redémarrages dans les environnements CGI d' PHP. 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 illustre un script qui consigne les modifications d'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 s'exécute 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 l' PHP -FPM, vous pouvez envoyer une requête SIGUSR2 afin de le redémarrer en douceur, comme indiqué dans 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. Par conséquent, ce chargement fonctionne même lorsque le processus s'exécute en tant que PID 1 dans le conteneur. Si vous ne pouvez pas ou ne souhaitez pas utiliser l'approche de redémarrage, vous pouvez également créer un instantané de l'instance de 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 conteneur transmis au script pour rechercher le nom de l'image de conteneur. Il valide ensuite le conteneur en cours d'exécution dans une nouvelle image, à laquelle est attribuée une balise indiquant le numéro de version de l'extension PHP. Il arrête ensuite le conteneur d'origine et démarre un conteneur à partir de l'image nouvellement balisée. Bien que cette action relance la procédure d'installation du capteur « PHP », elle ne déclenche pas à nouveau le script de notification, car l'extension est déjà installée.

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

Pour désactiver l'installation automatique de l'extension de traçage d' PHP dans les environnements d'exécution d' PHP nouvellement détectés, définissez tracing.installExtension sur false dans la com.instana.plugin.php section du fichier de configuration.yaml l'agent :

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

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

Si aucune trace n'apparaît dans l'interface utilisateur d' Instana pour les applications PHP, procédez comme suit :

1. Vérifiez les prérequis suivants:

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

2. Rechargez l'extension de traçage d' PHP s en exécutant la commande reload suivante sur le service qui exécute les applications PHP :

   • Pour Apache:

     systemctl reload apache2
      

   • Pour l' PHP -FPM :

     systemctl reload php<version>-fpm
      

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

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

L'extension Tracer d' PHP communique avec le démon PHP via le socket Unix TCP<socket path> et avec l'agent Instana via le port 42699 de TCP/IP. Lorsque SELinux est configuré en mode « enforcing », il empêche l'extension et le démon « PHP » 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 /var/log/audit/audit.log s'il y a des refus silencieux enregistrés pour le démon ` PHP `. Vous pouvez également effectuer un test de fonctionnement en suivant les étapes suivantes :

1. Désactivez temporairement SELinux.
2. Redémarrez le démon « PHP ».

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

• Configurer SELinux pour autoriser la communication d' PHP Tracer : avec SELinux, vous pouvez suivre vos propres règles de sécurité pour configurer une stratégie personnalisée permettant cette communication. Pour plus d'informations sur la création et la modification des politiques SELinux, consultez les liens suivants :

  • CentOS Documentation SELinux
  • RHEL Documentation SELinux

• Configurez SELinux en 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 configurer SELinux en mode permissif, consultez la section « Mode permissif de SELinux ».

• Désactiver SELinux : Instana ne vous recommande pas expressément de désactiver ce logiciel de sécurité. Une approche appropriée et sûre consiste à créer une stratégie SELinux. Toutefois, si vous décidez de désactiver SELinux, consultez la section « Désactiver SELinux ».

Par défaut, la consignation est désactivée. Pour l'activer, reportez-vous aux étapes suivantes.

• Activez la journalisation à l'aide de variables d'environnement.
  1. Pour définir le niveau de journalisation sur « debug », définissez INSTANA_DEBUG sur TRUE ou INSTANA_LOG_LEVEL=4

• Activez la journalisation à l'aide du fichier INI.

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

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

  3. Lorsque vous exécutez le runtime PHP de votre choix, assurez-vous que la sortie contient des informations de journalisation 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 indiqué ici. Si vous ignorez cette étape, aucune journalisation n'aura lieu.

Pour installer manuellement l'extension « PHP Tracing », procédez comme suit :

1. Téléchargez l'extension de traçage « Instana » PHP en procédant 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 affiche 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 « 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 l'option -p 8.4.

      • Pour la version d' OpenSSL, utilisez l'option -s ssl1 pour télécharger l'extension compatible avec OpenSSL 1.1 ou utilisez -s ssl3 pour télécharger l'extension compatible avec 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 -v l'indicateur pour télécharger l'artefact correspondant à une version spécifique. Par exemple, exécutez le script avec -v 4.7.0 pour télécharger l'extension dans sa version finale 4.7.0.

      • Pour afficher 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 CLI d' PHP.

   2. Créez un fichier INI, zzz-instana.ini comme indiqué dans l'exemple suivant, puis enregistrez-le dans le répertoire INI supplémentaire de l'interface CLI d' PHP. 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 la section « Désactivation du traçage d' PHP », vous désactivez complètement le traçage d' PHP, ce qui implique notamment la suppression de l'extension « PHP Tracing » de votre environnement d'exécution PHP.

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

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

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

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

2. Désactivez l'extension de traçage « PHP » dans le fichier de configuration INI de votre serveur PHP. Voir la section « Désactivation de l'extension de traçage d' PHP ».

3. Supprimez le fichier de l'extension « PHP Tracing » de votre système. Voir la section « Suppression du fichier d'extension de traçage d' PHP ».