---
title: "在火山引擎观测"
---

VeADK 通过不同的 Exporter 把 Tracing 数据上报至火山引擎平台。本页介绍 CozeLoop、APMPlus、TLS 三个平台的接入方式。各 Span 的字段含义见[埋点字段说明](/cn/docs/framework/span-attributes)。

## 共享配置

三个平台共用相同的 `model` 与 `volcengine` 配置，只是 `observability` 子树不同。下面是共享部分，后续各平台只展示各自的 `observability` 配置：

```yaml title="config.yaml"
model:
  agent:
    provider: openai
    name: doubao-seed-1-8-251228
    api_base: https://ark.cn-beijing.volces.com/api/v3
    api_key: your api_key

volcengine:
  access_key: your ak
  secret_key: your sk
```

接入代码也基本一致：构造对应平台的 Exporter，交给 `OpentelemetryTracer`，再挂载到 Agent 上。

## CozeLoop 平台

将 VeADK 开发的智能体接入扣子罗盘后，你可以通过扣子罗盘的 Trace 功能观测调用链路，或通过其评测功能对 Agent 进行评测。

### 准备工作

在 `config.yaml` 的 `observability` 字段中填写 cozeloop 属性：

- `endpoint`：固定为 `https://api.coze.cn/v1/loop/opentelemetry/v1/traces`
- `api_key`：扣子罗盘访问密钥，支持个人访问令牌、OAuth 访问令牌和服务访问令牌。获取方式参见[配置个人访问令牌](https://loop.coze.cn/open/docs/cozeloop/authentication-for-sdk#05d27a86)。
- `service_name`：扣子罗盘工作空间 ID。登录扣子罗盘后，在左上角切换到目标工作空间，在 URL 中 `space` 之后的片段即为工作空间 ID。例如 `https://loop.coze.cn/console/enterprise/personal/space/739XXXXXXXX092/pe/prompts` 中，**739XXXXXXXX092** 为工作空间 ID。

![cozeloop 空间](/assets/images/observation/coze-spaceid.png)

```yaml title="config.yaml（observability 子树）"
observability:
  opentelemetry:
    cozeloop:
      endpoint: https://api.coze.cn/v1/loop/opentelemetry/v1/traces
      api_key: your api_key
      service_name: your cozeloop space id
```

### 接入代码

```python title="agent.py"
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.cozeloop_exporter import CozeloopExporter
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

exporters = [CozeloopExporter()]
tracer = OpentelemetryTracer(exporters=exporters)

agent = Agent(tools=[get_city_weather], tracers=[tracer])

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())

prompt = "How is the weather like in Beijing? Besides, tell me which tool you invoked."

asyncio.run(runner.run(messages=prompt, session_id="session_id_pj"))
```

### 效果展示

```bash
python agent.py
```

![cozeloop 控制台](/assets/images/observation/coze-console.png)

![cozeloop trace](/assets/images/observation/coze-trace.png)

## APMPlus 平台

定义 APMPlus 数据导出器，即可将智能体的 Trace 与 Metrics 数据接入火山引擎 APMPlus 平台。

### 准备工作

在 `config.yaml` 的 `observability` 字段中填写 apmplus 属性：

- `endpoint`：APMPlus 接入点，例如 `http://apmplus-cn-beijing.volces.com:4317`
- `api_key`：有效的应用程序密钥
- `service_name`：服务名称，可按需修改

```yaml title="config.yaml（observability 子树）"
observability:
  opentelemetry:
    apmplus:
      endpoint: http://apmplus-cn-beijing.volces.com:4317
      api_key: your api_key
      service_name: apmplus_veadk_pj
```

### 接入代码

```python title="agent.py"
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.opentelemetry_tracer import OpentelemetryTracer

exporters = [APMPlusExporter()]
tracer = OpentelemetryTracer(exporters=exporters)

agent = Agent(tools=[get_city_weather], tracers=[tracer])

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())

prompt = "How is the weather like in Beijing? Besides, tell me which tool you invoked."

asyncio.run(runner.run(messages=prompt, session_id="session_id_pj"))
```

### 效果展示

本地运行上述代码，APMPlus 追踪器会记录 Agent 各节点的调用，并将 Metrics 上传至云端：

```bash
python agent.py
```

![apmplus 控制台](/assets/images/observation/apm-console.png)

会话信息：

![apmplus 会话](/assets/images/observation/apm-session.png)

Trace 信息：

![apmplus trace](/assets/images/observation/apm-trace.png)

模型指标信息：

![apmplus 指标](/assets/images/observation/apm-metrics.png)

## TLS 平台

定义 TLS 数据导出器，即可将智能体执行链路接入火山引擎日志服务 TLS，并在 TLS 观测模块中查看。

### 准备工作

在 `config.yaml` 的 `observability` 字段中填写 tls 属性：

```yaml title="config.yaml（observability 子树）"
observability:
  opentelemetry:
    tls:
      endpoint: https://tls-cn-beijing.volces.com:4318/v1/traces
      service_name: tp_pj
      region: cn-beijing
```

### 接入代码

TLS 接入分两步：先用 `VeTLS` 客户端创建日志项目与追踪实例，再用 `TLSExporter` 上报数据。

```python title="agent.py"
import asyncio
from os import getenv

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.tls_exporter import TLSExporter, TLSExporterConfig
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer
from veadk.integrations.ve_tls.ve_tls import VeTLS

# 1. 创建日志项目与追踪实例
ve_tls_client = VeTLS()
log_project_id = ve_tls_client.create_log_project("veadk_pj")
print(f"Created log project with ID: {log_project_id}")

trace_instance_name = getenv("OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME")
trace_instance = ve_tls_client.create_tracing_instance(log_project_id, trace_instance_name)
print(f"Created trace instance with ID: {trace_instance['TraceInstanceId']}")

# 2. 用 TLSExporter 上报 Tracing 数据
tls_exporter = TLSExporter(
    config=TLSExporterConfig(
        topic_id=trace_instance.get("TraceTopicId", trace_instance_name),
    )
)
tracer = OpentelemetryTracer(exporters=[tls_exporter])

agent = Agent(tools=[get_city_weather], tracers=[tracer])

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())

prompt = "How is the weather like in Beijing? Besides, tell me which tool you invoked."

asyncio.run(runner.run(messages=prompt, session_id="session_id_pj"))
```

### 效果展示

本地运行上述代码，会触发 TLS Project、Topic 的创建，并记录 Agent 各节点的调用：

```bash
python agent.py
```

![控制台打印](/assets/images/observation/tls-console.png)

![tls trace](/assets/images/observation/tls-trace.png)
