apmspan_get
Read-only
Retrieve OpenTelemetry APM spans from Zabbix 8.0+ within a required time range, filtering by trace, span, attributes, or duration and paging results.
Instructions
Retrieve OpenTelemetry (OTel) APM spans (Zabbix 8.0+): the individual operations inside traces, with parent_spanid, span_kind, duration in nanoseconds, status, events and links. time_from and time_till are required and bound the span start. Filter by traceids (all spans of a trace), spanids, parent_spanids, attribute conditions or duration. Page with limit and offset. For a user who is not Super admin the result is limited to the data whose resource attributes match an APM filter of one of the user's groups (usergroup 'apm_filters').
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return. | |
| filter | No | Return only results whose properties exactly match the given values (a single value or a list of values per key). Example: {"status": 0} or {"status": [0, 1]}. Keys: duration, events, links, parent_spanid, resource_attributes, scope_name, scope_version, service_name, span_attributes, span_kind, span_name, spanid, status_code, status_message, timestamp, trace_state, traceid. Text properties cannot be filtered; use 'search' for them. | |
| offset | No | Number of records to skip before returning the result (paging). | |
| output | No | Properties of the apmspan object to return. Pass 'extend' for all, 'count' for the number of matches only, or a list of property names. Default when omitted: timestamp, traceid, spanid, parent_spanid, service_name, span_name, duration, status_code. Properties: duration, events, links, parent_spanid, resource_attributes, scope_name, scope_version, service_name, span_attributes, span_kind, span_name, spanid, status_code, status_message, timestamp, trace_state, traceid. | |
| search | No | Return results whose string properties contain the given pattern (case-insensitive; '*' is a wildcard when searchWildcardsEnabled is true). Example: {"name": "web"}. Keys: parent_spanid, scope_name, scope_version, service_name, span_kind, span_name, spanid, status_code, status_message, trace_state, traceid. | |
| server | No | Target Zabbix server. Available: default. Defaults to 'default' if omitted. | |
| spanids | No | Return only spans with the given IDs. | |
| raw_json | No | Strips the security disclaimer preamble from the response so it is pure JSON. Default: false. Requires the bearer token to have 'allow_raw_json' explicitly enabled by an operator in the admin portal - tokens without that policy receive a PolicyError instead. WARNING: setting true bypasses the prompt-injection mitigation marker that wraps untrusted Zabbix data (host names, item descriptions, problem text). LLM clients (Claude, GPT, Cursor, ...) should leave this false; only programmatic non-LLM consumers (Python scripts, n8n workflows that json.loads the result) should set true. | |
| traceids | No | Return only spans that belong to the given traces. | |
| sortfield | No | Sort by one or more of: timestamp, traceid, spanid, parent_spanid, trace_state, span_name, span_kind, service_name, scope_name, scope_version, duration, status_code, status_message (a list for several; pair with 'sortorder'). No other property is sortable. | |
| sortorder | No | Sort order: 'ASC' or 'DESC'. | |
| time_from | Yes | Return only spans that started at or after this time (required). Unix timestamp, ISO 8601 date-time or a relative time such as now-1h or now-1d/d. | |
| time_till | Yes | Return only spans that started before this time (required). Unix timestamp, ISO 8601 date-time or a relative time such as now or now/d. | |
| extra_params | No | Other native apmspan.get parameters, merged into the request as-is. apmspan.get has no parameters beyond the typed ones. Any other key is refused here, because Zabbix would silently ignore it. For a parameter you are sure exists on your release but is not listed, use zabbix_raw_api_call. | |
| max_duration | No | Return only spans that lasted less than this many nanoseconds. | |
| min_duration | No | Return only spans that lasted at least this many nanoseconds. | |
| parent_spanids | No | Return only spans whose parent span has one of the given IDs. | |
| span_attributes | No | Span attributes: Attribute conditions as a list of {"key": ..., "value": ..., "operator": ...} objects; operators: 0 Contains, 1 Equals, 2 Not like, 3 Not equal, 4 Exists, 5 Does not exist. An empty list returns everything. | |
| resource_attributes | No | Resource attributes: Attribute conditions as a list of {"key": ..., "value": ..., "operator": ...} objects; operators: 0 Contains, 1 Equals, 2 Not like, 3 Not equal, 4 Exists, 5 Does not exist. An empty list returns everything. | |
| span_attributes_evaltype | No | How the conditions in span_attributes combine: 0 = And/Or (default), 2 = Or. | |
| resource_attributes_evaltype | No | How the conditions in resource_attributes combine: 0 = And/Or (default), 2 = Or. |