Traceability - Aion Docs

Metadata

Field	Value
Canonical URI	`https://docs.aion.to/a2a/extensions/aion/traceability/1.0.0`
Issuer	`aion`
Version	`1.0.0`
Activation	This extension will automatically activate if detected in request regardless of explicit activation.
Related Extensions	Middleware

Overview

The Traceability extension standardizes how distributed trace state is propagated across A2A requests. It adopts:

W3C Trace Context headers: traceparent, tracestate
W3C Baggage header: baggage

This extension is request-scoped and one-way. Trace context is sent to the remote server and forwarded downstream as needed. Servers should correlate observability data directly in shared logging/tracing backends and should not return trace state in A2A responses.

Trace Context Terms

`traceparent`

traceparent is the primary trace-context header. It carries four fields in a fixed format:

version
trace-id
parent-id (the caller span id)
trace-flags (for example sampled)

Format:

{version}-{trace-id}-{parent-id}-{trace-flags}

Example:

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

`tracestate`

tracestate is an optional companion header for vendor-specific state. It is a comma-separated ordered list of key/value members. Ordering is meaningful (left-most entries have highest priority).

`baggage`

baggage is an optional set of user-defined key/value pairs propagated alongside requests. It is independent of trace identity and is typically used for request-scoped business context. Further reading:

Agent Card Declaration

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://docs.aion.to/a2a/extensions/aion/traceability/1.0.0",
        "description": "W3C trace context and baggage propagation",
        "required": false,
        "params": {
          "propagation": ["traceparent", "tracestate", "baggage"],
          "responsePropagation": "none"
        }
      }
    ]
  }
}

Transmission Model

Service Parameters (Preferred)

Use service parameters for transport-level propagation. For HTTP bindings this is HTTP headers; for gRPC bindings this is metadata with the same keys.

Name	Required	Description
`traceparent`	optional	W3C trace parent context. If absent, receiver starts a new trace.
`tracestate`	optional	W3C vendor-specific trace state.
`baggage`	optional	W3C arbitrary key/value context propagated across services.

Notes:

Canonical names are exactly traceparent, tracestate, and baggage (no w3c- prefix).
Send keys in lowercase for interoperability.
tracestate should be omitted when empty.
Clients should still declare extension intent with A2A-Extensions.

Request Metadata Carrier (Alternative)

When a binding cannot set transport headers directly, this extension may carry the same data in request metadata under the extension URI key. Recommended metadata shape:

traceparent: string
tracestate: ordered [{ key: string, value: string }]
baggage: key/value object (Record<string, string>)

Aion Baggage Key Conventions

This extension does not define required baggage keys for external callers. The aion.* namespace is reserved. External callers should keep aion.* clear unless explicitly documented by an Aion extension. The control plane may attach additional aion.* baggage entries. Additional tags may be propagated as user-defined baggage entries without any required prefix. These tags are used for observability metadata and may be logged by receivers. Sensitive information should not be transmitted in baggage.

Processing Rules

Receivers must parse traceparent first. If traceparent is invalid, receivers should ignore it and restart the trace.
If traceparent is invalid, tracestate should not be processed.
Pass-through components that do not change traceparent should not mutate tracestate.
If tracestate is mutated, preserve ordering of unmodified members and move modified vendor members to the left.
Propagate baggage downstream unless policy requires sanitization.
Propagate user-defined baggage tag keys as-is.
For baggage, propagate all members when total size is <= 8192 bytes and total entries are <= 64; otherwise implementations may drop or truncate entries.
Do not place secrets, credentials, or direct PII in baggage or tracestate.
For untrusted external boundaries, implementations may ignore, sanitize, or regenerate incoming context according to security policy.

Logging Guidance for Additional Tags

User-defined baggage tags are useful for diagnostics and cross-service correlation, but they should be handled as untrusted input.

It is reasonable to emit selected baggage tags to logs.
Apply an allowlist for keys that are safe to log.
Redact or hash sensitive values (for example auth/session/token fields, emails, raw identifiers).
Enforce size and cardinality limits to prevent log volume spikes.
Sanitize control characters before logging to prevent log-forging/injection issues.

Request-Only Semantics

This extension does not require servers to echo trace context in Message, Task, stream events, or push notifications. The trace context is treated as inbound and forwarding metadata used for server-side correlation.

Example 1: HTTP Header Propagation (Preferred)

POST /a2a HTTP/1.1
Host: agent.example.com
Content-Type: application/json
A2A-Extensions: https://docs.aion.to/a2a/extensions/aion/traceability/1.0.0
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate: aion=00f067aa0ba902b7
baggage: aion.sender.id=cp-node-17,channel=telegram,tenant=acme

{
  "jsonrpc": "2.0",
  "id": "req-42",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "messageId": "msg-42",
      "parts": [
        {
          "text": "Summarize the latest invoice."
        }
      ]
    }
  }
}

Example 2: Request Metadata Propagation (Extension Payload)

In this mode, extension activation still uses A2A-Extensions. Trace fields are carried in params.metadata under the extension URI key.

POST /a2a HTTP/1.1
Host: agent.example.com
Content-Type: application/json
A2A-Extensions: https://docs.aion.to/a2a/extensions/aion/traceability/1.0.0

{
  "jsonrpc": "2.0",
  "id": "req-43",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "messageId": "msg-43",
      "parts": [
        {
          "text": "Get order status for 8841."
        }
      ]
    },
    "metadata": {
      "https://docs.aion.to/a2a/extensions/aion/traceability/1.0.0": {
        "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
        "tracestate": [
          { "key": "aion", "value": "00f067aa0ba902b7" },
          { "key": "congo", "value": "t61rcWkgMzE" }
        ],
        "baggage": {
          "aion.sender.id": "cp-node-17",
          "channel": "api",
          "tenant": "acme"
        }
      }
    }
  }
}

Aion Extensions

​Overview

​Trace Context Terms

​traceparent

​tracestate

​baggage

​Agent Card Declaration

​Transmission Model

​Service Parameters (Preferred)

​Request Metadata Carrier (Alternative)

​Aion Baggage Key Conventions

​Processing Rules

​Logging Guidance for Additional Tags

​Request-Only Semantics

​Example 1: HTTP Header Propagation (Preferred)

​Example 2: Request Metadata Propagation (Extension Payload)