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 and model configuration, then set the environment variables below before starting Python. Replace placeholders with accessible resources and valid credentials

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

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

app.py

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:

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.

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.

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

export ENABLE_COZELOOP=true

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

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

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

When to use

Prerequisites

Usage

Parameters

Constructor parameters

Cozeloop connection config

Verification and troubleshooting

​When to use

​Prerequisites

​Usage

​Parameters

​Constructor parameters

​Cozeloop connection config

​Verification and troubleshooting

When to use

Prerequisites

Usage

Parameters

Constructor parameters

Cozeloop connection config

Verification and troubleshooting