Trace
├── 身份、时间、状态
├── 上下文
├── Trace 级特征
├── 用户反馈
└── Spans
├── 身份、父子关系、时间、状态
├── 输入和输出
├── 模型或工具信息
├── 错误
└── Span 级特征
trace和span的基本结构：
{
"$defs": {
"traceIdentity": {
"type": "object",
"required": ["trace_id", "start_time", "status", "spans"],
"properties": {
"trace_id": { "type": "string", "minLength": 1 },
"start_time": { "type": "string", "format": "date-time" },
"end_time": { "type": ["string", "null"], "format": "date-time" },
"status": { "$ref": "#/$defs/executionStatus" },
"spans": {
"type": "array",
"items": { "$ref": "#/$defs/span" }
}
}
},
"span": {
"type": "object",
"required": ["span_id", "type", "start_time", "status"],
"properties": {
"span_id": { "type": "string", "minLength": 1 },
"parent_span_id": { "type": ["string", "null"] },
"type": {
"enum": ["model_call", "tool_call", "retrieval",
"state_transition", "agent_call", "other"]
},
"start_time": { "type": "string", "format": "date-time" },
"end_time": { "type": ["string", "null"], "format": "date-time" },
"status": { "$ref": "#/$defs/executionStatus" }
}
}
}
}
1.subject
{
"subject": {
"type": "object",
"required": ["type", "id"],
"properties": {
"type": { "enum": ["trace", "span"] },
"id": { "type": "string", "minLength": 1 }
},
"additionalProperties": false
}
}
2. value
{
"value": {
"type": ["boolean", "integer", "number", "string", "array", "object", "null"]
}
}
3. value_status
{
"value_status": {
"type": "string",
"enum": ["known", "unknown", "not_applicable", "source_disabled"]
}
}
4. window
{
"window": {
"type": "object",
"required": ["start", "end"],
"properties": {
"start": { "type": "string", "format": "date-time" },
"end": { "type": "string", "format": "date-time" }
},
"additionalProperties": false
}
}
5. revision
{
"revision": {
"type": "object",
"required": ["feature_version", "producer_version"],
"properties": {
"feature_version": { "type": "string" },
"producer_version": { "type": "string" },
"evaluator_version": { "type": ["string", "null"] }
},
"additionalProperties": false
}
}
- provenance
{
"provenance": {
"type": "object",
"required": ["source_type", "source_id"],
"properties": {
"source_type": {
"enum": ["raw_trace", "derived", "evaluator", "human"]
},
"source_id": { "type": "string" },
"evidence_ref": { "type": ["string", "null"] }
},
"additionalProperties": false
}
}
feature:
{
"feature": {
"type": "object",
"required": [
"name", "subject", "value_status",
"window", "revision", "provenance"
],
"properties": {
"name": { "type": "string", "minLength": 1 },
"subject": { "$ref": "#/$defs/subject" },
"value": {},
"value_status": { "$ref": "#/$defs/valueStatus" },
"window": { "$ref": "#/$defs/timeWindow" },
"revision": { "$ref": "#/$defs/revision" },
"provenance": { "$ref": "#/$defs/provenance" }
},
"allOf": [{
"if": {
"properties": { "value_status": { "const": "known" } },
"required": ["value_status"]
},
"then": { "required": ["value"] }
}],
"additionalProperties": false
}
}
7.result
{
"result": {
"type": "object",
"required": ["status"],
"properties": {
"status": {
"enum": ["success", "error", "timeout", "cancelled", "unknown"]
},
"output_ref": { "type": ["string", "null"] },
"finish_reason": { "type": ["string", "null"] }
},
"additionalProperties": true
}
}
8.duration
{
"result": {
"type": "object",
"required": ["status"],
"properties": {
"status": {
"enum": ["success", "error", "timeout", "cancelled", "unknown"]
},
"output_ref": { "type": ["string", "null"] },
"finish_reason": { "type": ["string", "null"] }
},
"additionalProperties": true
}
}
9.error
{
"error": {
"type": ["object", "null"],
"required": ["type", "message"],
"properties": {
"type": { "type": "string" },
"code": { "type": ["string", "null"] },
"message": { "type": "string" },
"template": { "type": ["string", "null"] },
"recoverable": { "type": ["boolean", "null"] },
"recovered": { "type": ["boolean", "null"] },
"evidence_ref": { "type": ["string", "null"] }
},
"additionalProperties": true
}
}
10.model call
{
"model_call": {
"allOf": [{ "$ref": "#/$defs/spanBase" }],
"properties": {
"type": { "const": "model_call" },
"model": {
"type": "object",
"required": ["provider", "name"],
"properties": {
"provider": { "type": "string" },
"name": { "type": "string" },
"version": { "type": ["string", "null"] },
"input_tokens": { "type": ["integer", "null"], "minimum": 0 },
"output_tokens": { "type": ["integer", "null"], "minimum": 0 }
}
},
"input_ref": { "type": ["string", "null"] },
"output_ref": { "type": ["string", "null"] }
},
"required": ["model"]
}
}
11.tool call
{
"tool_call": {
"allOf": [{ "$ref": "#/$defs/spanBase" }],
"properties": {
"type": { "const": "tool_call" },
"tool": {
"type": "object",
"required": ["name", "invocation_id"],
"properties": {
"name": { "type": "string" },
"version": { "type": ["string", "null"] },
"invocation_id": { "type": "string" },
"arguments_ref": { "type": ["string", "null"] },
"result_ref": { "type": ["string", "null"] }
}
}
},
"required": ["tool"]
}
}
12.task intent
{
"task_intent": {
"type": "object",
"required": ["label", "value_status", "provenance"],
"properties": {
"label": { "type": ["string", "null"] },
"taxonomy_version": { "type": ["string", "null"] },
"confidence": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
"value_status": { "$ref": "#/$defs/valueStatus" },
"provenance": { "$ref": "#/$defs/provenance" }
}
}
}
13.user feedback
{
"user_feedback": {
"type": "array",
"items": {
"type": "object",
"required": ["feedback_id", "type", "timestamp", "provenance"],
"properties": {
"feedback_id": { "type": "string" },
"type": {
"enum": ["explicit_rejection", "correction",
"human_escalation", "positive", "other"]
},
"value": {},
"timestamp": { "type": "string", "format": "date-time" },
"related_span_id": { "type": ["string", "null"] },
"provenance": { "$ref": "#/$defs/provenance" }
}
}
}
}
一条简化的trace示例
{
"trace_id": "trace-20260915-001",
"start_time": "2026-09-15T10:00:00+08:00",
"end_time": "2026-09-15T10:00:04.800+08:00",
"duration_ms": 4800,
"status": "error",
"error": {
"type": "ToolExecutionError",
"code": "SEARCH_TIMEOUT",
"message": "search tool timed out after 3000 ms",
"template": "search tool timed out",
"recoverable": true,
"recovered": false,
"evidence_ref": "span:span-2"
},
"context": {
"entry_point": "IDE",
"deployment_version": "2026.09.15.1",
"model_version": "model-v3",
"task_intent": {
"label": "debugging",
"taxonomy_version": "intent-v2",
"confidence": 0.94,
"value_status": "known",
"provenance": {
"source_type": "evaluator",
"source_id": "intent-eval-18",
"evidence_ref": null
}
}
},
"spans": [
{
"span_id": "span-1",
"parent_span_id": null,
"type": "model_call",
"start_time": "2026-09-15T10:00:00.100+08:00",
"end_time": "2026-09-15T10:00:01.000+08:00",
"duration_ms": 900,
"status": "success",
"model": {
"provider": "example-provider",
"name": "example-model",
"version": "model-v3",
"input_tokens": 820,
"output_tokens": 110
}
},
{
"span_id": "span-2",
"parent_span_id": "span-1",
"type": "tool_call",
"start_time": "2026-09-15T10:00:01.100+08:00",
"end_time": "2026-09-15T10:00:04.100+08:00",
"duration_ms": 3000,
"status": "timeout",
"tool": {
"name": "search",
"version": "2.4.0",
"invocation_id": "tool-call-7",
"arguments_ref": "blob://tool-call-7/input",
"result_ref": null
}
}
],
"features": [
{
"name": "trace_is_error",
"subject": { "type": "trace", "id": "trace-20260915-001" },
"value": true,
"value_status": "known",
"window": {
"start": "2026-09-15T10:00:00+08:00",
"end": "2026-09-15T10:00:04.800+08:00"
},
"revision": {
"feature_version": "1.0.0",
"producer_version": "trace-normalizer-2.1.0",
"evaluator_version": null
},
"provenance": {
"source_type": "derived",
"source_id": "trace-status-rule-v1",
"evidence_ref": "span:span-2"
}
}
],
"user_feedback": []
}