> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Cozeloop

`CozeloopExporter` reports span data to the Cozeloop platform over OTLP (HTTP). Once connected, you can observe traces with Cozeloop's trace feature or evaluate agents with its evaluation feature. Data is isolated by workspace (space).

## When to use

* You want to observe your agent's traces on Cozeloop;
* You want to analyze conversation quality and tool-usage effectiveness with Cozeloop's evaluation capabilities;
* You already have a Cozeloop workspace and access token.

## Prerequisites

Complete [installation](/productions/veadk/preview/en/get-started/installation) and [model configuration](/productions/veadk/preview/en/components/agent/model), then set the environment variables below before starting Python. Replace placeholders with accessible resources and valid credentials

<Warning>
  Cozeloop receives trace data. Specify an existing workspace ID where possible; omitting it attempts to create a default workspace using your token and requires permission to do so. Configuring an exporter does not create or run evaluation tasks
</Warning>

```bash lines theme={null}
export OBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT="https://api.coze.cn/v1/loop/opentelemetry/v1/traces"
export OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY="your-cozeloop-token"
export OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME="your-cozeloop-space-id"
```

## Usage

Save as `app.py` and run `python app.py`. The example uses existing resources and flushes pending traces after one model call

```python title="app.py" lines theme={null}
import asyncio

from veadk import Agent, Runner
from veadk.tracing.telemetry.exporters.cozeloop_exporter import CozeloopExporter
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

tracer = OpentelemetryTracer(exporters=[CozeloopExporter()])
agent = Agent(name="trace_demo", tracers=[tracer])
runner = Runner(agent=agent, app_name="trace_demo", user_id="demo-user")
response = asyncio.run(
    runner.run("Explain the purpose of an agent in one sentence", session_id="demo-session")
)
print(response)
tracer.force_export()
print("Trace ID:", tracer.trace_id)
```

You can also pass connection parameters explicitly via `CozeloopExporterConfig`:

```python lines theme={null}
import os

from veadk.tracing.telemetry.exporters.cozeloop_exporter import (
    CozeloopExporter,
    CozeloopExporterConfig,
)

exporter = CozeloopExporter(
    config=CozeloopExporterConfig(
        endpoint="https://api.coze.cn/v1/loop/opentelemetry/v1/traces",
        space_id=os.environ["OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME"],
        token=os.environ["OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY"],
    )
)
```

## Parameters

### Constructor parameters

`CozeloopExporter` carries its connection parameters in the `config` field of type `CozeloopExporterConfig`; when omitted, each field is read automatically from the corresponding environment variable.

| Parameter | Type | Default | Description |
| :- | :- | :- | :- |
| `config` | `CozeloopExporterConfig` | Read from environment variables | Cozeloop connection and authentication config. |
| `resource_attributes` | `dict` | `{}` | Resource attributes attached to spans. |
| `headers` | `dict` | `{}` | Extra request headers; the exporter merges in `cozeloop-workspace-id` and `authorization` automatically. |

### Cozeloop connection config

`config` is a `CozeloopExporterConfig`; each field defaults from `CozeloopConfig`, with the following environment variables:

| Config | Environment variable | Type | Default | Description |
| :- | :- | :- | :- | :- |
| `endpoint` | `OBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT` | `str` | `https://api.coze.cn/v1/loop/opentelemetry/v1/traces` | Cozeloop OTLP endpoint (HTTP). |
| `space_id` | `OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME` | `str` | Creates a default workspace automatically when unset | Workspace ID for data isolation. |
| `token` | `OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY` | `str` | `""` | Access token; supports personal access tokens, OAuth access tokens, and service access tokens. |

<Note>
  `space_id` is taken from the environment variable `OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME`; when unset, the exporter creates a default workspace automatically using `token` as the credential. After logging in to Cozeloop, the segment after `space` in the URL is the workspace ID.
</Note>

You can also let `Agent` attach the Cozeloop exporter automatically from an environment variable, without constructing it explicitly:

```bash lines theme={null}
export ENABLE_COZELOOP=true
```

<Tip>
  With `ENABLE_COZELOOP=true`, `Agent` creates an `OpentelemetryTracer` and attaches `CozeloopExporter` automatically, even when the agent provides no `tracers`.
</Tip>

## Verification and troubleshooting

Search for the run's Trace ID in the target backend. A successful model response does not prove trace delivery. If data is missing, check the endpoint and region, credential permissions, target resource, and whether `tracer.force_export()` ran before the process exited