From 6b21d620e5793427991ff8b6b1ad4b225616c13a Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Wed, 3 Jun 2026 15:30:59 +0200 Subject: [PATCH] docs(rfd): Document observability guidance --- docs/docs.json | 2 ++ docs/protocol/v1/draft/extensibility.mdx | 4 ++++ docs/protocol/v1/draft/observability.mdx | 28 ++++++++++++++++++++++++ docs/protocol/v2/draft/extensibility.mdx | 4 ++++ docs/protocol/v2/draft/observability.mdx | 28 ++++++++++++++++++++++++ 5 files changed, 66 insertions(+) create mode 100644 docs/protocol/v1/draft/observability.mdx create mode 100644 docs/protocol/v2/draft/observability.mdx diff --git a/docs/docs.json b/docs/docs.json index 15c471b6..f248dcf4 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -105,6 +105,7 @@ "protocol/v1/draft/session-config-options", "protocol/v1/draft/slash-commands", "protocol/v1/draft/extensibility", + "protocol/v1/draft/observability", "protocol/v1/draft/transports", "protocol/v1/draft/schema" ] @@ -148,6 +149,7 @@ "protocol/v2/draft/session-config-options", "protocol/v2/draft/slash-commands", "protocol/v2/draft/extensibility", + "protocol/v2/draft/observability", "protocol/v2/draft/transports", "protocol/v2/draft/schema" ] diff --git a/docs/protocol/v1/draft/extensibility.mdx b/docs/protocol/v1/draft/extensibility.mdx index 31441013..03286c78 100644 --- a/docs/protocol/v1/draft/extensibility.mdx +++ b/docs/protocol/v1/draft/extensibility.mdx @@ -38,6 +38,10 @@ Clients may propagate fields to the agent for correlation purposes, such as `req Implementations **MUST NOT** add any custom fields at the root of a type that's part of the specification. All possible names are reserved for future protocol versions. +## Observability + +The `_meta` field can carry correlation context such as W3C trace context keys. Actual telemetry data should be exported out of band with OpenTelemetry. See [Observability](/protocol/v1/draft/observability). + ## Extension Methods The protocol reserves any method name starting with an underscore (`_`) for custom extensions. This allows implementations to add new functionality without the risk of conflicting with future protocol versions. diff --git a/docs/protocol/v1/draft/observability.mdx b/docs/protocol/v1/draft/observability.mdx new file mode 100644 index 00000000..99d508e8 --- /dev/null +++ b/docs/protocol/v1/draft/observability.mdx @@ -0,0 +1,28 @@ +--- +title: "Observability" +description: "Exporting agent telemetry out of band" +--- + +ACP does not define telemetry messages. Agents that produce traces, metrics, or structured logs should export them out of band with [OpenTelemetry](https://opentelemetry.io/) rather than over the ACP transport. + +Clients that want telemetry **MAY** run a local OTLP receiver and configure subprocess agents with standard [OpenTelemetry Protocol exporter environment variables](https://opentelemetry.io/docs/specs/otel/protocol/exporter/) when launching them over [stdio](/protocol/v1/draft/transports#stdio): + +```sh +OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 +OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +OTEL_SERVICE_NAME=agent-name +``` + +Clients **SHOULD** respect user-provided `OTEL_*` environment variables. If a variable is already set in the agent launch environment, the client **SHOULD** preserve that value instead of replacing it. This allows users to direct agent telemetry to their own collector or backend. + +Clients **SHOULD NOT** pass backend authentication headers or credentials directly to agents. If backend authentication is required, the local receiver or collector should add those credentials while forwarding telemetry. Agents and clients **SHOULD** avoid recording prompt contents, generated content, secrets, access tokens, file contents, or other sensitive data unless the user has explicitly enabled that behavior. + +Agents **MAY** use their language's OpenTelemetry SDK and standard environment-based auto-configuration. Agents do not need ACP-specific telemetry messages or custom JSON-RPC methods. + +Telemetry export failures **SHOULD NOT** fail ACP requests or block protocol message handling. Agents **MUST NOT** write telemetry payloads to `stdout`, because `stdout` is reserved for valid ACP messages on stdio transports. Agents **MAY** continue to write human-readable diagnostics to `stderr` as described in [Transports](/protocol/v1/draft/transports#stdio). + +## Trace Correlation + +Telemetry export is complementary to trace context propagation through [`params._meta`](/protocol/v1/draft/extensibility#the-_meta-field). Clients can propagate W3C trace context keys such as `traceparent`, `tracestate`, and `baggage` in `_meta`; agents can use that context as the parent for spans they export through OpenTelemetry. + +For telemetry contents, naming, and model-call attributes, follow OpenTelemetry resources such as the [semantic conventions](https://opentelemetry.io/docs/specs/semconv/) and [Generative AI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). diff --git a/docs/protocol/v2/draft/extensibility.mdx b/docs/protocol/v2/draft/extensibility.mdx index 69f05c8a..1232dafc 100644 --- a/docs/protocol/v2/draft/extensibility.mdx +++ b/docs/protocol/v2/draft/extensibility.mdx @@ -38,6 +38,10 @@ Clients may propagate fields to the agent for correlation purposes, such as `req Implementations **MUST NOT** add any custom fields at the root of a type that's part of the specification. All possible names are reserved for future protocol versions. +## Observability + +The `_meta` field can carry correlation context such as W3C trace context keys. Actual telemetry data should be exported out of band with OpenTelemetry. See [Observability](/protocol/v2/draft/observability). + ## Extension Methods The protocol reserves any method name starting with an underscore (`_`) for custom extensions. This allows implementations to add new functionality without the risk of conflicting with future protocol versions. diff --git a/docs/protocol/v2/draft/observability.mdx b/docs/protocol/v2/draft/observability.mdx new file mode 100644 index 00000000..c08c5ea2 --- /dev/null +++ b/docs/protocol/v2/draft/observability.mdx @@ -0,0 +1,28 @@ +--- +title: "Observability" +description: "Exporting agent telemetry out of band" +--- + +ACP does not define telemetry messages. Agents that produce traces, metrics, or structured logs should export them out of band with [OpenTelemetry](https://opentelemetry.io/) rather than over the ACP transport. + +Clients that want telemetry **MAY** run a local OTLP receiver and configure subprocess agents with standard [OpenTelemetry Protocol exporter environment variables](https://opentelemetry.io/docs/specs/otel/protocol/exporter/) when launching them over [stdio](/protocol/v2/draft/transports#stdio): + +```sh +OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 +OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +OTEL_SERVICE_NAME=agent-name +``` + +Clients **SHOULD** respect user-provided `OTEL_*` environment variables. If a variable is already set in the agent launch environment, the client **SHOULD** preserve that value instead of replacing it. This allows users to direct agent telemetry to their own collector or backend. + +Clients **SHOULD NOT** pass backend authentication headers or credentials directly to agents. If backend authentication is required, the local receiver or collector should add those credentials while forwarding telemetry. Agents and clients **SHOULD** avoid recording prompt contents, generated content, secrets, access tokens, file contents, or other sensitive data unless the user has explicitly enabled that behavior. + +Agents **MAY** use their language's OpenTelemetry SDK and standard environment-based auto-configuration. Agents do not need ACP-specific telemetry messages or custom JSON-RPC methods. + +Telemetry export failures **SHOULD NOT** fail ACP requests or block protocol message handling. Agents **MUST NOT** write telemetry payloads to `stdout`, because `stdout` is reserved for valid ACP messages on stdio transports. Agents **MAY** continue to write human-readable diagnostics to `stderr` as described in [Transports](/protocol/v2/draft/transports#stdio). + +## Trace Correlation + +Telemetry export is complementary to trace context propagation through [`params._meta`](/protocol/v2/draft/extensibility#the-_meta-field). Clients can propagate W3C trace context keys such as `traceparent`, `tracestate`, and `baggage` in `_meta`; agents can use that context as the parent for spans they export through OpenTelemetry. + +For telemetry contents, naming, and model-call attributes, follow OpenTelemetry resources such as the [semantic conventions](https://opentelemetry.io/docs/specs/semconv/) and [Generative AI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/).