apmtrace.get

Description

integer/array apmtrace.get(object parameters)

The method allows you to retrieve traces according to the given parameters.

This method is available to users of any type. Permissions to call the method can be revoked in user role settings. See User roles for more information.

Parameters

(object) Parameters defining the desired output.

The method supports the following parameters.

Parameter Type Description
time_from timestamp Return only traces whose root span started at or after the given time.

Parameter behavior:
- required
time_till timestamp Return only traces whose root span started before the given time.

Parameter behavior:
- required
traceids string/array Return only traces with the given IDs.
resource_attributes object/array Return only traces whose root span has the given resource attributes.
Format: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...].
An empty array returns all traces.

Possible operator values:
0 - (default) Contains;
1 - Equals;
2 - Does not contain;
3 - Does not equal;
4 - Exists;
5 - Does not exist.
resource_attributes_evaltype integer Evaluation method for the conditions in resource_attributes.

Possible values:
0 - (default) And/Or;
2 - Or.
span_attributes object/array Return only traces whose root span has the given span attributes.
Format: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...].
An empty array returns all traces.

Possible operator values:
0 - (default) Contains;
1 - Equals;
2 - Does not contain;
3 - Does not equal;
4 - Exists;
5 - Does not exist.
span_attributes_evaltype integer Evaluation method for the conditions in span_attributes.

Possible values:
0 - (default) And/Or;
2 - Or.
min_duration integer Return only traces whose root span duration is greater than or equal to the given value, in nanoseconds.
max_duration integer Return only traces whose root span duration is less than the given value, in nanoseconds.
filter object Return only those results that exactly match the given filter.

Accepts an object, where the keys are property names, and the values are either a single value or an array of values to match against.

Supported properties: traceid, spanid, trace_state, span_name, span_kind, service_name, scope_name, scope_version, status_code, status_message.
search object Return results that match the given pattern (case-insensitive).

Accepts an object, where the keys are property names, and the values are strings to search for. If no additional options are given, this will perform a LIKE "%…%" search.

Supported properties: trace_state, span_name, service_name, scope_name, scope_version, status_message.
sortfield string/array Sort the result by the given properties.

Possible values: timestamp, traceid, spanid, trace_state, span_name, span_kind, service_name, scope_name, scope_version, duration, status_code, status_message.
offset integer Number of records to skip before returning the result.
countOutput boolean These parameters are described in the reference commentary.
excludeSearch boolean
limit integer
output query
searchByAny boolean
searchWildcardsEnabled boolean
sortorder string/array
startSearch boolean

Return values

(integer/array) Returns either:

  • an array of objects;
  • the count of retrieved objects, if the countOutput parameter has been used.

Examples

Retrieving slow traces

Retrieve the two slowest traces of the zabbix-nginx service. Search traces from 10:00 to 11:00 on October 1, 2026 (UTC), and include only those that took 1 second or longer.

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
}

Response:

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

See also

Source

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