Creates an online Trace Span export task.

Request description

Server-side Monitoring has been deployed in multiple regions around the world to provide you with a more stable and low-latency access experience. You can refer to the Service addresses topic to choose the most suitable access point based on your business location.

Request method: POST

Request URL: https://apmplus-server.cn-beijing.volcengineapi.com?Action=CreateExportTask&Version=2024-07-30

Request parameters

The following table lists only the request parameters specific to this API and some common parameters. For details, see Common parameters.

Parameters	Type	Required	Sample value	Description
Action	String	Yes	CreateExportTask	The API name. The current API name is CreateExportTask.
Version	String	Yes	2024-07-30	The API version. The current API version is 2024-07-30.
Name	String	Yes	OnlineExportTaskA	Task name. Must start with a letter or a Chinese character, and may contain digits and underscores (_). Length limit: 1 to 50 characters.
Description	String	Yes	Online export task example	Task description. At most 200 characters.
TaskType	Integer	Yes	0	Task type. Value: 0, online task.
StartAt	Long	Yes	1672502400000	Timestamp of the task start time, measured in milliseconds.
EndAt	Long	Yes	1675180799000	Timestamp for the task end time, measured in milliseconds.
SpanFilter	Object of SpanFilter	Yes	{"ProjectName":"default","Conditions":[]}	Span filter criteria.
ExportTarget	Integer	Yes	2	Target platform for export data. Values: 2: AgentKit evaluation platform 3: DataFinder evaluation platform
EvaluationConfig	Object of EvaluationConfig	Yes	{"WorkspaceId":"ws-12345","IsNewEvaluationSet":true,"EvaluationSetName":" EvaluationSetA","ExportType":0,"FieldSchemas":[]}	Evaluation configuration.
ExportSpanParam	Object of ExportSpanParam	Yes	{"ExportFormat":"mapping","FieldMappings":[{"TraceFieldKey":"trace_id","TraceFieldJsonPath":"$.trace_id","FieldSchema":{"Name":"trace_id","ContentType":"Text","IsRequired":true}}]}	Export Span configuration.
TaskConfig	Object of TaskConfig	Yes	{"DataLimit":10000,"IsCycle":true,"CycleInterval":1,"CycleTimeUnit":"day","CycleDataLimit":100,"CycleStartAt":"2030-01-01","CycleEndAt":"2030-01-02"}	Task configuration information.

SpanFilter

Parameters	Type	Required	Sample value	Description
ProjectName	String	No	default	The project name. tip If not configured, it applies to all projects, and this field is not returned in the response.

EvaluationConfig

Parameters	Type	Required	Sample value	Description
ExportType	Integer	No	0	Export method. Values: 0: Append (default value) 1: Overwrite
WorkspaceId	String	No	ws-12345	Workspace ID of evaluation platform.
FieldSchemas	Array of FieldSchema	No	[{"Name":"trace_id","Description":"Trace ID","ContentType":"Text","IsRequired":true}]	Field structure list of the evaluation set.
EvaluationSetId	String	No	eval-set-67890	Existing evaluation set ID. Description This parameter is required when IsNewEvaluationSet is set to false.
EvaluationSetName	String	No	Trace Evaluation Set	Name of the new evaluation set. Description This parameter is required when IsNewEvaluationSet is set to true.
IsNewEvaluationSet	Boolean	No	true	Whether to create a new evaluation set. Values: true: Create false: Do not create (default value)

FieldSchema

Parameters	Type	Required	Sample value	Description
Name	String	No	trace_id	Field name.
IsRequired	Boolean	No	true	Whether the field is required. Values: true: Required false: Optional (default value)
TextSchema	String	No	{"type":"string"}	JSON Schema definition for text fields.
ContentType	String	No	Text	Field content type.
Description	String	No	Trace ID	Field description.
DefaultDisplayFormat	String	No	plain_text	Default display format for fields.

ExportSpanParam

Parameters	Type	Required	Sample value	Description
ExportFormat	String	Yes	mapping	Export format. Values: mapping: Export according to field mapping rules custom_template: Export according to custom template structure span_detail: Export according to Span details
FieldMappings	Array of FieldMappings	No	[{"TraceFieldKey":"trace_id","TraceFieldJsonPath":"$.trace_id","FieldSchema":{"Name":"trace_id","ContentType":"Text","IsRequired":true}}]	Field mapping. tip This parameter is required only when ExportFormat is set to mapping.
CustomTemplate	String	No	{"trace_id":"{{.TraceId}}"}	Custom export template. tip This parameter is required only when ExportFormat is set to custom_template.

FieldMappings

Parameters	Type	Required	Sample value	Description
FieldSchema	Object of FieldSchema	No	{"Name":"trace_id","Description":"Trace ID","ContentType":"Text","IsRequired":true}	Target evaluation set field structure.
TraceFieldKey	String	No	trace_id	Name of the Trace field. Sample value: GenAIInput: The field containing large model input content GenAIOutput: The field containing large model input content trace_id: Trace identifier span_id: Identifier for a single call unit tags.type: Type field in Span tags
TraceFieldJsonPath	String	No	$.trace_id	JSON path of the trace field.

TaskConfig

Parameters	Type	Required	Sample value	Description
IsCycle	Boolean	No	true	Whether the task runs in a cycle. Values: true: Cyclic false: Non-cyclic (default value)
DataLimit	Long	No	10,000	Upper data limit.
CycleEndAt	String	No	3-14:00:00	Cycle window end time. Example: 0-HH:mm:ss: Daily cycle D-HH:mm:ss: Weekly cycle, where D represents the day of the week, ranging from 1 to 7, corresponding to Monday to Sunday. tip This parameter is required only when IsCycle is set to true.
CycleStartAt	String	No	1-14:00:00	Cycle window start time. Example: 0-HH:mm:ss: Daily cycle D-HH:mm:ss: Weekly cycle, where D represents the day of the week, ranging from 1 to 7, corresponding to Monday to Sunday. tip This parameter is required only when IsCycle is set to true.
CycleInterval	Long	No	1	Cycle interval. When CycleTimeUnit is set to day, it means the task runs every specified number of days. When CycleTimeUnit is set to week, it means the task runs every specified number of weeks. tip This parameter is required only when IsCycle is set to true.
CycleTimeUnit	String	No	week	Cycle time unit. Values: day: Day week: Week tip This parameter is required only when IsCycle is set to true.
CycleDataLimit	Long	No	100	Single-cycle data volume.

Sample request

Response parameters

Parameters	Type	Sample value	Description
Id	String	1	Task ID.
Name	String	OnlineExportTaskA	Task name.
EndAt	Long	1675180799000	Timestamp for the task end time, measured in milliseconds.
Status	Integer	3	Task status. Values: 0: Pending 1: Running 2: Paused 3: Completed 4: Deleted 5: Failed
StartAt	Long	1672502400000	Timestamp of the task start time, measured in milliseconds.
TaskType	Integer	0	Task type. Value: 0, online task.
CreatedAt	String	2023-01-01T00:00:00Z	Creation time.
CreatedBy	String	zhangsan	Username of the task creator.
UpdatedAt	String	2023-01-01T01:00:00Z	Update time.
UpdatedBy	String	lisi	Username of the last operator who updated the task.
SpanFilter	Object of SpanFilter	{"ProjectName":"default","Conditions":[]}	Span filter criteria.
TaskConfig	Object of TaskConfig	{"DataLimit":10000,"IsCycle":true,"CycleInterval":1,"CycleTimeUnit":"day","CycleDataLimit":100,"CycleStartAt":"0-00:00:00","CycleEndAt":"0-23:59:59"}	Task configuration information.
TaskDetail	Object of TaskDetail	{"SuccessCount":950,"FailureCount":50,"TotalCount":1000}	Task execution details.
Description	String	Online export task example	Task description.
ExportTarget	Integer	2	Target platform for export data. Values: 0: Local file 1: CozeLoop 2: AgentKit evaluation platform 3: DataFinder evaluation platform
ExportSpanParam	Object of ExportSpanParam	{"ExportFormat":"mapping","FieldMappings":[{"TraceFieldKey":"trace_id","TraceFieldJsonPath":"$.trace_id","FieldSchema":{"Name":"trace_id","ContentType":"Text","IsRequired":true}}]}	Export Span configuration.
EvaluationConfig	Object of EvaluationConfig	{"WorkspaceId":"ws-12345","IsNewEvaluationSet":true,"EvaluationSetName":"EvaluationSetA","ExportType":0,"FieldSchemas":[]}	Evaluation configuration.

SpanFilter

Parameters	Type	Sample value	Description
ProjectName	String	default	The project name. tip If not configured, it applies to all projects, and this field is not returned in the response.

TaskConfig

Parameters	Type	Sample value	Description
IsCycle	Boolean	true	Whether the task runs in a cycle. Values: true: Cyclic false: Non-cyclic (default value)
DataLimit	Long	10,000	Upper data limit.
CycleEndAt	String	3-14:00:00	Cycle window end time. Example: 0-HH:mm:ss: Daily cycle D-HH:mm:ss: Weekly cycle, where D represents the day of the week, ranging from 1 to 7, corresponding to Monday to Sunday. tip This parameter is required only when IsCycle is set to true.
CycleStartAt	String	1-14:00:00	Cycle window start time. Example: 0-HH:mm:ss: Daily cycle D-HH:mm:ss: Weekly cycle, where D represents the day of the week, ranging from 1 to 7, corresponding to Monday to Sunday. tip This parameter is required only when IsCycle is set to true.
CycleInterval	Long	1	Cycle interval. When CycleTimeUnit is set to day, it means the task runs every specified number of days. When CycleTimeUnit is set to week, it means the task runs every specified number of weeks. tip This parameter is required only when IsCycle is set to true.
CycleTimeUnit	String	week	Cycle time unit. Values: day: Day week: Week tip This parameter is required only when IsCycle is set to true.
CycleDataLimit	Long	100	Single-cycle data volume.

TaskDetail

Parameters	Type	Sample value	Description
TotalCount	Long	1,000	Total export volume.
FailureCount	Long	50	Failure count.
SuccessCount	Long	950	Success count.

ExportSpanParam

Parameters	Type	Sample value	Description
ExportFormat	String	mapping	Export format. Values: mapping: Export according to field mapping rules custom_template: Export according to custom template structure span_detail: Export according to Span details
FieldMappings	Array of FieldMappings	[{"TraceFieldKey":"trace_id","TraceFieldJsonPath":"$.trace_id","FieldSchema":{"Name":"trace_id","ContentType":"Text","IsRequired":true}}]	Field mapping. tip This parameter is required only when ExportFormat is set to mapping.
CustomTemplate	String	{"trace_id":"{{.TraceId}}"}	Custom export template. tip This parameter is required only when ExportFormat is set to custom_template.

FieldMappings

Parameters	Type	Sample value	Description
FieldSchema	Object of FieldSchema	{"Name":"trace_id","Description":"Trace ID","ContentType":"Text","IsRequired":true}	Target evaluation set field structure.
TraceFieldKey	String	trace_id	Name of the Trace field. Sample value: GenAIInput: The field containing large model input content GenAIOutput: The field containing large model input content trace_id: Trace identifier span_id: Identifier for a single call unit tags.type: Type field in Span tags
TraceFieldJsonPath	String	$.trace_id	JSON path of the trace field.

FieldSchema

Parameters	Type	Sample value	Description
Name	String	trace_id	Field name.
IsRequired	Boolean	true	Whether the field is required. Values: true: Required false: Optional (default value)
TextSchema	String	{"type":"string"}	JSON Schema definition for text fields.
ContentType	String	Text	Field content type.
Description	String	Trace ID	Field description.
DefaultDisplayFormat	String	plain_text	Default display format for fields.

EvaluationConfig

Parameter	Type	Sample value	Description
ExportType	Integer	0	Export method. Values: 0: Append (default value) 1: Overwrite
WorkspaceId	String	ws-12345	Workspace ID of evaluation platform.
FieldSchemas	Array of FieldSchema	[{"Name":"trace_id","Description":"Trace ID","ContentType":"Text","IsRequired":true}]	Field structure list of the evaluation set.
EvaluationSetId	String	eval-set-67890	Existing evaluation set ID. Description This parameter is required when IsNewEvaluationSet is set to false.
EvaluationSetName	String	Trace Evaluation Set	Name of the new evaluation set. Description This parameter is required when IsNewEvaluationSet is set to true.
IsNewEvaluationSet	Boolean	true	Whether to create a new evaluation set. Values: true: Create false: Do not create (default value)

Sample response

Error codes

If the API call returns an exception, you can troubleshoot by referring to the API error codes and the Public error codes below.

HTTP status codes	Error codes	Error messages	Description
500	ErrInternalServerError	We encountered an unexpected server error, please try again later.	Internal server error.

Application Performance Management Plus