apmtrace_get
Read-only
Retrieve OpenTelemetry APM traces from Zabbix by time range, trace ID, attributes, or duration; filter, sort, and page root-span records for trace analysis.
Instructions
Retrieve OpenTelemetry (OTel) APM traces (Zabbix 8.0+): one record per trace, described by its root span (service_name, span_name, duration in nanoseconds, status_code, span_count, resource and span attributes). time_from and time_till are required and bound the root span start. 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.
Input Schema
TableJSON 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, 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 comma-separated list of property names. Default when omitted: timestamp, traceid, service_name, span_name, duration, status_code, span_count. Properties: duration, error_count, events, 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 (comma-separated for several; pair with 'sortorder'). No other property is sortable. | |
| sortorder | No | Sort order: 'ASC' or 'DESC'. | |
| time_from | Yes | Return only traces whose root span 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 whose root span 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 lasted less than this many nanoseconds. | |
| min_duration | No | Return only traces whose 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. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |