apmtrace.get

Beschreibung

integer/array apmtrace.get(object parameters)

Mit dieser Methode können Sie anhand der angegebenen Parameter Traces abrufen.

Diese Methode steht Benutzern jeden Typs zur Verfügung. Die Berechtigungen zum Aufrufen der Methode können in den Einstellungen der Benutzerrolle entzogen werden. Weitere Informationen finden Sie unter Benutzerrollen.

Parameter

(object) Parameter, die die gewünschte Ausgabe definieren.

Die Methode unterstützt die folgenden Parameter.

Parameter Typ Beschreibung
time_from timestamp Gibt nur Traces zurück, deren Root-Span zum angegebenen Zeitpunkt oder danach gestartet wurde.

Parameterverhalten:
- erforderlich
time_till timestamp Gibt nur Traces zurück, deren Root-Span vor dem angegebenen Zeitpunkt gestartet wurde.

Parameterverhalten:
- erforderlich
traceids string/array Gibt nur Traces mit den angegebenen IDs zurück.
resource_attributes object/array Gibt nur Traces zurück, deren Root-Span die angegebenen Ressourcenattribute besitzt.
Format: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...].
Ein leeres Array gibt alle Traces zurück.

Mögliche Werte für operator:
0 - (Standard) Enthält;
1 - Ist gleich;
2 - Enthält nicht;
3 - Ist nicht gleich;
4 - Ist vorhanden;
5 - Ist nicht vorhanden.
resource_attributes_evaltype integer Auswertungsmethode für die Bedingungen in resource_attributes.

Mögliche Werte:
0 - (Standard) Und/Oder;
2 - Oder.
span_attributes object/array Gibt nur Traces zurück, deren Root-Span die angegebenen Span-Attribute besitzt.
Format: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...].
Ein leeres Array gibt alle Traces zurück.

Mögliche Werte für operator:
0 - (Standard) Enthält;
1 - Ist gleich;
2 - Enthält nicht;
3 - Ist nicht gleich;
4 - Ist vorhanden;
5 - Ist nicht vorhanden.
span_attributes_evaltype integer Auswertungsmethode für die Bedingungen in span_attributes.

Mögliche Werte:
0 - (Standard) Und/Oder;
2 - Oder.
min_duration integer Gibt nur Traces zurück, deren duration des Root-Spans größer oder gleich dem angegebenen Wert in Nanosekunden ist.
max_duration integer Gibt nur Traces zurück, deren duration des Root-Spans kleiner als der angegebene Wert in Nanosekunden ist.
filter object Gibt nur Ergebnisse zurück, die exakt mit dem angegebenen Filter übereinstimmen.

Akzeptiert ein Objekt, dessen Schlüssel Eigenschaftsnamen und dessen Werte entweder ein einzelner Wert oder ein Array von Werten sind, mit denen abgeglichen wird.

Unterstützte Eigenschaften: traceid, spanid, trace_state, span_name, span_kind, service_name, scope_name, scope_version, status_code, status_message.
search object Gibt Ergebnisse zurück, die dem angegebenen Muster entsprechen (ohne Beachtung der Groß-/Kleinschreibung).

Akzeptiert ein Objekt, dessen Schlüssel Eigenschaftsnamen und dessen Werte Zeichenfolgen sind, nach denen gesucht wird. Wenn keine zusätzlichen Optionen angegeben werden, wird eine LIKE "%…%"-Suche durchgeführt.

Unterstützte Eigenschaften: trace_state, span_name, service_name, scope_name, scope_version, status_message.
sortfield string/array Sortiert das Ergebnis nach den angegebenen Eigenschaften.

Mögliche Werte: timestamp, traceid, spanid, trace_state, span_name, span_kind, service_name, scope_name, scope_version, duration, status_code, status_message.
offset integer Anzahl der Datensätze, die vor der Rückgabe des Ergebnisses übersprungen werden.
countOutput boolean Diese Parameter werden in der Referenzdokumentation beschrieben.
excludeSearch boolean
limit integer
output query
searchByAny boolean
searchWildcardsEnabled boolean
sortorder string/array
startSearch boolean

Rückgabewerte

(integer/array) Gibt entweder Folgendes zurück:

  • ein Array von Objekten;
  • die Anzahl der abgerufenen Objekte, wenn der Parameter countOutput verwendet wurde.

Beispiele

Langsame Traces abrufen

Rufen Sie die beiden langsamsten Traces des Dienstes zabbix-nginx ab.
Suchen Sie nach Traces vom 1. Oktober 2026 (UTC) zwischen 10:00 und 11:00 Uhr und berücksichtigen Sie nur diejenigen, deren Dauer mindestens 1 Sekunde betrug.

Anfrage:

{
    "jsonrpc": "2.0",
    "method": "apmtrace.get",
    "params": {
        "output": ["timestamp", "traceid", "span_name", "service_name", "duration", "status_code", "span_count", "error_count"],
        "time_from": 1790848800,
        "time_till": 1790852400,
        "filter": {
            "service_name": "zabbix-nginx"
        },
        "min_duration": 1000000000,
        "sortfield": "duration",
        "sortorder": "DESC",
        "limit": 2
    },
    "id": 1
}

Antwort:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "timestamp": "1790849274910226417",
            "traceid": "8a4f1c7e2b9d4e6fa0c3b5d7e9f1a2c4",
            "span_name": "POST /zabbix.php",
            "service_name": "zabbix-nginx",
            "duration": "30412907815",
            "status_code": "Error",
            "span_count": "49",
            "error_count": "2"
        },
        {
            "timestamp": "1790850512338104952",
            "traceid": "dee625f33cb0994e86c5cd4640e3b09c",
            "span_name": "POST /zabbix.php",
            "service_name": "zabbix-nginx",
            "duration": "1104826531",
            "status_code": "Unset",
            "span_count": "27",
            "error_count": "0"
        }
    ],
    "id": 1
}

Siehe auch

Quelle

CApmTrace::get() in ui/include/classes/api/services/CApmTrace.php.