# 查询trace列表 - ListOpsTrace #### 功能介绍 该接口用于分页查询调用链列表。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts/agentarts_07_0003.html)。 #### 授权信息 账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见[权限和授权项](https://support.huaweicloud.com/api-agentarts/Permission.html)。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | agentarts::listOpsTrace | List | - | - | - | - apm:apm2TraceEvents:get - apm:apm2Service:get | #### URI POST /v1/ops/observation/traces #### 请求参数 表1请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | start_time | 否 | Long | **参数解释**： 开始时间，用于指定查询时间范围的起始时间点，Unix时间戳，单位为ms。 **约束限制**： 必须为有效的Unix时间戳，且不大于end_time。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | end_time | 否 | Long | **参数解释**： 截止时间，用于指定查询时间范围的结束时间点，Unix时间戳，单位为ms。 **约束限制**： 必须为有效的Unix时间戳，且不小于start_time。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | resource_id | 否 | String | **参数解释**： 应用ID，用于筛选指定应用的调用链数据，可通过查询应用列表接口获取。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | resource_type | 否 | String | **参数解释**： 资源类型，用于筛选指定类型的资源调用链数据。 **约束限制**： 不涉及。 **取值范围**： - agent：单智能体； - multiagents：多智能体； - workflow：工作流。 **默认取值**： 不涉及。 | | trace_id | 否 | String | **参数解释**： 调用链ID，可通过查询调用链列表接口（ListOpsTrace）获取。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | status_code | 否 | String | **参数解释**： 状态码，用于筛选指定状态的调用链数据。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | session_id | 否 | String | **参数解释**： 会话ID，唯一标识一个会话，可通过ListOpsSession接口获取，用于筛选指定会话的调用链数据。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | span_type | 否 | String | **参数解释**： Span类型，用于筛选指定类型的Span数据。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | input | 否 | String | **参数解释**： Span的输入内容，即当前Span执行时接收的输入数据。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | output | 否 | String | **参数解释**： Span的输出内容，即当前Span执行完成后返回的输出数据。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | like | 否 | Integer | **参数解释**： 评价状态，用于筛选已评价或未评价的调用链数据。 **约束限制**： 不涉及。 **取值范围**： - 1：点赞。 - 2：点踩。 - 0：取消评价。 **默认取值**： 不涉及。 | | label | 否 | Map\ | **参数解释**： 标注的过滤条件，用于筛选带有特定标签的调用链数据。key表示标签名称，类型为String；value表示标签值，类型为String。 **约束限制**： 不涉及。 | | page_no | 否 | Integer | **参数解释**： 页码，用于分页查询，指定返回第几页的数据。 **约束限制**： 必须为正整数。 **取值范围**： 大于等于1的整数。 **默认取值**： 1。 | | page_size | 否 | Integer | **参数解释**： 每页条数，用于分页查询，指定每页返回的数据条数。 **约束限制**： 必须为正整数。 **取值范围**： 1\~100。 **默认取值**： 10。 | | filter_sign | 否 | String | **参数解释**： 连接标识，用于标明查询语句中条件之间且或者或的关系。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | label_filter | 否 | Array of [FilterParam] objects | **参数解释**： 标签过滤条件，用于按标签筛选调用链数据，支持多个条件的组合查询。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | filter | 否 | Array of [ListFilterParam] objects | **参数解释**： 过滤条件，用于多条件组合筛选调用链数据。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | 表2FilterParam | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | label_name | 否 | String | **参数解释**： 标签名。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | label_value | 否 | String | **参数解释**： 标签值。 **约束限制**： 长度限制为1\~128个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | operator | 否 | String | **参数解释**： 操作类型。 **约束限制**： 不涉及。 **取值范围**： - equal：等于。 - like：包含。 - not_like：不包含。 - empty：为空。 - not_empty：不为空。 - greater_than：大于等于。 - less_than：小于等于。 - in：属于。 - not_in：不属于。 **默认取值**： 不涉及。 | 表3ListFilterParam | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 否 | String | **参数解释**： 过滤名，指定要过滤的字段名称，如resource_id、resource_type等。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | value | 否 | String | **参数解释**： 过滤值，指定要过滤的字段值，需与name字段配合使用。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 根据name字段确定。 **默认取值**： 不涉及。 | | operator | 否 | String | **参数解释**： 操作类型。 **约束限制**： 不涉及。 **取值范围**： - equal：等于。 - like：包含。 - not_like：不包含。 - empty：为空。 - not_empty：不为空。 - greater_than：大于等于。 - less_than：小于等于。 - in：属于。 - not_in：不属于。 **默认取值**： 不涉及。 | #### 响应参数 **状态码：200** 表4响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | total | Integer | **参数解释**： 查询到的Span数据总数。 **取值范围**： 不涉及。 | | span_list | Array of [SpanInfo] objects | **参数解释**： Span列表，包含查询到的所有Span数据，数组中的每个元素为SpanInfo对象。 **取值范围**： 不涉及。 | 表5SpanInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | trace_id | String | **参数解释**： 调用链ID，唯一标识一次完整的调用链。 **取值范围**： 不涉及。 | | parent_span_id | String | **参数解释**： 父节点SpanID，标识当前Span的父节点，根节点时为null。 **取值范围**： 不涉及。 | | span_id | String | **参数解释**： SpanID，用于唯一标识一次调用过程中的一个操作节点。 **取值范围**： 不涉及。 | | span_type | String | **参数解释**： Span类型，标识当前Span所属的类型。 **取值范围**： 不涉及。 | | span_name | String | **参数解释**： 调用链中span的名称，用于标识和定位具体的调用链环节。 **取值范围**： 不涉及。 | | status_code | String | **参数解释**： 状态码，标识当前Span的执行状态。 **取值范围**： 不涉及。 | | status_message | String | **参数解释**： 状态信息，描述当前Span执行状态的详细说明。 **取值范围**： 不涉及。 | | input | String | **参数解释**： Span的输入内容，即当前Span执行时接收的输入数据。 **取值范围**： 不涉及。 | | output | String | **参数解释**： Span的输出内容，即当前Span执行完成后返回的输出数据。 **取值范围**： 不涉及。 | | duration | Integer | **参数解释**： 耗时，当前Span的执行时长，单位为ms。 **取值范围**： 大于等于0的整数。 | | session_id | String | **参数解释**： 会话ID，唯一标识一个会话，可通过ListOpsSession接口获取。 **取值范围**： 不涉及。 | | tokens | Integer | **参数解释**： Tokens消耗，当前Span消耗的总Token数量，单位为个。 **取值范围**： 大于等于0的整数。 | | input_tokens | Integer | **参数解释**： Input Tokens消耗，当前Span输入部分消耗的Token数量，单位为个。 **取值范围**： 大于等于0的整数。 | | output_tokens | Integer | **参数解释**： Output Tokens消耗，当前Span输出部分消耗的Token数量，单位为个。 **取值范围**： 不涉及。 | | start_time | Long | **参数解释**： 当前Span开始执行的时间戳，单位为毫秒。 **取值范围**： 不涉及。 | | call_type | String | **参数解释**： 触发类型，标识当前Span的触发方式，如用户触发、系统自动触发等。 **取值范围**： 不涉及。 | | metadata | String | **参数解释**： 元数据，当前Span的附加描述信息，以键值对形式存储。 **取值范围**： 不涉及。 | | feedback_operation | String | **参数解释**： 评价状态，标识当前Span的用户评价。 **取值范围**： - like：点赞。 - unlike：点踩。 - cancel：取消评价。 | | label | Array of [Label] objects | **参数解释**： 标签组，当前Span关联的所有标签信息。 | | resource_id | String | **参数解释**： 应用ID，当前Span所属应用的唯一标识。 **取值范围**： 不涉及。 | | resource_name | String | **参数解释**： 应用名称，当前Span所属应用的名称。 **取值范围**： 不涉及。 | | resource_type | String | **参数解释**： 应用类型，当前Span所属应用的类型。 **取值范围**： - agent：单智能体； - multiagents：多智能体； - workflow：工作流。 | | model_name | String | **参数解释**： 模型名称，当前Span使用的模型名称。 **取值范围**： 不涉及。 | | is_error | Boolean | **参数解释**： 是否失败，标识当前Span是否执行失败。 **取值范围**： - true：失败。 - false：成功。 | 表6Label | 参数 | 参数类型 | 描述 | |:---|:---|:---| | trace_id | String | **参数解释**： 调用链ID，标签所属的调用链唯一标识。 **取值范围**： 不涉及。 | | span_id | String | **参数解释**： SpanID，用于唯一标识一次调用过程中的一个操作节点。 **取值范围**： 不涉及。 | | start | Long | **参数解释**： 开始时间，标签创建或关联的时间戳，单位为毫秒。 **取值范围**： 不涉及。 | | last_update_time | Long | **参数解释**： 标签最后更新的时间戳，单位为毫秒。 **取值范围**： 不涉及。 | | label_name | String | **参数解释**： 标签名称，标签的标识名。 **取值范围**： 不涉及。 | | string_value | String | **参数解释**： 标签值，当标签值为字符串类型时返回此字段。 **取值范围**： 不涉及。 | | float_value | String | **参数解释**： 标签值，当标签值为浮点数类型时返回此字段。 **取值范围**： 不涉及。 | **状态码：400** 表7响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码。 **取值范围**： 不涉及。 | | error_msg | String | **参数解释**： 错误信息。 **取值范围**： 不涉及。 | **状态码：403** 表8响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码。 **取值范围**： 不涉及。 | | error_msg | String | **参数解释**： 错误信息。 **取值范围**： 不涉及。 | | encoded_authorization_message | String | **参数解释**： 编码后的授权信息，用于客户端解析权限问题。 **取值范围**： 不涉及。 | | details | Array of [OpsObserverCommonError] objects | **参数解释**： 赖的下游服务错误信息列表。 **取值范围**： 不涉及。 | 表9OpsObserverCommonError | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码。 **取值范围**： 不涉及。 | | error_msg | String | **参数解释**： 错误信息。 **取值范围**： 不涉及。 | **状态码：500** 表10响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码。 **取值范围**： 不涉及。 | | error_msg | String | **参数解释**： 错误信息。 **取值范围**： 不涉及。 | #### 请求示例 ``` POST https://api.example.com/v1/ops/observation/traces { "page_no" : 1, "page_size" : 10, "start_time" : 1773279366881, "end_time" : 1775871366881, "span_type" : "root" } ``` #### 响应示例 **状态码：200** **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 200表示成功，其他值表示失败，具体参见错误码文档。 ``` { "span_list" : [ { "trace_id" : "94c7408e75f61939f1deb09b58a1baf1", "span_id" : "7176c7f41140760d", "span_type" : "workflow", "span_name" : "UserInput", "status_code" : "STATUS_CODE_OK", "input" : "10000000000美元可以兑换黄金", "output" : "10000000000美元可以兑换黄金", "duration" : 5, "session_id" : "test111", "tokens" : 0, "input_tokens" : 0, "output_tokens" : 0, "start_time" : 1775271188055, "call_type" : "debug", "label" : [ ], "resource_id" : "b0fd244b-c5c8-4ef7-97b6-645a1b03edc6", "resource_name" : "测试", "resource_type" : "workflow", "is_error" : false, "status_message" : "reason is error" } ], "total" : 5 } ``` **状态码：400** **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 400表示请求参数不正确。 ``` { "error_code" : "AgentArts.05001003", "error_msg" : "请求参数不正确" } ``` **状态码：403** **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 403表示权限不足，拒绝访问。 ``` { "error_code" : "AgentArts.05004003", "error_msg" : "权限不足，拒绝访问", "encode_authorization_message" : "eyJIcnJvciI6ICJVbmF1dGhvcm16ZWQifQ==", "details" : [ { "error_code" : "AgentArts.05001003" }, { "error_msg" : "请求参数不正确" } ] } ``` **状态码：500** **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 500表示内部服务器错误。 ``` { "error_code" : "AgentArts.05005000", "error_msg" : "内部服务器错误" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 200表示成功，其他值表示失败，具体参见错误码文档。 | | 400 | **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 400表示请求参数不正确。 | | 403 | **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 403表示权限不足，拒绝访问。 | | 500 | **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 500表示内部服务器错误。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。