docs(observability): define OpenTelemetry best practices

[tucktuck101]

Summary

Adds a version-pinned, primary-source definition of OpenTelemetry instrumentation best practice and maps it to every Buzz product runtime boundary in issue #493. The artifact separates normative requirements, Stable conventions, experimental guidance, local recommendations, and deferred decisions while preserving ADR-0023 through ADR-0026, the infrastructure ownership boundary, and the mobile exclusion.

Related issue

Closes #493

Issue type

Task

---

Agent provenance

Field	Value
Harness / provider	Codex
Model	codex-sol-high
Session reference	N/A - the harness did not expose a run ID or URL
Initiating human	@tucktuck101

Objective

Create the issue #493 source-backed OpenTelemetry best-practice research artifact and Buzz runtime applicability map without designing instrumentation or infrastructure.

Impacted components

launchpad/Research/493-otel-instrumentation-best-practices.md

Approach and rejected alternatives

Used OpenTelemetry Specification 1.60.0, Semantic Conventions 1.44.0, an exact OpenTelemetry GenAI conventions commit, W3C Trace Context Level 2, and dated official browser documentation. Claims are explicitly classified by authority and maturity, then mapped to product/infrastructure ownership and downstream issue owners. Rejected an SDK/package inventory because that is #462, a Buzz-specific telemetry schema because ADR-0023 requires OpenTelemetry conventions first, and exporter/collector/platform design because those belong to desired-state work and buzz-infrastructure#113.

Verification

Command run:

ruby -e 'p=ARGV[0]; s=File.read(p); defs=s.scan(/^\[([^\]]+)\]:\s+(\S+)$/).to_h; refs=s.scan(/\[[^\]]+\]\[([^\]]+)\]/).flatten.uniq; local=s.scan(/\[[^\]]+\]\((\.\.[^)]+)\)/).flatten; missing_refs=refs-defs.keys; unused=defs.keys-refs; missing_local=local.reject { |x| File.exist?(File.expand_path(x, File.dirname(p))) }; puts "reference definitions=#{defs.length} references=#{refs.length} undefined=#{missing_refs.length} unused=#{unused.length}"; puts "relative links=#{local.length} missing=#{missing_local.length}"; abort "reference failure" unless missing_refs.empty? && unused.empty? && missing_local.empty?' launchpad/Research/493-otel-instrumentation-best-practices.md
/Users/jeff/.codex/skills/glow-render/check.sh launchpad/Research/493-otel-instrumentation-best-practices.md 80 >/dev/null && echo 'glow render: clean at width 80'

file=launchpad/Research/493-otel-instrumentation-best-practices.md
urls_file=$(mktemp)
failures_file=$(mktemp)
awk '/^\[[^]]+\]: https:/{print $2}' "$file" > "$urls_file"
xargs -P 8 -n 1 sh -c 'curl -LfsS --retry 2 --connect-timeout 10 --max-time 30 -o /dev/null "$1" || printf "%s\n" "$1"' sh < "$urls_file" > "$failures_file"
printf 'source links checked=%s failed=%s\n' "$(wc -l < "$urls_file" | tr -d ' ')" "$(wc -l < "$failures_file" | tr -d ' ')"
if test -s "$failures_file"; then sed 's/^/FAIL /' "$failures_file"; exit 1; fi

Raw output:

reference definitions=39 references=39 undefined=0 unused=0
relative links=6 missing=0
glow render: clean at width 80
source links checked=39 failed=0

• Tests or checks were run and the raw output is pasted above
• The diff is confined to the scope of the linked issue
• No secrets, keys, tokens or hostnames were added to tracked files

Not verified

Did not inventory current runtime instrumentation or SDK capabilities because those are #462 and #463-#476. Did not run a live relay, desktop/browser client, exporter, collector, or broad repository CI because this change is research-only and the assignment requires the smallest final documentation/source checks.

Security implications

This documentation-only change adds no runtime exposure. It preserves ADR-0025's prohibited-content, classification, filtering, truncation, consent, and cardinality boundaries and treats propagated context as untrusted correlation data rather than identity or authority.

Escalations

No new ADR is proposed. The absence of Stable WebSocket/Nostr carriers, Development browser/messaging/GenAI/MCP conventions, sampling/profile policy, and per-runtime SDK capability remain explicit uncertainties assigned to the existing current-state, desired-state, profile, and infrastructure issues.