feat(otel): add universally-applicable OpenTelemetry standards and infrastructure playbooks

[ldastey-dev]

Summary

Refactors the OpenTelemetry contribution from PR #23 into three universally-applicable contributions aligned with the repository's open-source framework principles.

Background

PR #23 added four playbooks tightly coupled to .NET and a specific observability stack. This PR restructures that contribution so it is useful to any project, any language, any runtime.

What's Changed

1. OTel Infrastructure Playbooks (refined)

• playbooks/setup/create-local-otel-stack.md — added backend-agnostic note; updated cross-references to standards
• playbooks/setup/discover-local-otel-stack.md — updated cross-references
• playbooks/setup/use-local-otel-stack.md — updated cross-references
• Supporting scripts, Docker Compose, Podman configs, and versions.env carry forward unchanged

2. .NET OpenTelemetry Standard (new)

standards/opentelemetry-dotnet.md (409 lines)

Migrated from playbooks/setup/instrument-dotnet-otel.md (deleted) into a canonical standard, following the structure of standards/dotnet.md:

• NuGet packages, Startup.cs canonical pattern, environment variable configuration
• Testing patterns (InMemory exporter over ActivityListener)
• 3 documented pitfalls with root cause and fix:
  1. Explicit options.Endpoint breaks HTTP/protobuf signal path appending
  2. gRPC (port 4317) unreachable via host.containers.internal
  3. ActivityListener flaky in integration test suites
• Non-Negotiables + Decision Checklist

3. Language-Agnostic OpenTelemetry Standard (new)

standards/opentelemetry.md (565 lines)

A cross-language canonical standard applicable to Go, Python, Java, Rust, Node.js, .NET, PHP, and Ruby:

• OTel SDK principles, Resource configuration, Traces/Metrics/Logs patterns
• OTLP protocol (gRPC port 4317 vs HTTP/protobuf port 4318, signal paths)
• Backend comparison (Jaeger, Tempo, VictoriaMetrics, Honeycomb, Datadog, AWS X-Ray) — no vendor lock-in
• Integration patterns (direct, sidecar, gateway)
• Cross-language pitfalls (cardinality, context propagation, sampling)
• Non-Negotiables + Decision Checklist
• Designed as the canonical parent; language-specific standards (opentelemetry-dotnet.md, future opentelemetry-go.md, etc.) extend it

Framework Integration

• core/.context/index.md: keyword routes for both new standards added; stale instrument-dotnet-otel entry removed
• core/AGENTS.md: Technology Standards table updated with both new standards
• tests/test-deploy.sh + tests/test-deploy.ps1: updated to assert new standards deployed, assert deleted playbook and skill wrappers are absent

Review

Full 7-speciality review completed on this refactoring:

Speciality	Result
SRE (Infrastructure & Ops)	✅ Clear
Principal Engineer (Architecture)	✅ Clear
Architect (System Design)	✅ Clear
QA (Link Integrity & Deployment)	✅ Clear
Security Engineer (Secrets & Provenance)	✅ Clear
Observability Specialist (SDK Practices)	✅ Clear
Senior Technical Writer (Documentation)	✅ Clear

All review feedback addressed (code block language tags added to 71 blocks, orphaned file deleted, index/file consistency restored).

Framework Principles

• Single-source-of-truth: No content duplicated across files
• Separation of concerns: Playbooks hold operational procedures; standards hold prescriptive rules
• Universally applicable: Nothing project-specific
• Language-specific supported: Follows the dotnet.md / react.md precedent
• Extensible: opentelemetry.md is the canonical parent for future language standards

Closes #23

[Copilot]

Pull request overview

This PR refactors the prior .NET-centric OpenTelemetry contribution into universally applicable, single-source-of-truth documentation: a cross-language OpenTelemetry standard plus a .NET-specific extension, while keeping the local OTel stack playbooks and updating deployment tests/index routing accordingly.

Changes:

• Added a new cross-language OpenTelemetry standard (standards/opentelemetry.md) and a .NET-specific OpenTelemetry standard (standards/opentelemetry-dotnet.md).
• Updated local OTel stack playbooks to reference the new standards and removed the old .NET instrumentation playbook (instrument-dotnet-otel.md).
• Updated framework integration (AGENTS + context routing) and deploy tests to assert the new standards are shipped and the removed playbook/skill wrappers are absent.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/test-deploy.sh	Updates deploy assertions to include new OTel standards and exclude the removed playbook/wrappers.
tests/test-deploy.ps1	PowerShell equivalent deploy assertions for new standards and removed playbook/wrappers.
standards/opentelemetry.md	New cross-language OpenTelemetry standard (SDK patterns, OTLP, backends, pitfalls).
standards/opentelemetry-dotnet.md	New .NET-specific OpenTelemetry standard (packages, startup pattern, pitfalls, testing patterns).
playbooks/setup/create-local-otel-stack.md	Refines local stack playbook with backend-agnostic note and updated cross-references.
playbooks/setup/discover-local-otel-stack.md	Updates “Related” section to reference new standards instead of the removed playbook.
playbooks/setup/use-local-otel-stack.md	Updates references from removed playbook to the new .NET standard and adds standards links.
playbooks/setup/instrument-dotnet-otel.md	Removed (content migrated into standards/opentelemetry-dotnet.md).
core/AGENTS.md	Adds both new OTel standards to the Technology Standards table.
core/.context/index.md	Adds keyword routes for new standards and removes the stale route to the deleted playbook.

Suppressed comments (1)

standards/opentelemetry-dotnet.md:84

• The resource attribute key here should match the conventions used elsewhere in the repo (deployment.environment in standards/observability.md and standards/opentelemetry.md). Using environment in the sample code would produce different telemetry metadata keys than other runtimes and documents.

        {
            ["environment"] = env.EnvironmentName,
        }))

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.