Aktivieren und Konfigurieren von PHP-Tracing

Um das Tracing über die Umgebungsvariable zu deaktivieren, setzen Sie die Umgebungsvariable INSTANA_CONFIG_PATH auf den absoluten Pfad der YAML-Datei mit Ihrer Konfiguration.

Um z.B. das Tracing für alle Datenbankaufrufe (außer MongoDB ) und alle Logging-Frameworks zu deaktivieren, kopieren Sie den folgenden Code in eine separate YAML-Datei:

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

Setzen Sie die Umgebungsvariable INSTANA_CONFIG_PATH auf den absoluten Pfad der YAML-Datei, in der der Inhalt abgelegt wird, wie folgt:

INSTANA_CONFIG_PATH=<your YAML file>
 

Um die Ablaufverfolgung über die Konfiguration des Instana-Agenten zu deaktivieren, deaktivieren Sie die Ablaufverfolgung im Abschnitt com.instana.tracing.disable in der Datei configuration.yaml des Agenten.

Um die Ablaufverfolgung für alle Datenbankaufrufe (außer Redis ) und alle Protokollierungs-Frameworks zu deaktivieren, aktualisieren Sie den Abschnitt com.instana.tracing in der Datei configuration.yaml Ihres Agenten wie im folgenden Beispiel gezeigt:

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

Weitere Informationen zum Anpassen der Konfiguration finden Sie unter Deaktivieren der Ablaufverfolgung.

Wenn Sie die Ablaufverfolgung für eine Kategorie deaktivieren, wird die Erzeugung von Spannen für alle Bibliotheken dieser Kategorie ausgeschaltet. Siehe die folgende Liste der von PHP Tracer unterstützten Kategorien:

• Datenbanken
• frameworks
• Nachrichtenübertragung
• Protokolle
• Protokollierung
• Erstellung anhand einer Vorlage
• Andere (für andere ist kein Kategorienschlüssel verfügbar)

Die Regeln für die Sperrung von Bereichen werden in der folgenden Reihenfolge angewendet, von der höchsten zur niedrigsten:

1. Spanne Deaktivierungsregeln aus der Konfigurationsdatei, die über die INSTANA_CONFIG_PATH umgebungsvariable übergeben wird.
2. Deaktivierung der Spanne, konfiguriert in der Einstellung instana.disabled_instrumentation ini.
3. Spanne Deaktivierungsregeln aus der Datei configuration.yaml des Agenten.

Dieser Vorrang wird auf Merkmalsebene durchgesetzt. Wenn eine PHP-Laufzeitumgebung mehrere Konfigurationen in einem Merkmal erkennt, wendet sie die Regeln zum Deaktivieren der Spanne aus der Konfiguration mit der höchsten Priorität an. Wenn zum Beispiel eine PHP-Laufzeitumgebung die folgenden Regeln zum Deaktivieren der Spanne über die INSTANA_CONFIG_PATH umgebungsvariable festgelegt sind:

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

Und dieselbe Runtime hat die folgende Ini-Einstellung:

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

Mit dieser Beispielkonfiguration funktioniert der PHP Tracer wie folgt:

• Die Ablaufverfolgung für alle Protokollierungsbibliotheken ist deaktiviert.
• Die Ablaufverfolgung ist für alle Datenbanken außer für Redis deaktiviert.

Die Einstellung instana.disabled_instrumentation ini wird ignoriert, da die INSTANA_CONFIG_PATH umgebungsvariable Vorrang hat. Daher werden alle Instrumentierungen, die nicht durch die Konfigurationsdatei deaktiviert sind, die durch die INSTANA_CONFIG_PATH umgebungsvariable angegeben sind, aktiviert.

Wenn die Regeln zum Deaktivieren von Bereichen sowohl über die INSTANA_CONFIG_PATH umgebungsvariable und die Datei configuration.yaml des Agenten festgelegt werden, werden die Regeln aus der Datei configuration.yaml ignoriert.

Der PHP-Sensor erkennt alle Änderungen in der Datei configuration.yaml des Agenten und erstellt eine Kopie des Abschnitts com.instana.tracing.disable in eine separate Datei, die sich unter <System Temp>/instana-php/instana_span_filer_config.yaml befindet. Der absolute Pfad der generierten Datei wird auf die Einstellung instana.span_filter_config_file ini gesetzt, so dass PHP Tracer spätere Änderungen an der Datei configuration.yaml ohne Neustart der PHP-Laufzeit erkennen und übernehmen kann. Daher muss die PHP-Laufzeitumgebung Lesezugriff auf den Temp-Ordner des Systems haben, wenn Sie Regeln zum Deaktivieren der Spanne über die Datei configuration.yaml des Agenten konfigurieren.

Die folgenden Unterabschnitte beschreiben die zusätzlichen Schritte, die in einigen Umgebungen erforderlich sind, damit die PHP-Laufzeitumgebung ausreichenden Zugriff auf den Temp-Ordner des Systems hat.

Das Benachrichtigungsskript wird einmal pro PHP-Laufzeit ausgeführt, was bedeutet, dass das Skript möglicherweise nicht für alle Prozesse ausgelöst wird, die dieselbe ausführbare PHP-Datei ausführen. Um die PHP-Tracing-Erweiterung in den Speicher zu laden, müssen Sie sicherstellen, dass Ihr Skript alle Prozesse neu startet, die von dieser ausführbaren PHP-Datei aus laufen.

Wenn dieses Skript konfiguriert und erfolgreich ausgeführt wird, setzt es den Standardmechanismus für automatische Neustarts außer Kraft. Im Gegensatz zum Standardmechanismus wird das Skript für jedes SAPI ausgeführt, so dass es zur Automatisierung von Neustarts für PHP-CGI-Umgebungen verwendet werden kann. Wenn Sie den automatischen Neustart vollständig deaktivieren möchten, konfigurieren Sie ein leeres Skript.

Der PHP-Sensor setzt die folgenden Umgebungsvariablen für die Skriptausführung:

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)
 

Das folgende Beispiel zeigt ein Skript, das Erweiterungsänderungen in einer Datei protokolliert und Apache neu startet:

#!/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;
 

Wenn Ihr Apache innerhalb eines Containers läuft, ersetzen Sie die letzte Zeile im Beispielskript durch die folgende Zeile:

docker exec $INSTANA_CONTAINER apachectl -k graceful;
 

Für PHP-FPM können Sie eine SIGUSR2 senden, um ihn ordnungsgemäß neu zu starten, wie im folgenden Beispiel gezeigt:

docker exec $INSTANA_CONTAINER kill -USR2 $INSTANA_PID_CONTAINER;
 

Bei einem ordnungsgemäßen Neustart wird die PHP-Erweiterung in den Speicher geladen, ohne dass der Master-Prozess neu gestartet wird. Dieses Laden funktioniert also auch dann, wenn der Prozess als PID 1 innerhalb des Containers läuft. Wenn Sie den Neustart nicht durchführen können oder wollen, können Sie auch einen Snapshot der laufenden Container-Instanz erstellen, diese stoppen und einfach eine neue Instanz öffnen:

#!/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
 

Diese Aktion verwendet die an das Skript übergebene Container-ID, um den Namen des Container-Bildes zu ermitteln. Anschließend wird der laufende Container in ein neues Image überführt, das mit der neuen Versionsnummer der PHP-Erweiterung versehen wird. Anschließend wird der ursprüngliche Container gestoppt und ein Container mit dem neu markierten Bild gestartet. Diese Aktion löst zwar erneut die Installationsroutine im PHP-Sensor aus, aber nicht erneut das Benachrichtigungsskript, da die Erweiterung bereits installiert ist.

Diese Beispiele gehen davon aus, dass Sie Docker als Container-Engine verwenden. Da das getriggerte Shell-Skript jedoch vollständig unter Ihrer Kontrolle steht, können Sie jede beliebige Logik einbauen, die Sie benötigen, damit der automatische Neustart für Ihre Einrichtung funktioniert.

Um die automatische Installation der PHP-Tracing-Erweiterung in neu erkannten PHP-Laufzeiten zu deaktivieren, setzen Sie tracing.installExtension auf false im Abschnitt com.instana.plugin.php abschnitt in der Datei configuration.yaml des Agenten:

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

Wenn Sie Plesk verwenden, müssen Sie plesk bin php_handler --reread ausführen.

Wenn Sie keine Spuren in der Instana-Benutzeroberfläche für PHP-Anwendungen sehen, führen Sie die folgenden Schritte aus:

1. Überprüfen Sie die folgenden Voraussetzungen:

   • Der PHP-Sensor ist aktiviert. Weitere Informationen finden Sie unter Deaktivieren des PHP-Tracing.
   • Das PHP Tracing Extension Binary ist verfügbar. Weitere Informationen finden Sie unter Deaktivieren der PHP-Tracing-Erweiterung.
   • Die PHP-Tracing-Erweiterung ist in der Konfigurationsdatei des Agenten aktiviert. Weitere Informationen finden Sie unter Entfernen der PHP-Tracing-Erweiterungsdatei.

2. Laden Sie die PHP-Tracing-Erweiterung neu, indem Sie den folgenden reload auf dem Dienst, der PHP-Anwendungen ausführt:

   • Für Apache :

     systemctl reload apache2
      

   • Für PHP-FPM:

     systemctl reload php<version>-fpm
      

     Ersetzen Sie <Version> im reload-Befehl durch die aktuelle Version, die im System installiert ist.

Wenn Sie immer noch keine Spuren in der Instana-Benutzeroberfläche sehen und Ihr Betriebssystem SELinux standardmäßig enthält oder es zu Sicherheitszwecken zur Umgebung hinzufügt, könnte SELinux für das Problem verantwortlich sein.

Die PHP-Tracer-Erweiterung kommuniziert mit dem PHP-Daemon über den Unix-TCP-Socket <socket path> und mit dem Instana-Agenten über den TCP/IP-Port 42699. Wenn SELinux auf den erzwingenden Modus eingestellt ist, verhindert es, dass die PHP-Erweiterung und der Daemon miteinander kommunizieren, es sei denn, SELinux ist so konfiguriert, dass es dies erlaubt.

Um zu überprüfen, ob SELinux für das Problem verantwortlich ist, überprüfen Sie /var/log/audit/audit.log auf alle stillen Verweigerungen, die für den PHP-Daemon aufgezeichnet wurden. Alternativ können Sie auch einen Rauchtest durchführen, indem Sie die folgenden Schritte ausführen:

1. Deaktivieren Sie SELinux vorübergehend.
2. Starten Sie den PHP-Daemon neu.

Wenn SELinux als Ursache für das Problem identifiziert wird, können Sie es mit einer der folgenden Optionen beheben:

• Konfigurieren Sie SELinux, um PHP Tracer die Kommunikation zu ermöglichen: Mit SELinux können Sie Ihre eigenen Sicherheitsrichtlinien befolgen und eine benutzerdefinierte Richtlinie konfigurieren, um die Kommunikation zu ermöglichen. Weitere Informationen zum Erstellen und Ändern von SELinux-Richtlinien finden Sie unter den folgenden Links:

  • CentOS SELinux-Dokumentation
  • RHEL SELinux-Dokumentation

• Setzen Sie SELinux in den permissiven Modus: In diesem Modus können Ihre Dienste ohne Einschränkungen arbeiten. Sie können die Standardeinstellung wiederherstellen, indem Sie den Server neu starten. Um SELinux in den permissiven Modus zu versetzen, siehe SELinux permissiver Modus.

• Deaktivieren Sie SELinux: Instana ermutigt Sie nicht aktiv dazu, Sicherheitssoftware zu deaktivieren. Ein richtiger und sicherer Ansatz ist die Erstellung einer SELinux-Richtlinie. Wenn Sie sich jedoch entscheiden, SELinux zu deaktivieren, lesen Sie den Abschnitt Deaktivieren Linux.

In der Standardeinstellung ist die Protokollierung ausgeschaltet. Um sie zu aktivieren, führen Sie die folgenden Schritte aus.

• Aktivieren Sie die Protokollierung mit Hilfe von Umgebungsvariablen.

1. Um die Protokollstufe auf Debug zu setzen, setzen Sie INSTANA_DEBUG auf TRUE oder INSTANA_LOG_LEVEL=4

• Aktivieren Sie die Protokollierung mit Hilfe der INI-Datei.

1. Suchen Sie im Scan-Verzeichnis Ihrer PHP-Installation eine Datei namens zzz-instana.ini . Wenn Sie z. B. php --ini | grep zzz-instana.ini oder php-fpm<version> -i | grep zzz-instana.ini aufrufen, sehen Sie, wo er sich befindet.

2. Fügen Sie die Zeile instana.log_level=4 zu zzz-instana.ini hinzu.

3. Wenn Sie die PHP-Laufzeitumgebung Ihrer Wahl ausführen, vergewissern Sie sich, dass eine gewisse Protokollierung in der Ausgabe vorhanden und die Erweiterung aktiviert ist. Sie können zum Beispiel php --ri instana oder php-fpm<version> -i | grep instana ausführen, um dies zu überprüfen.

   Beispiel:

   [instana.INFO] Initializing, logging at level 4
    

4. Laden Sie die PHP-Tracing-Erweiterung wie hier beschrieben neu. Wird dieser Schritt übersprungen, erfolgt keine Protokollierung.

Die Protokolle werden in die PHP-Laufzeitumgebung geleitet, in der die PHP-Tracing-Erweiterung installiert ist. Aus diesem Grund hängt seine genaue Position stark von seiner Konfiguration ab. Übliche Speicherorte sind /var/log/apache2/error.log für Apache2 und /var/log/php<version>-fpm.log für PHP-FPM.

Um die PHP-Tracing-Erweiterung manuell zu installieren, führen Sie die folgenden Schritte aus:

1. Laden Sie die Instana PHP Tracing-Erweiterung wie folgt herunter:

   1. Laden Sie das Shell-Skript aus dem folgenden Repository herunter:

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

   2. Führen Sie das Shell-Skript aus, um die für Ihre Umgebung geeignete Erweiterung herunterzuladen. Der folgende Befehl zeigt die verfügbaren Optionen:

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

      • Geben Sie für die PHP-Version die Major- und Minor-Versionsnummern an. Um zum Beispiel die Instana-Erweiterung für PHP 8.4.12 herunterzuladen, führen Sie das Shell-Skript mit dem Flag -p 8.4 aus.

      • Für die Version OpenSSL verwenden Sie die Option -s ssl1 , um die Erweiterung herunterzuladen, die OpenSSL 1.1 unterstützt, oder verwenden Sie -s ssl3 , um die Erweiterung herunterzuladen, die OpenSSL 3.x unterstützt.

      • Für die Version der Instana-Erweiterung ist der Standardwert release, wodurch die neueste verfügbare Version heruntergeladen wird. Verwenden Sie das -v Flag, um das Artefakt für eine bestimmte Version herunterzuladen. Führen Sie zum Beispiel das Skript mit -v 4.7.0 aus, um die Erweiterung mit der Release-Version 4.7.0 herunterzuladen.

      • Um alle für das Skript verfügbaren Optionen zu sehen, führen Sie den folgenden Befehl aus:

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

2. Installieren Sie die Erweiterung wie folgt:

   1. Verschieben Sie die heruntergeladene Datei .so in das Verzeichnis der PHP CLI-Erweiterung.

   2. Erstellen Sie eine INI-Datei, zzz-instana.ini, wie im folgenden Beispiel gezeigt, und speichern Sie sie im Verzeichnis PHP CLI additional INI. Ersetzen Sie <hostIP> durch die IP-Adresse des Instana-Agenten-Hosts, damit der Agent von der PHP-Umgebung aus erreichbar ist.

      ; 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
       

Führen Sie die unter Deaktivieren der PHP-Ablaufverfolgung beschriebenen Schritte aus, um die PHP-Ablaufverfolgung vollständig zu deaktivieren, einschließlich der Entfernung der PHP-Tracing-Erweiterung aus Ihrer PHP-Laufzeitumgebung.

Wenn während dieses Vorgangs Fehler auftreten und Sie die PHP-Verfolgung manuell deaktivieren und die PHP-Tracing-Erweiterung deinstallieren möchten, führen Sie die folgenden Schritte aus:

1. Stellen Sie sicher, dass PHP-Tracing in der Datei configuration.yaml wie folgt deaktiviert ist:

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

   Diese Konfiguration verhindert, dass der PHP-Sensor die PHP-Tracing-Erweiterung erneut installiert.

2. Deaktivieren Sie die PHP Tracing-Erweiterung in Ihrer PHP INI-Konfiguration. Siehe Deaktivieren der PHP-Tracing-Erweiterung.

3. Entfernen Sie die PHP Tracing-Erweiterungsdatei von Ihrem System. Siehe Entfernen der PHP-Tracing-Erweiterungsdatei.