根据指定查询条件导出 Trace Span 数据，并写入指定评测平台或返回本地导出数据。

请求说明

应用性能监控已在全球多个地域部署服务，旨在为您提供更稳定、低延迟的访问体验。您可以通过查阅服务地址文档，根据业务所在地选择最合适的接入点。

请求方式：POST

请求地址：https://apmplus-server.cn-beijing.volcengineapi.com?Action=ExportTraceSpan&Version=2024-07-30

请求参数

下方仅列出该接口特有的请求参数和部分公共参数，更多详细信息参见公共参数。

参数	类型	是否必选	示例值	描述
Action	String	是	ExportTraceSpan	接口名称。当前 API 的名称为 ExportTraceSpan。
Version	String	是	2024-07-30	接口版本。当前 API 的版本为 2024-07-30。
SpanListParam	Object of SpanListParam	是	{"StartTime":1672502400,"EndTime":1672506000,"SpanIds":["0af7651916cd43dd8448eb211c80319c"]}	待导出的 Span 查询条件。
ExportSpanParam	Object of ExportSpanParam	是	{"ExportFormat":"mapping","FieldMappings":[{"TraceFieldKey":"trace_id","TraceFieldJsonPath":"$.trace_id","FieldSchema":{"Name":"trace_id","ContentType":"Text","IsRequired":true}}]}	Span 导出格式与字段映射配置。
ExportTarget	Integer	是	2	导出目标。取值： 2：AgentKit 评测 3：DataFinder 评测
EvaluationConfig	Object of EvaluationConfig	是	{"WorkspaceId":"ws-12345","IsNewEvaluationSet":true,"EvaluationSetName":" EvaluationSetA","ExportType":0,"FieldSchemas":[]}	统一评测平台配置。
ProjectName	String	是	default	项目名称。
CozeToken	String	是	pat_xxx	访问 CozeLoop 的授权令牌。说明当查询 CozeLoop时，必须配置此参数。

SpanListParam

参数	类型	是否必选	示例值	描述
Limit	Integer	否	100	导出数量上限。
Order	String	否	DESC	排序方向。取值： ASC：升序排列 DESC：降序排列
Offset	Integer	否	0	导出数据偏移量。
EndTime	Long	否	1672506000	查询结束时间戳，单位：秒。
Filters	Array of FilterConditionV2	否	[{"Key":"service_name","Op":"in","Values":["checkout-service"]}]	Span 过滤条件。
OrderBy	String	否	start_time_millisecond	排序字段。示例： start_time_millisecond：Span 的开始时间 duration_microseconds：Span 的持续时长
SpanIds	Array of String	否	["0af7651916cd43dd8448eb211c80319c"]	指定导出的 Span ID 列表。
StartTime	Long	否	1672502400	查询开始时间戳，单位：秒。
MaxCallCostMillisecond	Long	否	1000	调用耗时上限，单位：毫秒。说明取值为 0 时，表示不限制该参数。
MinCallCostMillisecond	Long	否	0	调用耗时下限。单位：毫秒。说明取值为 0 时，表示不限制该参数。

FilterConditionV2

参数	类型	是否必选	示例值	描述
Op	String	否	in	过滤条件操作符。取值： gt：大于 gte：大于等于 lt：小于 lte：小于等于 eq：等于 neq：不等于 in：包含 not_in：不包含 lk：模糊匹配特定模式的数据 nlk：排除模糊匹配的数据
Key	String	否	session_id	过滤条件 Key。
Values	Array of String	否	["sess_001"]	过滤条件值。

ExportSpanParam

参数	类型	是否必选	示例值	描述
ExportFormat	String	否	mapping	导出格式。取值： mapping：字段映射 custom_template：自定义模板 span_detail：Span 详情
FieldMappings	Array of FieldMappings	否	[{"TraceFieldKey":"trace_id","TraceFieldJsonPath":"$.trace_id","FieldSchema":{"Name":"trace_id","ContentType":"Text","IsRequired":true}}]	字段映射。说明仅在 ExportFormat取值为 mapping 时，需要配置此参数。
CustomTemplate	String	否	{"trace_id":"{{.TraceId}}"}	自定义导出模板。说明仅在 ExportFormat取值为 custom_template 时，需要配置此参数。

FieldMappings

参数	类型	是否必选	示例值	描述
FieldSchema	Object of FieldSchema	否	{"Name":"trace_id","Description":"Trace ID","ContentType":"Text","IsRequired":true}	目标评测集字段结构。
TraceFieldKey	String	否	trace_id	Trace 字段名称。示例值： GenAIInput：大模型输入内容字段 GenAIOutput：大模型输出内容字段 trace_id：链路追踪的唯一标识符 span_id：单个调用单元的唯一标识符 tags.type：Span 标签中的类型字段
TraceFieldJsonPath	String	否	$.trace_id	Trace 字段的 JSON 路径。

FieldSchema

参数	类型	是否必选	示例值	描述
Name	String	否	trace_id	字段名称。
IsRequired	Boolean	否	true	字段是否必填。
TextSchema	String	否	{"type":"string"}	文本字段的 JSON Schema 定义。
ContentType	String	否	Text	字段内容类型。
Description	String	否	Trace ID	字段描述。
DefaultDisplayFormat	String	否	plain_text	字段默认展示格式。

EvaluationConfig

参数	类型	是否必选	示例值	描述
ExportType	Integer	否	0	导出方式。取值： 0：追加 1：覆盖
WorkspaceId	String	否	ws-12345	评测平台工作空间 ID。
FieldSchemas	Array of FieldSchema	否	[{"Name":"trace_id","Description":"Trace ID","ContentType":"Text","IsRequired":true}]	评测集字段结构列表。
EvaluationSetId	String	否	eval-set-67890	已有评测集 ID。说明当 IsNewEvaluationSet取值为 false 时，必须配置此参数。
EvaluationSetName	String	否	Trace Evaluation Set	新评测集名称。说明当 IsNewEvaluationSet取值为 true 时，必须配置此参数。
IsNewEvaluationSet	Boolean	否	true	是否创建新的评测集。取值： true：创建 false：不创建

请求示例

POST https://apmplus-server.cn-beijing.volcengineapi.com?Action=ExportTraceSpan&Version=2024-07-30​
{​
    "SpanListParam": {​
        "StartTime": 1672502400,​
        "EndTime": 1672506000,​
        "SpanIds": [​
            "0af7651916cd43dd8448eb211c80319c"​
        ]​
    },​
    "ExportSpanParam": {​
        "ExportFormat": "mapping",​
        "FieldMappings": [​
            {​
                "TraceFieldKey": "trace_id",​
                "TraceFieldJsonPath": "$.trace_id",​
                "FieldSchema": {​
                    "Name": "trace_id",​
                    "ContentType": "Text",​
                    "IsRequired": true​
                }​
            }​
        ]​
    },​
    "ExportTarget": 2,​
    "EvaluationConfig": "{\"WorkspaceId\":\"ws-12345\",\"IsNewEvaluationSet\":true,\"EvaluationSetName\":\"\nEvaluationSetA\",\"ExportType\":0,\"FieldSchemas\":[]}",​
    "ProjectName": "default",​
    "CozeToken": "pat_xxx"​
}

返回参数

参数	类型	示例值	描述
Items	Array of ExportTraceSpanItem	[{"FieldList":[],"status":"success"}]	导出的数据项列表。
ItemCount	Integer	100	成功生成的导出数据项数量。
EvaluationSetId	String	eval-set-67890	写入的评测集 ID。
EvaluationSetName	String	Trace Evaluation Set	写入的评测集名称。

ExportTraceSpanItem

参数	类型	示例值	描述
status	String	success	数据项导出状态。
FieldList	Array of FieldData	[{"Key":"trace_id","Name":"trace_id","Content":{"ContentType":"Text","Text":"0af7651916cd43dd8448eb211c80319c"}}]	数据项字段列表。

FieldData

参数	类型	示例值	描述
Key	String	trace_id	字段唯一标识。
Name	String	trace_id	字段名称。
Content	Object of FieldContent	{"ContentType":"Text","Text":"0af7651916cd43dd8448eb211c80319c"}	字段内容。

FieldContent

参数	类型	示例值	描述
Text	String	0af7651916cd43dd8448eb211c80319c	文本内容。
ContentType	String	Text	字段内容类型。

返回示例

{​
    "Result": {​
        "EvaluationSetId": "eval-set-67890",​
        "EvaluationSetName": "Trace Evaluation Set",​
        "ItemCount": 100,​
        "Items": []​
    },​
    "ResponseMetadata": {​
        "RequestId": "20230604110420****100232280022D31",​
        "Action": "ExportTraceSpan",​
        "Version": "2024-07-30",​
        "Service": "apmplus_server",​
        "Region": "cn-north-1"​
    }​
}

错误码

若接口调用返回异常，可参考以下接口错误码和公共错误码进行故障排查。

HTTP 状态码	错误码	错误信息	说明
500	ErrInternalServerError	We encountered an unexpected server error, please try again later.	服务器内部错误。

应用性能监控全链路版