Telemetry

Aether supports exporting OpenTelemetry GenAI traces and metrics. Configure telemetry in the top-level telemetry section of your settings file. Telemetry is disabled by default.

.aether/settings.json

{
  "telemetry": {
    "serviceName": "aether-production",
    "sampleRatio": 1.0,
    "captureContent": false,
    "traces": { "enabled": true },
    "metrics": { "enabled": true },
    "otlp": {
      "endpoint": "http://localhost:4318",
      "headers": {
        "authorization": "Bearer <token>"
      }
    }
  }
}

Aether sends OTLP over HTTP/Protobuf. Set otlp.endpoint to the collector’s base URL; Aether sends traces to /v1/traces and metrics to /v1/metrics. For providers that require signal-specific URLs, set otlp.tracesEndpoint or otlp.metricsEndpoint to override the derived URL for that signal. An endpoint is required whenever either signal is enabled (either the shared endpoint or the corresponding signal-specific override).

otlp.headers values support $VAR and ${VAR} environment variable expansion (and $$ for a literal $), so you can reference secrets such as Bearer $OTEL_TOKEN without hard-coding them. Missing variables are errors, not empty substitutions.

Settings

Field	Default	Description
serviceName	"aether"	The OpenTelemetry service.name resource attribute.
sampleRatio	1.0	Fraction of traces to sample, from 0.0 through 1.0. Metrics are unaffected.
captureContent	false	Whether to export prompt, response, reasoning, tool-definition, and tool-argument content.
traces.enabled	true	Export trace spans.
metrics.enabled	true	Export metrics.
otlp.endpoint	—	Base URL for the OTLP/HTTP collector. Required when traces or metrics are enabled (unless a signal-specific override is set).
otlp.tracesEndpoint	—	Exact OTLP/HTTP trace export URL. Overrides the traces URL derived from endpoint.
otlp.metricsEndpoint	—	Exact OTLP/HTTP metric export URL. Overrides the metrics URL derived from endpoint.
otlp.headers	{}	HTTP headers sent with OTLP requests, such as an authorization header. Values support $VAR / ${VAR} environment variable expansion.

Set both traces.enabled and metrics.enabled to false to keep a telemetry section without creating an exporter.

Correlating SDK runs

SDK callers can either continue beneath an existing OpenTelemetry parent span or start root spans with a caller-supplied trace ID:

await using continuedSession = await AetherSession.start({
  traceContext: {
    traceparent:
      "00-00112233445566778899aabbccddeeff-0123456789abcdef-01",
    tracestate: "vendor=value",
  },
});

await using rootSession = await AetherSession.start({
  traceContext: {
    traceId: "00112233445566778899aabbccddeeff",
  },
});

traceContext is a run/session launch option for AetherSession.start, runHeadless, and the lower-level ACP process API; it is not a persistent telemetry setting. Telemetry still has to be enabled above — without a telemetry section the trace context is ignored.

With traceparent, Aether treats the supplied context as a remote parent, making every invoke_agent turn span its child and preserving tracestate. The parent’s sampled flag is authoritative. With traceId, each invoke_agent span is a root span with no parent span ID, and sampleRatio controls sampling.

Values are validated when telemetry starts. traceparent must follow the W3C Trace Context format with non-zero trace and parent span IDs. traceId must contain exactly 32 lowercase hexadecimal characters and cannot be all zeros. tracestate must be a valid W3C header and is only accepted with traceparent. Invalid or mixed forms fail Aether startup rather than being silently dropped.

Privacy

Content capture is disabled by default. Unless you set captureContent to true, Aether redacts prompts, model responses, reasoning, tool definitions, and tool arguments from telemetry. Enable it only when your collector and its access controls are appropriate for that data.

What Aether exports

Each agent turn produces an invoke_agent root span. Its child spans describe LLM calls (chat <model>) and tool executions (execute_tool <name>), including retries and terminal errors or cancellations.

When enabled, Aether also exports these GenAI histograms:

• gen_ai.client.operation.duration
• gen_ai.client.operation.time_to_first_chunk
• gen_ai.client.operation.time_per_output_chunk
• gen_ai.client.token.usage

For the complete schema, see the field reference.