apmtrace.get

描述

integer/array apmtrace.get(object parameters)

此方法允许您根据给定参数检索追踪记录。

任何类型的用户都可以使用此方法。 可以在用户角色设置中撤销调用此方法的权限。 有关更多信息，请参阅用户角色。

参数

(object) 定义所需输出的参数。

该方法支持以下参数。

参数 类型 描述
time_from timestamp 仅返回根 span 在给定时间或之后开始的 trace。

参数行为：
- 必需
time_till timestamp 仅返回根 span 在给定时间之前开始的 trace。

参数行为：
- 必需
traceids string/array 仅返回具有给定 ID 的 trace。
resource_attributes object/array 仅返回其根 span 具有给定资源属性的 trace。
格式：[{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...]。
空数组将返回所有 trace。

可能的 operator 值：
0 - （默认） 包含；
1 - 等于；
2 - 不包含；
3 - 不等于；
4 - 存在；
5 - 不存在。
resource_attributes_evaltype integer resource_attributes 中条件的评估方法。

可能的值：
0 - （默认） And/Or；
2 - Or。
span_attributes object/array 仅返回其根 span 具有给定 span 属性的 trace。
格式：[{"key": "<key>", "value": "<value>", "operator": "<operator>"}, ...]。
空数组将返回所有 trace。

可能的 operator 值：
0 - （默认） 包含；
1 - 等于；
2 - 不包含；
3 - 不等于；
4 - 存在；
5 - 不存在。
span_attributes_evaltype integer span_attributes 中条件的评估方法。

可能的值：
0 - （默认） And/Or；
2 - Or。
min_duration integer 仅返回根 span 的 duration 大于或等于给定值的 trace，单位为纳秒。
max_duration integer 仅返回根 span 的 duration 小于给定值的 trace，单位为纳秒。
filter object 仅返回与给定过滤器完全匹配的结果。

接受一个对象，其中键为属性名称，值为要匹配的单个值或值数组。

支持的属性：traceid、spanid、trace_state、span_name、span_kind、service_name、scope_name、scope_version、status_code、status_message。
search object 返回与给定模式匹配的结果（不区分大小写）。

接受一个对象，其中键为属性名称，值为要搜索的字符串。如果未提供其他选项，则执行 LIKE "%…%" 搜索。

支持的属性：trace_state、span_name、service_name、scope_name、scope_version、status_message。
sortfield string/array 按给定属性对结果进行排序。

可能的值：timestamp、traceid、spanid、trace_state、span_name、span_kind、service_name、scope_name、scope_version、duration、status_code、status_message。
offset integer 返回结果前要跳过的记录数。
countOutput boolean 这些参数在参考说明中进行了描述。
excludeSearch boolean
limit integer
output query
searchByAny boolean
searchWildcardsEnabled boolean
sortorder string/array
startSearch boolean

返回值

(integer/array) 返回以下内容之一：

  • 对象数组；
  • 如果使用了 countOutput 参数，则返回检索到的对象数量。

示例

获取慢速跟踪记录

获取 zabbix-nginx 服务中最慢的两条跟踪记录。
搜索 2026 年 10 月 1 日 10:00 至 11:00（UTC）期间的跟踪记录，并且仅包含耗时达到 1 秒或更长的记录。

请求:

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

响应：

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

另请参阅

来源

ui/include/classes/api/services/CApmTrace.php 中的 CApmTrace::get()。