apmtrace.get

Descrição

integer/array apmtrace.get(object parameters)

O método permite recuperar traces de acordo com os parâmetros fornecidos.

Este método está disponível para usuários de qualquer tipo. As permissões para chamar o método podem ser revogadas nas configurações da função de usuário. Consulte Funções de usuário para obter mais informações.

Parâmetros

(object) Parâmetros que definem a saída desejada.

O método aceita os seguintes parâmetros.

Parâmetro Tipo Descrição
time_from timestamp Retorna somente os traces cujo span raiz foi iniciado no horário especificado ou posteriormente.

Comportamento do parâmetro:
- obrigatório
time_till timestamp Retorna somente os traces cujo span raiz foi iniciado antes do horário especificado.

Comportamento do parâmetro:
- obrigatório
traceids string/array Retorna somente os traces com os IDs especificados.
resource_attributes object/array Retorna somente os traces cujo span raiz tenha os atributos de recurso especificados.
Formato: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...].
Uma matriz vazia retorna todos os traces.

Valores possíveis de operator:
0 - (padrão) Contém;
1 - É igual a;
2 - Não contém;
3 - Não é igual a;
4 - Existe;
5 - Não existe.
resource_attributes_evaltype integer Método de avaliação das condições em resource_attributes.

Valores possíveis:
0 - (padrão) E/OU;
2 - OU.
span_attributes object/array Retorna somente os traces cujo span raiz tenha os atributos de span especificados.
Formato: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...].
Uma matriz vazia retorna todos os traces.

Valores possíveis de operator:
0 - (padrão) Contém;
1 - É igual a;
2 - Não contém;
3 - Não é igual a;
4 - Existe;
5 - Não existe.
span_attributes_evaltype integer Método de avaliação das condições em span_attributes.

Valores possíveis:
0 - (padrão) E/OU;
2 - OU.
min_duration integer Retorna somente os traces cujo duration do span raiz seja maior ou igual ao valor especificado, em nanossegundos.
max_duration integer Retorna somente os traces cujo duration do span raiz seja menor que o valor especificado, em nanossegundos.
filter object Retorna somente os resultados que correspondam exatamente ao filtro especificado.

Aceita um objeto cujas chaves são nomes de propriedades e cujos valores são um único valor ou uma matriz de valores a serem comparados.

Propriedades compatíveis: traceid, spanid, trace_state, span_name, span_kind, service_name, scope_name, scope_version, status_code, status_message.
search object Retorna os resultados que correspondam ao padrão especificado (sem distinção entre maiúsculas e minúsculas).

Aceita um objeto cujas chaves são nomes de propriedades e cujos valores são strings a serem pesquisadas. Se nenhuma opção adicional for especificada, será realizada uma pesquisa LIKE "%…%".

Propriedades compatíveis: trace_state, span_name, service_name, scope_name, scope_version, status_message.
sortfield string/array Ordena o resultado pelas propriedades especificadas.

Valores possíveis: 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 a ignorar antes de retornar o resultado.
countOutput boolean Esses parâmetros são descritos no comentário de referência.
excludeSearch boolean
limit integer
output query
searchByAny boolean
searchWildcardsEnabled boolean
sortorder string/array
startSearch boolean

Valores de retorno

(integer/array) Retorna um dos seguintes:

  • um array de objetos;
  • a quantidade de objetos recuperados, se o parâmetro countOutput tiver sido usado.

Exemplos

Recuperando traces lentos

Recupere os dois traces mais lentos do serviço zabbix-nginx. Pesquise traces das 10:00 às 11:00 de 1º de outubro de 2026 (UTC) e inclua apenas aqueles que levaram 1 segundo ou mais.

Request:

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

Resposta:

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

Veja também

Origem

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