观测与评测
数据追踪
火山引擎云平台提供了多种 Tracing 平台
VeADK 提供可观测（Tracing）的能力，用于记录 Agent 执行过程中的关键路径与中间状态。支持将 Trace 数据输出至本地文件，或通过不同的 Exporter 上报至火山引擎平台，包括 CozeLoop、APMPlus、TLS，有助于开发者进行调试、性能分析、行为追踪等任务。
本地观测
通过如下方式开启本地观测，并且在 runner 的运行函数中指定 save_tracing_data=True 来将运行时数据保存至本地：
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer
tracer = OpentelemetryTracer()
agent = Agent(tracers=[tracer])
session_id = "session_id"
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
prompt = "How is the weather like in Beijing? Besides, tell me which tool you invoked."
# 设置 `save_tracing_data` 来保存运行时的 Tracing 数据
asyncio.run(runner.run(messages=prompt, session_id=session_id, save_tracing_data=True))
print(f"Tracing file path: {tracer._trace_file_path}")
Tracing 保存后的文件格式样例如下：
[
{
"name": "execute_tool get_city_weather",
"span_id": 7791923691033028744,
"trace_id": 219596633571878926828580094409810266267,
"start_time": 1758693545943618000,
"end_time": 1758693545943896000,
"attributes": {
"gen_ai.system": "openai",
"gen_ai.system.version": "0.2.8",
"gen_ai.agent.name": "veAgent",
"openinference.instrumentation.veadk": "0.2.8",
"gen_ai.app.name": "veadk_default_app",
"gen_ai.user.id": "veadk_default_user",
"gen_ai.session.id": "session_id",
"agent_name": "veAgent",
"agent.name": "veAgent",
"app_name": "veadk_default_app",
"app.name": "veadk_default_app",
"user.id": "veadk_default_user",
"session.id": "session_id",
"cozeloop.report.source": "veadk",
"cozeloop.call_type": "",
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": "get_city_weather",
"gen_ai.tool.input": "{\"name\": \"get_city_weather\", \"description\": \"Retrieves the weather information of a given city. the args must in English\", \"parameters\": {\"city\": \"Beijing\"}}",
"gen_ai.tool.output": "{\"id\": \"call_opas0vkohuzcaevluv06sewk\", \"name\": \"get_city_weather\", \"response\": {\"result\": \"Sunny, 25°C\"}}",
"cozeloop.input": "{\"name\": \"get_city_weather\", \"description\": \"Retrieves the weather information of a given city. the args must in English\", \"parameters\": {\"city\": \"Beijing\"}}",
"cozeloop.output": "{\"id\": \"call_opas0vkohuzcaevluv06sewk\", \"name\": \"get_city_weather\", \"response\": {\"result\": \"Sunny, 25°C\"}}"
},
"parent_span_id": 7552931582864344016
},
{
"name": "call_llm",
"span_id": 7552931582864344016,
"trace_id": 219596633571878926828580094409810266267,
"start_time": 1758693533476592000,
"end_time": 1758693545956432000,
"attributes": {
"gen_ai.system": "openai",
"gen_ai.system.version": "0.2.8",
"gen_ai.agent.name": "veAgent",
"openinference.instrumentation.veadk": "0.2.8",
"gen_ai.app.name": "veadk_default_app",
"gen_ai.user.id": "veadk_default_user",
"gen_ai.session.id": "session_id",
"agent_name": "veAgent",
"agent.name": "veAgent",
"app_name": "veadk_default_app",
"app.name": "veadk_default_app",
"user.id": "veadk_default_user",
"session.id": "session_id",
"cozeloop.report.source": "veadk",
"cozeloop.call_type": "",
"gen_ai.request.model": "openai/doubao-seed-1.6-250615",
"gen_ai.request.type": "chat",
"gen_ai.request.functions.0.name": "get_city_weather",
"gen_ai.request.functions.0.description": "Retrieves the weather information of a given city. the args must in English",
"gen_ai.request.functions.0.parameters": "{'properties': {'city': {'type': <Type.STRING: 'STRING'>}}, 'required': ['city'], 'type': <Type.OBJECT: 'OBJECT'>}",
"gen_ai.response.model": "openai/doubao-seed-1.6-250615",
"gen_ai.response.stop_reason": "<no_stop_reason_provided>",
"gen_ai.response.finish_reason": "<no_finish_reason_provided>",
"gen_ai.operation.name": "chat",
"gen_ai.prompt.0.role": "user",
"gen_ai.prompt.0.content": "How is the weather like in Beijing? Besides, tell me which tool you invoked.",
"gen_ai.completion.0.role": "model",
"gen_ai.completion.0.tool_calls.0.id": "call_opas0vkohuzcaevluv06sewk",
"gen_ai.completion.0.tool_calls.0.type": "function",
"gen_ai.completion.0.tool_calls.0.function.name": "get_city_weather",
"gen_ai.completion.0.tool_calls.0.function.arguments": "{\"city\": \"Beijing\"}",
"gen_ai.usage.input_tokens": 630,
"gen_ai.usage.output_tokens": 497,
"gen_ai.usage.total_tokens": 1127
},
"parent_span_id": 772582603144924992
},
{
"name": "call_llm",
"span_id": 455911132604421388,
"trace_id": 219596633571878926828580094409810266267,
"start_time": 1758693545956907000,
"end_time": 1758693550432795000,
"attributes": {
"gen_ai.system": "openai",
"gen_ai.system.version": "0.2.8",
"gen_ai.agent.name": "veAgent",
"openinference.instrumentation.veadk": "0.2.8",
"gen_ai.app.name": "veadk_default_app",
"gen_ai.user.id": "veadk_default_user",
"gen_ai.session.id": "session_id",
"agent_name": "veAgent",
"agent.name": "veAgent",
"app_name": "veadk_default_app",
"app.name": "veadk_default_app",
"user.id": "veadk_default_user",
"session.id": "session_id",
"cozeloop.report.source": "veadk",
"cozeloop.call_type": "",
"gen_ai.request.model": "openai/doubao-seed-1.6-250615",
"gen_ai.request.type": "chat",
"gen_ai.request.functions.0.name": "get_city_weather",
"gen_ai.request.functions.0.description": "Retrieves the weather information of a given city. the args must in English",
"gen_ai.request.functions.0.parameters": "{'properties': {'city': {'type': <Type.STRING: 'STRING'>}}, 'required': ['city'], 'type': <Type.OBJECT: 'OBJECT'>}",
"gen_ai.response.model": "openai/doubao-seed-1.6-250615",
"gen_ai.response.stop_reason": "<no_stop_reason_provided>",
"gen_ai.response.finish_reason": "<no_finish_reason_provided>",
"gen_ai.operation.name": "chat",
"gen_ai.prompt.0.role": "user",
"gen_ai.prompt.0.content": "How is the weather like in Beijing? Besides, tell me which tool you invoked.",
"gen_ai.prompt.1.tool_calls.0.id": "call_opas0vkohuzcaevluv06sewk",
"gen_ai.prompt.1.tool_calls.0.type": "function",
"gen_ai.prompt.1.tool_calls.0.function.name": "get_city_weather",
"gen_ai.prompt.1.tool_calls.0.function.arguments": "{\"city\": \"Beijing\"}",
"gen_ai.prompt.2.role": "user",
"gen_ai.prompt.2.content": "{'result': 'Sunny, 25°C'}",
"gen_ai.completion.0.role": "model",
"gen_ai.completion.0.content": "The weather in Beijing is Sunny with a temperature of 25°C. The tool invoked is \"get_city_weather\".",
"gen_ai.usage.input_tokens": 690,
"gen_ai.usage.output_tokens": 175,
"gen_ai.usage.total_tokens": 865
},
"parent_span_id": 772582603144924992
},
{
"name": "agent_run [veAgent]",
"span_id": 772582603144924992,
"trace_id": 219596633571878926828580094409810266267,
"start_time": 1758693533476273000,
"end_time": 1758693550432953000,
"attributes": {
"gen_ai.operation.name": "agent",
"gen_ai.system": "openai",
"gen_ai.system.version": "0.2.8",
"gen_ai.agent.name": "veAgent",
"openinference.instrumentation.veadk": "0.2.8",
"gen_ai.app.name": "veadk_default_app",
"gen_ai.user.id": "veadk_default_user",
"gen_ai.session.id": "session_id",
"agent_name": "veAgent",
"agent.name": "veAgent",
"app_name": "veadk_default_app",
"app.name": "veadk_default_app",
"user.id": "veadk_default_user",
"session.id": "session_id",
"cozeloop.report.source": "veadk",
"cozeloop.call_type": ""
},
"parent_span_id": 13555911686149146924
},
{
"name": "invocation",
"span_id": 13555911686149146924,
"trace_id": 219596633571878926828580094409810266267,
"start_time": 1758693533476140000,
"end_time": 1758693550432995000,
"attributes": {
"gen_ai.operation.name": "chain",
"gen_ai.system": "openai",
"gen_ai.system.version": "0.2.8",
"gen_ai.agent.name": "veAgent",
"openinference.instrumentation.veadk": "0.2.8",
"gen_ai.app.name": "veadk_default_app",
"gen_ai.user.id": "veadk_default_user",
"gen_ai.session.id": "session_id",
"agent_name": "veAgent",
"agent.name": "veAgent",
"app_name": "veadk_default_app",
"app.name": "veadk_default_app",
"user.id": "veadk_default_user",
"session.id": "session_id",
"cozeloop.report.source": "veadk",
"cozeloop.call_type": "",
"gen_ai.usage.total_tokens": 1992
},
"parent_span_id": null
}
]
火山引擎云观测
通过设置不同的云端上报器exporter，可以将观测数据上传到对应平台：
- CozeLoop 平台：
CozeLoopExporter - APMPlus 平台：
APMPlusExporter - TLS 平台：
TLSExporter
示例：配置多个云端 exporter
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.demo_tools import get_city_weather
from veadk.tracing.telemetry.exporters.apmplus_exporter import APMPlusExporter
from veadk.tracing.telemetry.exporters.cozeloop_exporter import CozeloopExporter
from veadk.tracing.telemetry.exporters.tls_exporter import TLSExporter
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer
# 通过加载不同的 exporters 来上报到不同云平台
exporters = [CozeloopExporter(), APMPlusExporter(), TLSExporter()]
tracer = OpentelemetryTracer(exporters=exporters)
agent = Agent(tools=[get_city_weather], tracers=[tracer])
session_id = "session_id"
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
prompt = "How is the weather like in Beijing? Besides, tell me which tool you invoked."
# 设置 `save_tracing_data` 来保存运行时的 Tracing 数据
asyncio.run(runner.run(messages=prompt, session_id=session_id, save_tracing_data=True))
print(f"Tracing file path: {tracer._trace_file_path}")
Cozeloop 平台可视化界面：
APMPlus 平台可视化界面：
TLS 平台可视化界面：
