Docs still reference copilot-otel.jsonl artifact removed in #32280

[Etienne-M]

Docs still promise the copilot-otel.jsonl artifact that was removed in #32280

Analysis

PR #30530 (commit 6bd6baad, 2026-05-06) introduced a Copilot CLI OTEL file-export pipeline: the compiler injected COPILOT_OTEL_FILE_EXPORTER_PATH=/tmp/gh-aw/copilot-otel.jsonl, export_copilot_otel_traces.cjs forwarded those spans to configured OTLP endpoints, and the file was included in the unified agent artifact.

During review of PR #32280 (commit fc420392, 2026-05-15), this entire pipeline was removed at maintainer request (comment and the follow-up comment at 04:59 UTC). The removal deleted:

• COPILOT_OTEL_FILE_EXPORTER_PATH injection in pkg/workflow/observability_otlp.go
• the artifact path in collectArtifactPaths (pkg/workflow/compiler_yaml_main_job.go)
• the CopilotOtelJsonlFilename constant (pkg/constants/job_constants.go)
• actions/setup/js/export_copilot_otel_traces.cjs (+ test) and its call in generate_observability_summary.cjs

However, neither the #32280 changeset, its ADR (docs/adr/32280-pass-otel-headers-as-container-env-var.md), nor the documentation was updated. The docs still tell users to expect copilot-otel.jsonl in the agent artifact, which no code produces. Users configuring observability.otlp today get otel.jsonl only and (correctly per current design, per ADR-34450) must query Copilot CLI spans directly from their OTLP backend via the injected OTEL_RESOURCE_ATTRIBUTES correlation keys (github.run_id, gh-aw.run.id, etc.).

Stale references (verified 2026-08-13)

File	Reference
docs/src/content/docs/guides/open-telemetry.mdx	Lines ~126–127, ~231, ~241: lists copilot-otel.jsonl as an artifact file, describes it being "written ... and forwarded to configured endpoints", and shows a cat copilot-otel.jsonl | jq example
docs/src/content/docs/reference/artifacts.md	Line ~151: copilot-otel.jsonl — OTLP spans emitted by Copilot CLI when observability.otlp is configured
docs/src/content/docs/reference/open-telemetry.mdx	Lines ~261–262: <code>copilot-otel.jsonl</code> for spans emitted by Copilot CLI
.github/skills/otel-queries/SKILL.md	Line ~39: /tmp/gh-aw/copilot-otel.jsonl for Copilot CLI spans listed as a local mirror to check
specs/otel-observability-spec.md	Line ~756: artifact "SHOULD contain ... runtime-specific companion files such as copilot-otel.jsonl when present" (conditional, but misleading since nothing produces the file)
scratchpad/layout.md	Lines ~197, ~652: /tmp/gh-aw/copilot-otel.jsonl in the filesystem layout tables
.github/workflows/smoke-otel-backends.md	Line ~117: echoes COPILOT_OTEL_FILE_EXPORTER_PATH, an env var no code sets anymore

Implementation Plan

Please implement the following documentation-only changes (no Go/JS behavior change):

1. docs/src/content/docs/guides/open-telemetry.mdx

   • Remove copilot-otel.jsonl from the artifact file list.
   • Replace the paragraph describing Copilot CLI spans being written to /tmp/gh-aw/copilot-otel.jsonl and forwarded at end of run with an explanation of the current design: Copilot CLI inherits the standard OTel env vars (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES) and exports spans directly to the configured OTLP backend; query them in the backend filtered by the github.run_id resource attribute (see ADR-34450).
   • Remove the cat copilot-otel.jsonl | jq example; optionally replace with a backend query hint.

2. docs/src/content/docs/reference/artifacts.md

   • Remove the copilot-otel.jsonl bullet from the agent artifact contents list.

3. docs/src/content/docs/reference/open-telemetry.mdx

   • Remove the copilot-otel.jsonl line item; keep otel.jsonl (gh-aw JS helper spans).

4. .github/skills/otel-queries/SKILL.md

   • Remove /tmp/gh-aw/copilot-otel.jsonl from the local mirror checklist; point Copilot CLI span queries at the OTLP backend path already described in the skill.

5. specs/otel-observability-spec.md

   • Update §Telemetry artifacts (~line 756) to drop the copilot-otel.jsonl example or note explicitly that no runtime companion file is currently produced. Add a changelog entry noting the pipeline removal in Pass OTEL_EXPORTER_OTLP_HEADERS env var to mcpg container; remove headers from gateway JSON config #32280.

6. scratchpad/layout.md

   • Remove the /tmp/gh-aw/copilot-otel.jsonl rows from both layout tables.

7. .github/workflows/smoke-otel-backends.md

   • Remove the COPILOT_OTEL_FILE_EXPORTER_PATH echo from Step 1. Run make recompile afterwards so the paired .lock.yml stays in sync.

8. Follow Guidelines

   • Follow .github/skills/documentation/SKILL.md (Diataxis / Starlight conventions).
   • No changeset needed if the repo treats docs-only changes as such; otherwise add a patch changeset describing the doc correction.
   • Run make agent-report-progress before the final push.

Out of scope / open question for the team

Whether to restore the copilot-otel.jsonl pipeline instead of documenting its absence. The removal in #32280 assumed Copilot CLI exports spans directly via the standard OTel env vars, but that assumption was not verified in the PR. If Copilot CLI does not honor OTEL_EXPORTER_OTLP_ENDPOINT, Copilot spans are currently lost entirely and the right fix is a revert of the removal rather than a docs update. Suggest the team confirms Copilot CLI direct-export behavior first; this issue covers the documentation cleanup for whichever state is confirmed.