> ## 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.

# APMPlus

`APMPlusExporter` reports span data to the Volcengine APMPlus platform over OTLP (gRPC). Beyond traces, its built-in metrics uploader collects model invocation counts, token usage, operation duration, exception counts, and tool latency, writing them to APMPlus metrics dashboards.

## When to use

* You want unified trace observation for your agent on Volcengine APMPlus;
* You need model-level metrics such as token consumption, latency, and error rate;
* You need cost tracking and performance monitoring in production.

## Usage

```python lines theme={null}
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())

asyncio.run(runner.run(messages="How is the weather in Beijing?", session_id="session_id_demo"))
```

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

```python lines theme={null}
from veadk.tracing.telemetry.exporters.apmplus_exporter import (
    APMPlusExporter,
    APMPlusExporterConfig,
)

exporter = APMPlusExporter(
    config=APMPlusExporterConfig(
        endpoint="http://apmplus-cn-beijing.volces.com:4317",
        app_key="your-apmplus-app-key",
        service_name="apmplus_veadk_demo",
    )
)
```

## Parameters

### Constructor parameters

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

| Parameter | Type | Default | Description |
| :- | :- | :- | :- |
| `config` | `APMPlusExporterConfig` | Read from environment variables | APMPlus connection and authentication config. |
| `resource_attributes` | `dict` | `{}` | Resource attributes attached to spans; the exporter merges in `service.name` automatically. |
| `headers` | `dict` | `{}` | Extra request headers; the exporter merges in the auth header `x-byteapm-appkey` automatically. |

### APMPlus connection config

`config` is an `APMPlusExporterConfig`; each field defaults from `APMPlusConfig`, with the following environment variables:

| Config | Environment variable | Type | Default | Description |
| :- | :- | :- | :- | :- |
| `endpoint` | `OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT` | `str` | `http://apmplus-cn-beijing.volces.com:4317` | APMPlus OTLP endpoint (gRPC). |
| `app_key` | `OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY` | `str` | Fetches an APMPlus token automatically when unset | Application key used for authentication. |
| `service_name` | `OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME` | `str` | `veadk_tracing` | Service name shown in the APMPlus console to identify the source. |

<Note>
  When `app_key` is not provided via environment variable, the exporter fetches an APMPlus token automatically through Volcengine authentication, so valid Volcengine credentials are required. The `endpoint` connects over gRPC without transport encryption.
</Note>

## Environment variables

```bash lines theme={null}
export OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT="http://apmplus-cn-beijing.volces.com:4317"
export OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY="your-apmplus-app-key"
export OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME="apmplus_veadk_demo"
```

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

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

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