Zum Hauptinhalt springen

PHP-Anwendungen mit Tideways profilen

Tideways ist ein kommerzieller Dienst für Application Performance Monitoring (APM) und Profiling von PHP-Anwendungen. Tideways zeichnet kontinuierlich auf, wie lange deine Requests dauern, wo diese Zeit verbraucht wird und welche Fehler auftreten — bis hinunter zu einzelnen Funktionsaufrufen und Datenbankabfragen.

Tideways besteht aus drei Bestandteilen:

  1. Einer PHP-Extension, die deine Anwendung instrumentiert und Traces sammelt. Diese Extension ist in den PHP-Builds von mittwald bereits enthalten und muss nur noch aktiviert werden.
  2. Dem Tideways-Daemon, einem kleinen Hintergrunddienst, der die gesammelten Traces puffert und an das Tideways-Backend weiterleitet. Diesen betreibst du selbst, als Container in deinem Projekt.
  3. Dem Tideways-Backend unter app.tideways.io, in dem du die gesammelten Daten auswertest.

Diese Anleitung zeigt dir, wie du die Extension aktivierst und den Daemon auf der mittwald-Plattform betreibst.

Voraussetzungen​

Für diese Anleitung benötigst du:

  • Zugriff auf ein mittwald mStudio-Projekt mit einer PHP-App (oder einem PHP-Worker)
  • Ein Hosting-Produkt, das Container-Workloads unterstützt, da der Tideways-Daemon als Container läuft
  • Einen Tideways-Account und den API-Key eines Tideways-Projekts (diesen findest du in der Tideways-Oberfläche in den Projekteinstellungen)
  • Eine der folgenden PHP-Versionen — das sind die ersten mittwald-Builds, die die Tideways-Extension mitbringen:
    • PHP 8.3.33 oder neuer
    • PHP 8.4.24 oder neuer
    • PHP 8.5.9 oder neuer

Die PHP-Version deiner App kannst du im mStudio UI nachsehen oder über die CLI:

Lokale Shell-Sitzung
user@local $ mw app get <app-id>

Falls deine App noch eine ältere PHP-Version verwendet, aktualisiere sie, bevor du fortfährst:

Lokale Shell-Sitzung
user@local $ mw app dependency update <app-id> --set php=~8.4

Weitere Informationen zur Verwaltung der PHP-Version findest du unter PHP-Anwendungen verwalten und deployen.

Schritt 1: Den Tideways-Daemon betreiben​

Die PHP-Extension kommuniziert nicht direkt mit dem Tideways-Backend. Stattdessen schickt sie ihre Daten über eine TCP-Verbindung an den Tideways-Daemon, der sich um Pufferung und Übertragung kümmert. Du benötigst daher genau einen Daemon-Container pro Projekt, den sich alle deine PHP-Apps teilen können.

Wir betreiben diesen Daemon als Container in deinem Projekt und verwenden dafür das Image ghcr.io/tideways/daemon:latest aus der GitHub Container Registry. Der Daemon lauscht auf dem TCP-Port 9135 und benötigt keinen persistenten Speicher, es sind also keine Volumes erforderlich.

Über das mStudio UI​

Gehe in mStudio zu deinem Projekt, wähle „Container" und klicke auf „Container erstellen". Ein geführter Dialog öffnet sich, um dir beim Container-Setup zu helfen.

Gib zunächst eine Beschreibung ein — dies ist ein Freitextfeld zur Identifizierung des Containers. Gib zum Beispiel „Tideways-Daemon" ein und klicke auf „Weiter".

Als Nächstes wirst du nach dem Image-Namen gefragt. Gib ghcr.io/tideways/daemon:latest ein und bestätige mit „Weiter".

Entrypoint und Command​

  • Entrypoint: Keine Änderungen erforderlich
  • Command: Für ein Standard-Setup keine Änderungen erforderlich. Um zu steuern, wie sich der Daemon in der Tideways-Oberfläche registriert, kannst du --env=production --hostname=tideways-daemon angeben (siehe Daemon-Optionen weiter unten).

Volumes​

Es sind keine Volumes erforderlich. Der Daemon puffert die Daten nur im Arbeitsspeicher und leitet sie weiter.

Umgebungsvariablen​

Es sind keine Umgebungsvariablen erforderlich.

Am Ende des Dialogs wirst du nach dem Port gefragt. Gib 9135 ein, damit der Daemon für die übrigen Workloads in deinem Projekt erreichbar wird. Klicke auf „Container erstellen", um den Container zu erstellen und zu starten.

Alternative: Verwendung des mw container run-Befehls​

Du kannst den Daemon-Container auch direkt über die Kommandozeile erstellen und starten:

Lokale Shell-Sitzung
user@local $ mw container run \
  --name tideways-daemon \
  --description "Tideways-Daemon" \
  --publish 9135:9135 \
  ghcr.io/tideways/daemon:latest

Das --name-Flag bestimmt den internen DNS-Namen, unter dem der Daemon aus deinen Apps erreichbar ist.

Um Optionen an den Daemon selbst zu übergeben, hängst du sie hinter dem Image-Namen an. Da diese Optionen wie CLI-Flags aussehen, trennst du sie mit einem -- von den mw-Flags:

Lokale Shell-Sitzung
user@local $ mw container run \
  --name tideways-daemon \
  --description "Tideways-Daemon" \
  --publish 9135:9135 \
  -- ghcr.io/tideways/daemon:latest --env=production --hostname=tideways-daemon

Alternative: Verwendung des mw stack deploy-Befehls​

Alternativ kannst du den Befehl mw stack deploy verwenden, der mit Docker Compose kompatibel ist. Erstelle dazu eine docker-compose.yml-Datei mit folgendem Inhalt:

services:
  tideways-daemon:
    image: ghcr.io/tideways/daemon:latest
    command: "--env=production --hostname=tideways-daemon"
    ports:
      - "9135:9135/tcp"

Deploye sie anschließend:

Lokale Shell-Sitzung
user@local $ mw stack deploy

Dieser Befehl liest die docker-compose.yml-Datei aus dem aktuellen Verzeichnis und deployt sie in deinen Standard-Stack.

Daemon-Optionen​

Der Daemon läuft mit seinen Standardeinstellungen problemlos, zwei Optionen solltest du aber explizit setzen:

  • --env=<name> legt den Namen der Umgebung fest, unter der Traces gemeldet werden, zum Beispiel production oder staging. Der Standardwert ist production.
  • --hostname=<name> legt den Servernamen fest, unter dem sich der Daemon in der Tideways-Oberfläche registriert. In Containern hängt der Daemon standardmäßig die Container-ID an den ermittelten Hostnamen an — dadurch erscheint jede Neuerstellung des Containers als neuer Server. Ein fester Hostname vermeidet das.

Alle verfügbaren Optionen sind in der Konfigurationsreferenz des Daemons dokumentiert.

Schritt 2: Die PHP-Extension konfigurieren​

Die Tideways-Extension ist Bestandteil der PHP-Installation deiner App, ist aber standardmäßig deaktiviert. Um sie zu aktivieren und zu konfigurieren, legst du eine neue Konfigurationsdatei im PHP-Konfigurationsverzeichnis deines Projekts an. Verbinde dich dazu per SSH mit deiner App:

Lokale Shell-Sitzung
user@local $ mw app ssh <app-id>

Erstelle dann die Datei ~/.config/php/php.d/20-tideways.ini mit folgendem Inhalt:

~/.config/php/php.d/20-tideways.ini
extension=tideways.so

; Der API-Key deines Tideways-Projekts
tideways.api_key=YOUR_API_KEY

; Interner DNS-Name und Port deines Daemon-Containers
tideways.connection=tcp://tideways-daemon:9135

; Optional: Überschreibt den Standard-Servicenamen für diese App. Nutze
; das mit Bedacht, da manche Anwendungen den Servicenamen automatisch
; setzen, je nachdem, welche Oberfläche gerade genutzt wird (z. B.
; Storefront/Backend/API)
; tideways.service=...

; Prozentsatz der Requests, die mit dem Timeline-Profiler aufgezeichnet werden
tideways.trace_sample_rate=25

Ersetze YOUR_API_KEY durch den API-Key deines Tideways-Projekts und tideways-daemon durch den internen DNS-Namen des Containers aus Schritt 1.

Die Einstellungen haben folgende Bedeutung:

  • tideways.api_key (erforderlich) authentifiziert deine Traces gegenüber deinem Tideways-Projekt.
  • tideways.connection (in diesem Setup erforderlich) verweist die Extension auf deinen Daemon. Ohne diese Einstellung sucht die Extension einen Daemon auf einem lokalen Unix-Socket, den es auf der mittwald-Plattform nicht gibt.
  • tideways.service erlaubt dir, den Standard-Servicenamen zu überschreiben, den Tideways deiner App zuweist. Weitere Informationen findest du in der Dokumentation zur Konfiguration von Services.
  • tideways.trace_sample_rate steuert, wie viel Prozent der Requests mit dem vollständigen Timeline-Profiler aufgezeichnet werden. Der Standardwert ist 25. Alle übrigen Requests werden weiterhin vom Performance- und Fehler-Monitoring erfasst.

Die vollständige Liste der Einstellungen findest du in der Tideways-Konfigurationsdokumentation.

Schritt 3: Das Setup überprüfen​

Prüfe zunächst, ob die Extension geladen ist. Führe dazu in einer SSH-Sitzung auf deiner App aus:

SSH-Sitzung
user@ssh $ php -m | grep -i tideways

Die Ausgabe sollte tideways enthalten. Um zusätzlich zu prüfen, ob deine Einstellungen übernommen wurden, führe aus:

SSH-Sitzung
user@ssh $ php -i | grep tideways

Die Ausgabe dieses Befehls sollte einen Abschnitt wie diesen enthalten:

Can connect to tideways-daemon? => Yes, version 1.15.2

Prüfe als Nächstes, ob der Daemon läuft und Verbindungen annimmt:

Lokale Shell-Sitzung
user@local $ mw container logs tideways-daemon

Schicke abschließend etwas Traffic auf deine Anwendung und öffne dein Projekt unter app.tideways.io. Die ersten Datenpunkte erscheinen üblicherweise innerhalb weniger Minuten.

Gezieltes Profiling mit der Browser-Extension​

Sampling deckt deinen durchschnittlichen Traffic ab, manchmal möchtest du aber einen vollständigen Trace eines bestimmten Seitenaufrufs. Mit der Tideways-Browser-Extension kannst du das direkt aus dem Browser auslösen: Sie setzt ein signiertes TIDEWAYS_SESSION-Cookie, das die PHP-Extension anweist, für deine eigenen Requests einen vollständigen Timeline- und Callgraph-Trace aufzuzeichnen.

Nachdem du sie installiert und dich mit deinem Tideways-Account angemeldet hast, klickst du auf das Tideways-Icon und wählst „Take Profile", um die aktuelle Seite mit aktiviertem Profiling neu zu laden, oder „Profile for 15 seconds", um eine Abfolge von Interaktionen wie ein Formular-Submit oder mehrere AJAX-Calls aufzuzeichnen.

Fehlerbehebung​

In Tideways erscheinen keine Daten​

  • Prüfe, ob der Daemon-Container läuft und Port 9135 veröffentlicht ist. Ohne veröffentlichten Port ist der Container aus deiner App nicht erreichbar.
  • Prüfe, ob tideways.connection den internen DNS-Namen des Containers verwendet und nicht dessen Anzeigenamen oder Container-ID. Den DNS-Namen findest du im mStudio UI oder über mw container list.
  • Sieh dir das PHP-Error-Log unter /var/log/php_errors.log und die Daemon-Logs mit mw container logs tideways-daemon auf Verbindungs- oder Authentifizierungsfehler an.
  • Stelle sicher, dass der API-Key zu dem Tideways-Projekt gehört, das du dir gerade ansiehst.

Die Extension wird nicht geladen​

  • Vergewissere dich, dass deine App eine PHP-Version verwendet, die die Extension enthält (siehe Voraussetzungen).
  • Stelle sicher, dass die Konfigurationsdatei in ~/.config/php/php.d/ liegt und die Endung .ini hat. extension=tideways.so hat in einer verzeichnisbezogenen .user.ini-Datei keine Wirkung.
  • Prüfe das PHP-Error-Log deiner App unter /var/log/php_errors.log auf Meldungen über eine fehlgeschlagene Extension-Ladung.

Profiling einer containerisierten PHP-Anwendung​

Diese Anleitung behandelt Managed PHP-Apps, bei denen mittwald den PHP-Build inklusive Tideways-Extension bereitstellt. Wenn du PHP stattdessen in einem eigenen Container betreibst, musst du die Extension selbst in dein Image installieren — folge dazu der Docker-Installationsanleitung von Tideways. Das Daemon-Setup aus Schritt 1 bleibt unverändert.

Weiterführende Ressourcen​