@agent-native/otel
OpenTelemetry SDK wiring for Agent-Native apps. It builds a meter provider and a tracer provider with OTLP exporters and registers them with @agent-native/core through registerObservabilityProvider().
It does nothing unless an OTLP endpoint is set, so apps can depend on it unconditionally. Apps scaffolded from first-party templates already include it; to add it to another app:
pnpm add @agent-native/otel
Then start it from a server plugin:
// server/plugins/otel.ts
import { defineNitroPlugin } from "@agent-native/core/server";
import { startAgentNativeOtel } from "@agent-native/otel";
export default defineNitroPlugin(() => {
startAgentNativeOtel();
});
Configuration uses the standard OpenTelemetry variables:
| Variable | Effect |
|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT | Turns both signals on; /v1/metrics and /v1/traces are appended |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT / _TRACES_ENDPOINT | Turns on that signal only, at this exact URL |
OTEL_EXPORTER_OTLP_HEADERS | Headers sent with every export, e.g. Authorization=Bearer%20… |
OTEL_SERVICE_NAME | service.name |
OTEL_RESOURCE_ATTRIBUTES | Extra resource attributes, e.g. deployment.environment.name |
OTEL_TRACES_SAMPLER / _ARG | Trace sampling, e.g. parentbased_traceidratio / 0.01 |
OTEL_METRICS_EXPORTER / OTEL_TRACES_EXPORTER | otlp (default) or none; any other value fails startup |
OTEL_EXPORTER_OTLP_PROTOCOL (and per-signal overrides) | http/protobuf only; any other value fails startup |
Metrics use cumulative temporality with a random service.instance.id per process, so each process is its own series. On serverless runtimes (Netlify, AWS Lambda, Vercel, Cloudflare), as @agent-native/core detects them, core force-flushes both providers after responses, capped at 2 seconds, with metrics exported at most once every 10 seconds per process; elsewhere metrics export every 60 seconds.