Aktivieren und Konfigurieren der Ablaufverfolgung von „ PHP “

Um die Ablaufverfolgung über die Umgebungsvariable zu deaktivieren, setzen Sie die Umgebungsvariable INSTANA_CONFIG_PATH auf den absoluten Pfad der Datei „ YAML “ mit Ihrer Konfiguration.

Um beispielsweise die Ablaufverfolgung für alle Datenbankaufrufe (außer „ MongoDB “) und alle Protokollierungsframeworks zu deaktivieren, kopieren Sie den folgenden Code in eine separate Datei „ YAML “:

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

Setzen Sie die Umgebungsvariable INSTANA_CONFIG_PATH auf den absoluten Pfad der Datei „ YAML “, in der der Inhalt wie folgt abgelegt ist:

INSTANA_CONFIG_PATH=<your YAML file>
 

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

Um die Ablaufverfolgung für alle Datenbankaufrufe (außer „ Redis “) und alle Protokollierungsframeworks zu deaktivieren, aktualisieren Sie den com.instana.tracing Abschnitt in Ihrer configuration.yaml Agentendatei 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.

Durch Deaktivieren der Ablaufverfolgung für eine Kategorie wird die Spannen-Generierung für alle Bibliotheken unter dieser Kategorie deaktiviert. Siehe die folgende Liste der von „ PHP Tracer” unterstützten Kategorien:

• Datenbanken
• frameworks
• Nachrichtenübertragung
• Protokolle
• Protokollierung
• Erstellung anhand einer Vorlage
• Sonstige (Für sonstige gibt es keinen Kategorie-Schlüssel)

Span-Deaktivierungsregeln werden in der folgenden Reihenfolge angewendet, aufgeführt von der höchsten zur niedrigsten Priorität:

1. Deaktivieren Sie Regeln aus der Konfigurationsdatei, die über die INSTANA_CONFIG_PATH Umgebungsvariable übergeben wird.
2. Span-Deaktivierung in der instana.disabled_instrumentation INI-Einstellung konfiguriert.
3. Regeln zum Deaktivieren von Spannen aus der configuration.yaml Agentendatei.

Diese Priorität wird auf Funktionsebene durchgesetzt. Wenn eine „ PHP “-Laufzeitumgebung mehrere Konfigurationen in einer Funktion erkennt, wendet sie die Regeln zum Deaktivieren von Spannen aus der Konfiguration mit der höchsten Priorität an. Wenn beispielsweise eine PHP -Laufzeitumgebung die folgenden Regeln zum Deaktivieren von Spans über die INSTANA_CONFIG_PATH Umgebungsvariable festgelegt hat:

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

Und dieselbe Laufzeitumgebung hat die folgende INI-Einstellung:

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

Mit dieser Beispielkonfiguration funktioniert der Tracer „ PHP “ wie folgt:

• Die Ablaufverfolgung für alle Protokollierungsbibliotheken ist deaktiviert.
• Die Ablaufverfolgung für alle Datenbanken ist deaktiviert, mit Ausnahme von Redis.

Die instana.disabled_instrumentation ini-Einstellung wird ignoriert, da die INSTANA_CONFIG_PATH Umgebungsvariable Vorrang hat. Daher sind alle Instrumentierungen aktiviert, die nicht über die durch die INSTANA_CONFIG_PATH Umgebungsvariable angegebene Konfigurationsdatei deaktiviert sind.

Wenn Regeln zum Deaktivieren von Spannen sowohl über die INSTANA_CONFIG_PATH Umgebungsvariable als auch über die configuration.yaml Agentendatei festgelegt werden, werden die Regeln aus der configuration.yaml Datei ignoriert.

Der Sensor „ PHP ” erkennt alle Änderungen in der configuration.yaml Agentendatei und erstellt eine Kopie des Abschnitts com.instana.tracing.disable in einer separaten Datei unter <System Temp>/instana-php/instana_span_filer_config.yaml. Der absolute Pfad der generierten Datei wird in der instana.span_filter_config_file INI-Einstellung so festgelegt, dass PHP Tracer alle nachfolgenden Änderungen an der configuration.yaml Datei erkennen und anwenden kann, ohne dass die PHP -Laufzeit neu gestartet werden muss. Daher muss die Laufzeitumgebung von „ PHP “ Lesezugriff auf den temporären Ordner des Systems haben, wenn Sie Regeln zum Deaktivieren von Spans über die configuration.yaml Agentendatei konfigurieren.

Die folgenden Unterabschnitte beschreiben die zusätzlichen Schritte, die in einigen Umgebungen erforderlich sind, damit die Laufzeitumgebung von „ PHP “ ausreichenden Zugriff auf den temporären Ordner des Systems hat.

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

Wenn dieses Skript konfiguriert und erfolgreich ausgeführt wird, überschreibt es den Standardmechanismus für automatische Neustarts. Im Gegensatz zum Standardmechanismus wird das Skript für jede SAPI ausgeführt, sodass es zur Automatisierung von Neustarts für CGI-Umgebungen ( PHP ) verwendet werden kann. Wenn Sie automatische Neustarts vollständig deaktivieren möchten, konfigurieren Sie ein leeres Skript.

Der Sensor „ PHP “ legt die folgenden Umgebungsvariablen für die Skriptausführung fest:

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 “ in einem Container ausgeführt wird, 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 einen Befehl „ SIGUSR2 “ senden, um es wie im folgenden Beispiel gezeigt ordnungsgemäß neu zu starten:

docker exec $INSTANA_CONTAINER kill -USR2 $INSTANA_PID_CONTAINER;
 

Ein eleganter Neustart lädt die Erweiterung „ PHP “ in den Speicher, ohne den Master-Prozess neu zu starten. Diese Ladung funktioniert also auch, wenn der Prozess als PID 1 innerhalb des Containers läuft. Wenn Sie den Neustart nicht verwenden können oder möchten, können Sie auch einen Snapshot der laufenden Containerinstanz erstellen, diese stoppen und ganz 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-Images zu ermitteln. Anschließend wird der aktuell ausgeführte Container in ein neues Image übernommen, das mit der neuen Versionsnummer der Erweiterung „ PHP “ gekennzeichnet ist. Anschließend wird der ursprüngliche Container angehalten und ein Container aus dem neu getaggten Image gestartet. Diese Aktion löst zwar erneut die Installationsroutine im Sensor „ PHP “ aus, jedoch nicht erneut das Benachrichtigungsskript, da die Erweiterung bereits installiert ist.

Diese Beispiele gehen davon aus, dass Sie „ Docker “ als Container-Engine verwenden. Da das ausgelöste Shell-Skript jedoch vollständig unter Ihrer Kontrolle steht, können Sie jede beliebige Logik einfügen, die Sie benötigen, damit automatische Neustarts für Ihre Konfiguration funktionieren.

Um die automatische Installation der Erweiterung „ PHP Tracing“ in neu erkannten „ PHP “-Laufzeitumgebungen zu deaktivieren, setzen Sie tracing.installExtension auf false im Abschnitt com.instana.plugin.php der configuration.yaml Agentendatei:

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

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

Wenn in der Benutzeroberfläche von „ Instana “ keine Spuren für „ PHP “-Anwendungen angezeigt werden, führen Sie die folgenden Schritte aus:

1. Überprüfen Sie die folgenden Voraussetzungen:

   • Der Sensor „ PHP “ ist aktiviert. Weitere Informationen finden Sie unter Deaktivieren der Ablaufverfolgung „ PHP “.
   • Die Binärdatei für die Erweiterung „ PHP -Tracing“ ist verfügbar. Weitere Informationen finden Sie unter Deaktivieren der Erweiterung „ PHP -Tracing “.
   • Die Erweiterung „ PHP -Tracing“ ist in der Agent-Konfigurationsdatei aktiviert. Weitere Informationen finden Sie unter Entfernen der Datei „ PHP Tracing Extension “.

2. Laden Sie die Erweiterung „ PHP -Tracing“ neu, indem Sie den folgenden reload Befehl für den Dienst ausführen, auf dem „ PHP “-Anwendungen ausgeführt werden:

   • Für „ Apache “:

     systemctl reload apache2
      

   • Für PHP -FPM:

     systemctl reload php<version>-fpm
      

     Ersetzen Sie <version> im Befehl zum Neuladen durch die tatsächlich auf dem System installierte Version.

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

Die Erweiterung „ PHP ” Tracer kommuniziert mit dem Daemon „ PHP ” über den Socket „ <socket path>UnixTCP ” und mit dem Agenten „ Instana ” über den IP-Port „ TCP /IP 42699”. Wenn SELinux auf den Durchsetzungsmodus eingestellt ist, verhindert es die Kommunikation zwischen der Erweiterung „ PHP “ und dem Daemon, es sei denn, SELinux ist so konfiguriert, dass es dies zulässt.

Um zu überprüfen, ob SELinux für das Problem verantwortlich ist, überprüfen Sie /var/log/audit/audit.log , ob für den Daemon „ PHP “ stillschweigende Ablehnungen protokolliert wurden. Alternativ können Sie einen Rauch-Test durchführen, indem Sie die folgenden Schritte ausführen:

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

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

• Konfigurieren Sie SELinux so, dass die Kommunikation zwischen dem Tracer und dem Dienst „ PHP “ möglich ist: Mit SELinux können Sie Ihre eigenen Sicherheitsrichtlinien befolgen, um eine benutzerdefinierte Richtlinie zu konfigurieren, die die Kommunikation ermöglicht. Weitere Informationen zum Erstellen und Ändern von SELinux-Richtlinien finden Sie unter den folgenden Links:

  • CentOS SELinux-Dokumentation
  • RHEL SELinux-Dokumentation

• SELinux in den permissiven Modus versetzen: In diesem Modus können Ihre Dienste ohne Einschränkungen ausgeführt werden. Sie können die Standardeinstellung wiederherstellen, indem Sie den Server neu starten. Um SELinux in den permissiven Modus zu versetzen, siehe SELinux-Permissive-Modus.

• SELinux deaktivieren: Instana empfiehlt Ihnen nicht ausdrücklich, Sicherheitssoftware zu deaktivieren. Ein richtiger und sicherer Ansatz ist die Erstellung einer SELinux-Richtlinie. Wenn Sie sich jedoch entscheiden, SELinux zu deaktivieren, lesen Sie bitte den Abschnitt „ Linux deaktivieren “.

Standardmäßig ist die Protokollierung deaktiviert. Um es zu aktivieren, befolgen Sie die folgenden Schritte.

• Aktivieren Sie die Protokollierung mithilfe von Umgebungsvariablen.

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

• Aktivieren Sie die Protokollierung mithilfe der INI-Datei.

1. Suchen Sie eine Datei namens zzz-instana.ini im Scan-Verzeichnis Ihrer PHP -Installation. Beispielsweise gibt das Ausführen von php --ini | grep zzz-instana.ini oder seinen Standort php-fpm<version> -i | grep zzz-instana.ini preis.

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

3. Wenn Sie die Laufzeitumgebung „ PHP “ Ihrer Wahl ausführen, stellen Sie sicher, dass in der Ausgabe einige Protokollierungen vorhanden sind und dass die Erweiterung aktiviert ist. Beispielsweise können Sie oder php --ri instana ausführen php-fpm<version> -i | grep instana , um dies zu überprüfen.

   Beispiel:

   [instana.INFO] Initializing, logging at level 4
    

4. Laden Sie die Tracing-Erweiterung „ PHP “ wie hier beschrieben neu. Wenn Sie diesen Schritt überspringen, wird letztendlich keine Protokollierung durchgeführt.

Protokolle werden in die Laufzeitumgebung „ PHP “ geleitet, in der die Ablaufverfolgungserweiterung „ PHP “ 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 Erweiterung „ PHP -Tracing“ manuell zu installieren, führen Sie die folgenden Schritte aus:

1. Laden Sie die Erweiterung „ InstanaPHP Tracing“ 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 an:

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

      • Für die Version „ PHP “ geben Sie die Haupt- und Nebenversionsnummern an. Um beispielsweise die Erweiterung „ Instana “ für PHP 8.4.12 herunterzuladen, führen Sie das Shell-Skript mit dem Flag aus -p 8.4.

      • Für die Version „ OpenSSL “ verwenden Sie die Option -s ssl1 zum Herunterladen der Erweiterung, die „ OpenSSL 1.1 “ unterstützt, oder verwenden Sie -s ssl3 zum Herunterladen der Erweiterung, die „ OpenSSL “ unterstützt. 3.x.

      • Für die Erweiterung „ Instana “ lautet der Standardwert, wodurch die neueste releaseverfügbare Version heruntergeladen wird. Verwenden Sie -v das Flag, um das Artefakt für eine bestimmte Version herunterzuladen. Führen Sie beispielsweise das Skript mit aus -v 4.7.0 , um die Erweiterung mit der Release-Version 4.7.0 herunterzuladen.

      • Um alle für das Skript verfügbaren Optionen anzuzeigen, 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 .so Datei in das Verzeichnis „ PHP “ der CLI-Erweiterung.

   2. Erstellen Sie eine INI-Datei wie im folgenden Beispiel gezeigt und speichern Sie sie im zusätzlichen INI-Verzeichnis zzz-instana.ini der CLI „ PHP “. Ersetzen Sie <hostIP> durch die IP-Adresse des Instana -Agentenhosts, 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
       

Wenn Sie die unter „Deaktivieren von ‚ PHP ‘“ beschriebenen Schritte ausführen, wird die Verfolgung von „ PHP “ vollständig deaktiviert, einschließlich der Entfernung der Erweiterung „ PHP Tracing“ aus Ihrer „ PHP “-Laufzeitumgebung.

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

1. Stellen Sie sicher, dass die Ablaufverfolgung „ PHP “ in der configuration.yaml Agentendatei wie folgt deaktiviert ist:

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

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

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

3. Entfernen Sie die Erweiterung „ PHP Tracing“ von Ihrem System. Siehe Entfernen der Datei „ PHP Tracing Extension “.