---
title: "Observe on Volcengine"
---

VeADK reports tracing data to Volcengine platforms through different exporters. This page covers the integration steps for three platforms: CozeLoop, APMPlus, and TLS. For what each span attribute means, see [Span Attributes](/en/docs/framework/span-attributes).

## Shared Configuration

All three platforms share the same `model` and `volcengine` configuration; only the `observability` subtree differs. The shared part is shown below once—each platform section then shows only its own `observability` config:

```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
```

The integration code is also nearly identical: construct the platform's exporter, pass it to `OpentelemetryTracer`, and attach the tracer to your agent.

## CozeLoop Platform

After connecting a VeADK agent to CozeLoop, you can observe its traces with CozeLoop's Trace feature, or evaluate the agent with its evaluation feature.

### Preparation

Fill in the cozeloop attributes under the `observability` field of `config.yaml`:

- `endpoint`: Fixed to `https://api.coze.cn/v1/loop/opentelemetry/v1/traces`
- `api_key`: The CozeLoop access key. Personal access tokens, OAuth access tokens, and service access tokens are supported. To obtain one, see [Configure a Personal Access Token](https://loop.coze.cn/open/docs/cozeloop/authentication-for-sdk#05d27a86).
- `service_name`: The CozeLoop workspace ID. After logging in, switch in the top-left corner to the target workspace; the segment after `space` in the URL is the workspace ID. For example, in `https://loop.coze.cn/console/enterprise/personal/space/739XXXXXXXX092/pe/prompts`, **739XXXXXXXX092** is the workspace ID.

![CozeLoop workspace](/assets/images/observation/coze-spaceid.png)

```yaml title="config.yaml (observability subtree)"
observability:
  opentelemetry:
    cozeloop:
      endpoint: https://api.coze.cn/v1/loop/opentelemetry/v1/traces
      api_key: your api_key
      service_name: your cozeloop space id
```

### Integration Code

```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"))
```

### Result

```bash
python agent.py
```

![CozeLoop console](/assets/images/observation/coze-console.png)

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

## APMPlus Platform

Define an APMPlus data exporter to connect your agent's trace and metrics data to the Volcengine APMPlus platform.

### Preparation

Fill in the apmplus attributes under the `observability` field of `config.yaml`:

- `endpoint`: The APMPlus access point, e.g. `http://apmplus-cn-beijing.volces.com:4317`
- `api_key`: A valid application key
- `service_name`: The service name, which can be modified as needed

```yaml title="config.yaml (observability subtree)"
observability:
  opentelemetry:
    apmplus:
      endpoint: http://apmplus-cn-beijing.volces.com:4317
      api_key: your api_key
      service_name: apmplus_veadk_pj
```

### Integration Code

```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"))
```

### Result

Run the code above locally. The APMPlus tracer records the invocation of each node of the agent's execution and uploads metrics to cloud storage:

```bash
python agent.py
```

![APMPlus console](/assets/images/observation/apm-console.png)

Session information:

![APMPlus session](/assets/images/observation/apm-session.png)

Trace information:

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

Model metrics information:

![APMPlus metrics](/assets/images/observation/apm-metrics.png)

## TLS Platform

Define a TLS data exporter to connect your agent's execution traces to Volcengine Log Service (TLS) and view them in the TLS observation module.

### Preparation

Fill in the tls attributes under the `observability` field of `config.yaml`:

```yaml title="config.yaml (observability subtree)"
observability:
  opentelemetry:
    tls:
      endpoint: https://tls-cn-beijing.volces.com:4318/v1/traces
      service_name: tp_pj
      region: cn-beijing
```

### Integration Code

TLS integration takes two steps: first use the `VeTLS` client to create a log project and tracing instance, then use `TLSExporter` to report data.

```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. Create the log project and tracing instance
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. Report tracing data with TLSExporter
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"))
```

### Result

Run the code above locally to trigger the creation of the TLS Project and Topic and record the invocation of each node of the agent's execution:

```bash
python agent.py
```

![Console output](/assets/images/observation/tls-console.png)

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