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 content tracing is enabled, reasoning content in model output is labeled with the reasoning type to distinguish it from regular text, making it easier to inspect the reasoning process separately in APMPlus.

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

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:

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.

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.

Environment variables

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:

export ENABLE_APMPLUS=true

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

If a global TracerProvider already exists when OpentelemetryTracer is initialized, VeADK reuses that provider and automatically removes APMPlusExporter, because the existing provider is assumed to be responsible for APMPlus trace reporting. You can check this with the apmplus_managed_externally property; see Observability overview for details.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

When to use

Usage

Parameters

Constructor parameters

APMPlus connection config

Environment variables

​When to use

​Usage

​Parameters

​Constructor parameters

​APMPlus connection config

​Environment variables

When to use

Usage

Parameters

Constructor parameters

APMPlus connection config

Environment variables