chore: Update OTel observability spec#34043
Merged
Merged
Conversation
Collaborator
mnkiefer
commented
May 22, 2026
- Updates the OTel Observability Specification to version 0.3.0, introducing detailed support for MCP gateway and API proxy tracing.
Contributor
|
✅ smoke-ci: safeoutputs CLI comment + comment-memory run (26296458790)
|
Contributor
Comment MemoryNote This comment is managed by comment memory.It stores persistent context for this thread in the code block at the top of this comment.
|
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the repository’s OTel observability specification to v0.3.0, expanding the trace model and attribute contract to cover MCP gateway and API proxy tracing.
Changes:
- Bumped spec version/
last_updatedmetadata and added a v0.3.0 changelog entry. - Extended the trace hierarchy and span-kind assignments to include MCP gateway and API proxy spans.
- Added a new MCP gateway span attribute contract section plus corresponding implementation-mapping and compliance-test entries.
Show a summary per file
| File | Description |
|---|---|
specs/otel-observability-spec.md |
Updates the OTel spec to v0.3.0 and documents MCP gateway/API proxy spans, attributes, mapping, and compliance expectations. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 5
| 8. [Security and Privacy Requirements](#8-security-and-privacy-requirements) | ||
| 9. [Trace Model](#9-trace-model) | ||
| 10. [Span Attribute Contract](#10-span-attribute-contract) | ||
| - [10.7 MCP Gateway Span Attribute Contract](#107-mcp-gateway-span-attribute-contract) |
Comment on lines
303
to
+310
| │ ├── gh-aw.agent.conclusion (parent: agent setup span) | ||
| │ │ └── gh-aw.agent.agent (parent: agent conclusion span) | ||
| │ │ [dedicated AI latency measurement] | ||
| │ │ | ||
| │ └── MCP Gateway (service: mcp-gateway) | ||
| │ ├── gateway.request (parent: agent setup span) | ||
| │ │ └── mcp.tool_call (parent: gateway.request) | ||
| │ │ └── gateway.backend.execute (parent: mcp.tool_call) |
Comment on lines
+544
to
+550
| ### 10.7 MCP Gateway Span Attribute Contract | ||
|
|
||
| This section defines the attributes emitted by the MCP gateway (`gh-aw-mcpg`). These spans are emitted under the `mcp-gateway` service but share the workflow's trace ID (linked via `GITHUB_AW_OTEL_TRACE_ID` and `GITHUB_AW_OTEL_PARENT_SPAN_ID` passed to the gateway container per §6.3). | ||
|
|
||
| The canonical reference for gateway span attributes is [`gh-aw-mcpg/docs/otel-sentry.md`](https://github.com/github/gh-aw-mcpg/blob/main/docs/otel-sentry.md). This section summarizes the contract for cross-referencing with workflow-level spans. | ||
|
|
||
| #### 10.7.1 `gateway.request` Span |
Comment on lines
726
to
738
| | Section | Title | Primary implementation files | | ||
| |---|---|---| | ||
| | §4 | Configuration Model | `pkg/workflow/frontmatter_types.go`, `pkg/parser/schemas/main_workflow_schema.json`, `pkg/workflow/observability_otlp.go` | | ||
| | §5 | Runtime Environment Contract | `pkg/workflow/observability_otlp.go`, `pkg/workflow/compiler_types.go` | | ||
| | §6.1 | Multi-Endpoint Fan-Out | `pkg/workflow/observability_otlp.go`, `actions/setup/js/send_otlp_span.cjs` | | ||
| | §6.2-§6.4 | Export and Gateway Integration | `pkg/workflow/mcp_renderer.go`, `pkg/workflow/mcp_setup_generator.go`, `pkg/workflow/schemas/mcp-gateway-config.schema.json` | | ||
| | §6.5 | Trace Context Variables | `actions/setup/js/action_setup_otlp.cjs`, `actions/setup/js/aw_context.cjs` | | ||
| | §7 | Local Mirrors and Artifacts | `actions/setup/js/send_otlp_span.cjs`, `actions/setup/js/constants.cjs`, `actions/setup/post.js` | | ||
| | §8 | Security and Privacy Requirements | `pkg/workflow/observability_otlp.go`, `pkg/workflow/mcp_renderer.go`, `pkg/workflow/mcp_setup_generator.go`, `actions/setup/js/send_otlp_span.cjs` | | ||
| | §9 | Trace Model | `actions/setup/js/send_otlp_span.cjs`, `actions/setup/js/action_setup_otlp.cjs`, `actions/setup/js/action_conclusion_otlp.cjs` | | ||
| | §10 | Span Attribute Contract | `actions/setup/js/action_setup_otlp.cjs`, `actions/setup/js/action_conclusion_otlp.cjs`, `actions/setup/js/send_otlp_span.cjs`, `actions/setup/js/evaluate_outcomes.cjs`, `actions/setup/js/emit_outcome_spans.cjs` | | ||
| | §10.7 | MCP Gateway Span Attribute Contract | `gh-aw-mcpg` tracing package, `gh-aw-mcpg/docs/otel-sentry.md` | | ||
| | §11 | Resource Attributes | `actions/setup/js/action_setup_otlp.cjs`, `actions/setup/js/send_otlp_span.cjs` | |
Comment on lines
+766
to
770
| | `T-OTEL-OBS-016` | Gateway span linkage | Gateway spans (`gateway.request`, `mcp.tool_call`, `gateway.backend.execute`) appear as children of the agent job's setup span in the same trace. | `gh-aw-mcpg` integration tests | | ||
| | `T-OTEL-OBS-017` | Gateway tool name attribute | Every `mcp.tool_call` span includes `gen_ai.tool.name` identifying the tool invoked. | `gh-aw-mcpg` integration tests | | ||
| | `T-OTEL-OBS-018` | Gateway rate limit attribute | `gateway.backend.execute` spans include `rate_limit.hit` when a rate limit is triggered. | `gh-aw-mcpg` integration tests | | ||
| | `T-OTEL-OBS-019` | Proxy DIFC span emission | When API proxy is active, `proxy.difc_pipeline` and `proxy.backend.forward` spans are emitted. | `gh-aw-mcpg` integration tests | | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.