Docs idea: governance metadata for agent gateway traces #2141

Activity

1. piyushbag commented on Jun 16, 2026

   

   piyushbag

   on Jun 16, 2026

   Contributor

   More actions

   +1 on documenting this. Gateways sit at the boundary where model reasoning becomes tool execution, so they are the right place to make workflow decisions auditable.

   Today most traces answer "what happened?" The metadata you listed would help answer "was this an allowed path through the process?"

   Suggested minimum trace metadata (gateway span)

   Field	Purpose
   decision.result	allow / deny / redact / require_confirmation
   decision.policy_id	which guardrail or route rule fired
   action.risk_class	read / write / destructive / external_publish
   action.target	tool name, resource URI, or route target
   action.arguments_digest	hash of normalized args at enforcement time
   capability.selected	resolved capability or tool version
   output.bounded	whether response was truncated/redacted before return
   workflow.phase	optional phase label if the call sits inside a multi-step process
   workflow.checkpoint_ref	link to prior human gate, if any
   audit.id	stable id for cross-system correlation
   identity.subject	caller identity propagated through the gateway

   This keeps the doc tool-agnostic while giving operators enough structure for replay and review.

   Why this matters for multi-step processes

   In workflow-heavy environments, failures are often silent scope drift: session goes stale, write succeeds with empty payload, or an earlier human approval is reused after arguments changed. Trace metadata should make those cases visible:

   • deny + reason when args digest differs from approved envelope
   • explicit marker when a call proceeded without a required checkpoint
   • correlation between gateway span and downstream tool span via shared audit.id

   Offer to contribute

   If useful, I can open a docs PR that:

   1. Adds a "Recommended governance metadata" section under agentgateway tracing docs
   2. Includes one JSON example for an allowed read call and one for a denied write
   3. Maps fields to common export formats (OTel attributes where applicable)

   I have been working on MCP production transport and session lifecycle in modelcontextprotocol/go-sdk and am interested in the workflow/traceability lane across the AAIF stack. Happy to start with a short RFC-style doc PR and iterate here on field names before implementation.

   Related prior art worth cross-linking: AAIF Observability and Workflows working group themes around execution history as system of record.
2. piyushbag commented on Jun 16, 2026

   

   piyushbag

   on Jun 16, 2026

   Contributor

   More actions

   Opened docs PR for Phase 1 (documentation only):

   #2205

   Adds design/2141-governance-trace-metadata.md with recommended fields, JSON examples, OTel attribute mapping, and mapping to existing dtrace events. Cross-links from examples/telemetry/README.md.

   Happy to iterate on field names, digest normalization, or span placement based on review.
3. howardjohn commented on Aug 27, 2026

   

   howardjohn

   on Aug 27, 2026

   Collaborator

   More actions

   #2205 (comment)
4. howardjohn

   closed this as not plannedon Aug 27, 2026
5. howardjohn

   added the

   Task

   issue type on Aug 27, 2026
6. teemow

   added a commit that references this issue on Oct 14, 2026

   feat(substrate): inject an actor JWT minted through Control.MintActorJwt

   ...

   be87973