apmtrace.get

Descripción

integer/array apmtrace.get(object parameters)

El método permite recuperar trazas según los parámetros especificados.

Este método está disponible para usuarios de cualquier tipo. Los permisos para llamar al método pueden revocarse en la configuración de roles de usuario. Consulte Roles de usuario para obtener más información.

Parámetros

(object) Parámetros que definen el resultado deseado.

El método admite los siguientes parámetros.

Parámetro Tipo Descripción
time_from timestamp Devuelve únicamente los seguimientos cuyo span raíz se inició en el momento indicado o después.

Comportamiento del parámetro:
- obligatorio
time_till timestamp Devuelve únicamente los seguimientos cuyo span raíz se inició antes del momento indicado.

Comportamiento del parámetro:
- obligatorio
traceids string/array Devuelve únicamente los seguimientos con los ID indicados.
resource_attributes object/array Devuelve únicamente los seguimientos cuyo span raíz tiene los atributos de recurso indicados.
Formato: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...].
Un array vacío devuelve todos los seguimientos.

Valores posibles de operator:
0 - (predeterminado) Contiene;
1 - Es igual a;
2 - No contiene;
3 - No es igual a;
4 - Existe;
5 - No existe.
resource_attributes_evaltype integer Método de evaluación de las condiciones de resource_attributes.

Valores posibles:
0 - (predeterminado) And/Or;
2 - Or.
span_attributes object/array Devuelve únicamente los seguimientos cuyo span raíz tiene los atributos de span indicados.
Formato: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...].
Un array vacío devuelve todos los seguimientos.

Valores posibles de operator:
0 - (predeterminado) Contiene;
1 - Es igual a;
2 - No contiene;
3 - No es igual a;
4 - Existe;
5 - No existe.
span_attributes_evaltype integer Método de evaluación de las condiciones de span_attributes.

Valores posibles:
0 - (predeterminado) And/Or;
2 - Or.
min_duration integer Devuelve únicamente los seguimientos cuya duration del span raíz es mayor o igual que el valor indicado, en nanosegundos.
max_duration integer Devuelve únicamente los seguimientos cuya duration del span raíz es menor que el valor indicado, en nanosegundos.
filter object Devuelve únicamente los resultados que coinciden exactamente con el filtro indicado.

Acepta un objeto cuyas claves son nombres de propiedades y cuyos valores son un único valor o un array de valores con los que se debe comparar.

Propiedades compatibles: traceid, spanid, trace_state, span_name, span_kind, service_name, scope_name, scope_version, status_code, status_message.
search object Devuelve los resultados que coinciden con el patrón indicado (sin distinguir entre mayúsculas y minúsculas).

Acepta un objeto cuyas claves son nombres de propiedades y cuyos valores son cadenas que se deben buscar. Si no se proporcionan opciones adicionales, se realizará una búsqueda LIKE "%…%".

Propiedades compatibles: trace_state, span_name, service_name, scope_name, scope_version, status_message.
sortfield string/array Ordena el resultado según las propiedades indicadas.

Valores posibles: timestamp, traceid, spanid, trace_state, span_name, span_kind, service_name, scope_name, scope_version, duration, status_code, status_message.
offset integer Número de registros que se deben omitir antes de devolver el resultado.
countOutput boolean Estos parámetros se describen en el comentario de referencia.
excludeSearch boolean
limit integer
output query
searchByAny boolean
searchWildcardsEnabled boolean
sortorder string/array
startSearch boolean

Valores devueltos

(integer/array) Devuelve uno de los siguientes valores:

  • un array de objetos;
  • el número de objetos recuperados, si se ha utilizado el parámetro countOutput.

Ejemplos

Recuperación de trazas lentas

Recupere las dos trazas más lentas del servicio zabbix-nginx. Busque trazas desde las 10:00 hasta las 11:00 del 1 de octubre de 2026 (UTC) e incluya únicamente aquellas que tardaron 1 segundo o más.

Solicitud:

{
    "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
}

Respuesta:

{
    "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
}

Véase también

Origen

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