scoutapm_get_calls — Funktion · PHP-Referenz

Signatur

scoutapm_get_calls(): array

Beschreibung

scoutapm_get_calls() ist Teil der ScoutAPM PHP-Erweiterung (scoutapm), einer nativen C-Extension für Performance-Monitoring. Die Funktion gibt ein Array aller instrumentierten Aufrufe zurück, die die Extension seit ihrer Aktivierung bzw. seit dem letzten Aufruf dieser Funktion intern aufgezeichnet hat.

Die Extension überwacht automatisch bestimmte PHP-Kernfunktionen (z. B. Dateioperationen, cURL, PDO, MySQLi) sowie benutzerdefinierte Funktionen, die über scoutapm_enable_instrumentation() markiert wurden. Für jeden Aufruf werden Metadaten wie Funktionsname, Argumente, Startzeit und Ausführungsdauer erfasst.

Typischer Einsatz ist die Integration in einen APM-Agenten (z. B. den offiziellen Scout APM PHP-Agenten), der die gesammelten Daten auswertet, aggregiert und an den Scout APM-Backend-Dienst übermittelt. Direkt in eigenen Projekten kann die Funktion auch für Profiling und Debugging instrumentierter Code-Pfade verwendet werden.

Nach dem Aufruf von scoutapm_get_calls() wird der interne Puffer der Erweiterung geleert, sodass beim nächsten Aufruf nur neue Ereignisse enthalten sind.

Rückgabewert

Typ

array

Beschreibung

Gibt ein (möglicherweise leeres) Array zurück. Jedes Element ist ein assoziatives Array mit Informationen zu einem instrumentierten Aufruf, typischerweise mit den Schlüsseln:

function – Name der aufgerufenen Funktion oder Methode
entered – Zeitstempel (als Float) des Aufrufbeginns in Mikrosekunden
exited – Zeitstempel (als Float) des Aufrufendes in Mikrosekunden
time_taken – Ausführungsdauer in Sekunden (Float)
argv – Array der übergebenen Argumente (sofern erfasst)

Die genaue Struktur kann je nach Version der scoutapm-Extension variieren.

Beispiele

Instrumentierte Aufrufe nach PDO-Abfrage auslesen

<?php
// Voraussetzung: scoutapm-Extension ist geladen
if (!extension_loaded('scoutapm')) {
    die('scoutapm-Extension nicht geladen.');
}

// Eine instrumentierte Operation durchführen (z. B. Datei lesen)
$content = file_get_contents(__FILE__);

// Alle seit dem letzten scoutapm_get_calls()-Aufruf gesammelten Aufrufe abrufen
$calls = scoutapm_get_calls();

foreach ($calls as $call) {
    printf(
        "Funktion: %s | Dauer: %.6f Sek.\n",
        $call['function'],
        $call['time_taken']
    );
}

Funktion: file_get_contents | Dauer: 0.000123 Sek.

Puffer-Verhalten: Nach Abruf ist der Puffer geleert

<?php
// Erste Operation
file_get_contents(__FILE__);

// Erster Abruf: enthält den obigen Aufruf
$calls1 = scoutapm_get_calls();
echo 'Erster Abruf: ' . count($calls1) . ' Aufruf/Aufrufe' . PHP_EOL;

// Zweiter Abruf ohne neue Operationen: Puffer ist leer
$calls2 = scoutapm_get_calls();
echo 'Zweiter Abruf: ' . count($calls2) . ' Aufruf/Aufrufe' . PHP_EOL;

Erster Abruf: 1 Aufruf/Aufrufe Zweiter Abruf: 0 Aufruf/Aufrufe

// Wichtig · Fallstricke

Voraussetzung: Die native PHP-Extension scoutapm muss installiert und in der php.ini geladen sein (extension=scoutapm.so bzw. extension=scoutapm.dll). Die Funktion ist nicht Teil von PHP selbst und steht ohne die Extension nicht zur Verfügung.

Puffer wird geleert: Jeder Aufruf von scoutapm_get_calls() leert den internen Ringpuffer der Extension. In Langläufer-Prozessen (z. B. ReactPHP, Swoole) sollte die Funktion regelmäßig aufgerufen werden, um einen Speicherüberlauf durch unbegrenzt wachsende Puffer zu vermeiden.

Performance-Overhead: Das Instrumentieren aller überwachten Funktionen erzeugt einen gewissen Overhead. In produktionskritischen Umgebungen sollte die Instrumentierung gezielt aktiviert und die Extension-Konfiguration sorgfältig abgestimmt werden.

Siehe auch

scoutapm_enable_instrumentation