apmtrace_get
Retrieves OpenTelemetry APM traces from Zabbix with root span details, durations, status codes, and error counts. Filter by time range, trace IDs, attributes, or duration and page results.
Instructions
Retrieve OpenTelemetry (OTel) APM traces (Zabbix 8.0+): one record per trace, with the service_name and span_name of its root span, duration in nanoseconds (from the start of its first span to the end of its last), status_code, span_count, error_count, has_root_span, resource and span attributes. time_from and time_till are required and bound the start of the trace: of its root span or, for a trace whose root span is not stored (has_root_span 0), of its earliest span. Filter by traceids, resource_attributes / span_attributes conditions, or min_duration / max_duration. Page with limit and offset. Use apmspan_get for the spans of a trace and apmlog_get for its log records. 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, error_count, events, has_root_span, links, resource_attributes, scope_name, scope_version, service_name, span_attributes, span_count, 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 apmtrace 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, service_name, span_name, duration, status_code, span_count. Properties: duration, error_count, events, has_root_span, links, resource_attributes, scope_name, scope_version, service_name, span_attributes, span_count, 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: 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. | |
| 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 traces with the given IDs. | |
| sortfield | No | Sort by one or more of: timestamp, traceid, 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 traces 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 traces 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 apmtrace.get parameters, merged into the request as-is. apmtrace.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 traces whose root span (the whole trace, where it has no root span) lasted less than this many nanoseconds. | |
| min_duration | No | Return only traces whose root span (the whole trace, where it has no root span) lasted at least this many nanoseconds. | |
| 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. |