apmspan.get

Description

integer/array apmspan.get(object parameters)

The method allows you to retrieve spans 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 spans that started at or after the given time.

Parameter behavior:
- required
time_till timestamp Return only spans that started before the given time.

Parameter behavior:
- required
traceids string/array Return only spans that belong to the given traces.
spanids string/array Return only spans with the given IDs.
parent_spanids string/array Return only spans with the given parent spans.
resource_attributes object/array Return only spans with the given resource attributes.
Format: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...].
An empty array returns all spans.

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 spans with the given span attributes.
Format: [{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...].
An empty array returns all spans.

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 spans whose duration is greater than or equal to the given value, in nanoseconds.
max_duration integer Return only spans whose 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, parent_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, parent_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 the span hierarchy of a trace

Retrieve the first four spans of the trace "dee625f33cb0994e86c5cd4640e3b09c", sorted by start time. The parent_spanid property shows how the spans are related: the root span has no parent, and each other span refers to the span that started it.

Request:

{
    "jsonrpc": "2.0",
    "method": "apmspan.get",
    "params": {
        "output": ["spanid", "parent_spanid", "service_name", "span_name", "duration", "status_code"],
        "time_from": 1790848800,
        "time_till": 1790852400,
        "traceids": "dee625f33cb0994e86c5cd4640e3b09c",
        "sortfield": "timestamp",
        "sortorder": "ASC",
        "limit": 4
    },
    "id": 1
}

Response:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "spanid": "7c1a9e2f4b6d8a03",
            "parent_spanid": "",
            "service_name": "zabbix-nginx",
            "span_name": "POST /zabbix.php",
            "duration": "1104826531",
            "status_code": "Unset"
        },
        {
            "spanid": "3f8b2c6d1e9a7054",
            "parent_spanid": "7c1a9e2f4b6d8a03",
            "service_name": "zabbix-frontend",
            "span_name": "POST /zabbix.php",
            "duration": "1098230418",
            "status_code": "Unset"
        },
        {
            "spanid": "b3390ad41931ed08",
            "parent_spanid": "3f8b2c6d1e9a7054",
            "service_name": "zabbix-frontend",
            "span_name": "mysqli::real_connect",
            "duration": "36671360",
            "status_code": "Ok"
        },
        {
            "spanid": "e41f7a2c9d5b3086",
            "parent_spanid": "3f8b2c6d1e9a7054",
            "service_name": "zabbix-frontend",
            "span_name": "mysqli_query",
            "duration": "19704118",
            "status_code": "Ok"
        }
    ],
    "id": 1
}

See also

Source

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