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