[docs] docs: sync OTEL attribute names and environment variable references

[github-actions]

Documentation Sync - May 21, 2026

This PR synchronizes documentation with code changes from the past 7 days, specifically the recent OTEL (OpenTelemetry) attribute naming changes.

Changes Made

• Updated docs/api-proxy-sidecar.md: Corrected OTEL attribute names to match current code

  • awf.cache_read_tokens → awf.cached_read
  • awf.cache_write_tokens → awf.cached_write
  • Added missing awf.reasoning attribute to the span attributes table

• Updated docs/otel-sentry.md: Fixed environment variable names to match actual implementation

  • AWF_OTEL_TRACE_ID → GITHUB_AW_OTEL_TRACE_ID
  • AWF_OTEL_SPAN_ID → GITHUB_AW_OTEL_PARENT_SPAN_ID

Code Changes Referenced

• Commit 719b171: "fix: rename OTEL cache attrs to avoid Sentry PII scrubber (fix: rename OTEL cache attrs to avoid Sentry PII scrubber #3504)" — Changed attribute names from awf.cache_*_tokens to awf.cached_* to prevent Sentry's PII scrubber from redacting them
• Commit ebf303e: "docs: add OTEL Sentry attribute reference (docs: add OTEL Sentry attribute reference #3508)" — Added comprehensive OTEL Sentry documentation (contained incorrect env var names)
• Commit ec6e0f0: "fix: emit cache token OTEL attributes as strings for Sentry visibility (fix: emit cache token OTEL attributes as strings for Sentry #3501)" — Changed attributes from numeric to string format

Verification

• ✅ Verified actual OTEL code in containers/api-proxy/otel.js uses the corrected attribute names
• ✅ Verified actual code uses GITHUB_AW_OTEL_TRACE_ID and GITHUB_AW_OTEL_PARENT_SPAN_ID (not the AWF_ prefix variant)
• ✅ Existing docs/environment.md already documents the correct env var names
• ✅ Code examples in documentation are now consistent with implementation

Why This Matters

Accurate documentation is critical for secure usage of the firewall. Incorrect environment variable names or attribute references would cause:

• OTEL tracing to fail silently or misbehave
• Operators to implement incorrect monitoring configurations
• Integration with Sentry to not work as expected

Generated by Documentation Maintainer · ● 83.9K · ◷

[github-actions]

Documentation Preview

Documentation build failed for this PR. View logs.

Built from commit 150c903

[github-actions]

Smoke Test Results

✅ GitHub API - Confirmed 2 PR entries in recent-prs.json
✅ Playwright - Successfully navigated to github.com (title contains "GitHub")
✅ File Verify - Confirmed file exists at /tmp/gh-aw/agent/smoke-test-claude-26208442351.txt

Result: PASS ✅ All tests passed.

💥 [THE END] — Illustrated by Smoke Claude

[github-actions]

🔬 Smoke Test Results

Test	Status
GitHub MCP connectivity	✅ (fetched merged PR: "docs: add OTEL Sentry attribute reference")
GitHub.com HTTP connectivity	⚠️ pre-step data unavailable (template not expanded)
File write/read	⚠️ pre-step data unavailable (template not expanded)

PR: [docs] sync OTEL attribute names and environment variable references — author: @github-actions[bot], no assignees.

Overall: PARTIAL — MCP test passed; connectivity/file tests could not be verified due to missing pre-step outputs.

📰 BREAKING: Report filed by Smoke Copilot

[github-actions]

🔥 Smoke Test: Copilot BYOK (Offline) Mode

Test	Result
GitHub MCP connectivity (latest merged PR: #3508 "docs: add OTEL Sentry attribute reference")	✅
GitHub.com HTTP connectivity	⚠️ data not injected (${{ steps.smoke-data.outputs.SMOKE_HTTP_CODE }})
File write/read	⚠️ data not injected (${{ steps.smoke-data.outputs.SMOKE_FILE_PATH }})
BYOK inference (agent → api-proxy → api.githubcopilot.com)	✅

Running in BYOK offline mode (COPILOT_OFFLINE=true) via api-proxy → api.githubcopilot.com.

Overall: PARTIAL — BYOK inference and MCP working; pre-step template variables not expanded for tests 2–3.

PR author: @github-actions[bot] · No assignees.

🔑 BYOK report filed by Smoke Copilot BYOK

[github-actions]

Smoke Test Results: MCP (FAIL), Connectivity (FAIL), File Writing (PASS), Bash Tool (PASS). Overall: FAIL

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• localhost

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "localhost"

See Network Configuration for more information.

💎 Faceted by Smoke Gemini

[github-actions]

✅ GitHub PR review: docs: add OTEL Sentry attribute reference | fix: rename OTEL cache attrs to avoid Sentry PII scrubber
❌ safeinputs-gh: tool unavailable; queried titles: [WIP] Optimize token usage in Smoke Claude workflow | [WIP] Optimize tokens usage for test coverage
✅ Playwright: title contains GitHub
❌ Tavily: no tools exposed/results unavailable
✅ File write/bash: smoke file created and read back
❌ Discussion: github-discussion-query unavailable
✅ Build: npm ci && npm run build
Overall status: FAIL

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• registry.npmjs.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "registry.npmjs.org"

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex

[github-actions]

🏗️ Build Test Suite Results

Ecosystem	Project	Build/Install	Tests	Status
Bun	elysia	✅	1/1 passed	✅ PASS
Bun	hono	✅	1/1 passed	✅ PASS
C++	fmt	✅	N/A	✅ PASS
C++	json	✅	N/A	✅ PASS
Deno	oak	N/A	1/1 passed	✅ PASS
Deno	std	N/A	1/1 passed	✅ PASS
.NET	hello-world	✅	N/A	✅ PASS
.NET	json-parse	✅	N/A	✅ PASS
Go	color	✅	1/1 passed	✅ PASS
Go	env	✅	1/1 passed	✅ PASS
Go	uuid	✅	1/1 passed	✅ PASS
Java	gson	✅	1/1 passed	✅ PASS
Java	caffeine	✅	1/1 passed	✅ PASS
Node.js	clsx	✅	all passed	✅ PASS
Node.js	execa	✅	all passed	✅ PASS
Node.js	p-limit	✅	all passed	✅ PASS
Rust	fd	✅	1/1 passed	✅ PASS
Rust	zoxide	✅	1/1 passed	✅ PASS

Overall: 8/8 ecosystems passed — ✅ PASS

Generated by Build Test Suite for issue #3512 · ● 5.2M · ◷

[github-actions]

Smoke Test Results — FAIL

Check	Result
Redis PING	❌ Timeout/unreachable
PostgreSQL pg_isready	❌ No response
PostgreSQL SELECT 1	❌ Timeout/failed

host.docker.internal is not reachable from this runner environment. All three checks failed.

Overall: ❌ FAIL

🔌 Service connectivity validated by Smoke Services