Author an observability and tracing operations guide in docs/observability.md

[1nonlypiece]

📌 Description

OpenTelemetry trace-context propagation and Prometheus metrics exist, but there is
no single guide explaining the observability stack: what traces and metrics are
emitted, how trace context flows from Express through the Horizon listener, how to
read the dashboards, and how to correlate a trace with logs and metrics during an
incident. docs/operations-metrics.md lists gauges but not the end-to-end story.

This issue authors an observability operations guide.

🎯 Requirements and Context

• Document the trace-propagation path (HTTP → middleware → listener → jobs) and
  the correlation-ID-to-trace-id relationship.
• Catalogue exported metrics and their intended SLO/alert use.
• Document how to correlate traces, structured logs, and metrics for a given
  request during triage.
• Cross-link the on-call SLO runbook.

🛠️ Suggested Execution

1. Fork the repo and create a branch

git checkout -b docs/observability-guide

2. Implement changes

• Author docs/observability.md, cross-linking docs/operations-metrics.md and
  docs/runbooks/on-call-slo.md.
• Add src/tests/docs.observability.test.ts asserting documented metric names
  match those registered in code.

3. Test and commit

• Run: npm test -- src/tests/docs.observability.test.ts
• Cover edge cases: documented metric names exist in the registry, required
  sections present, runbook cross-link valid.

Example commit message

docs: observability and tracing operations guide

✅ Guidelines

• Minimum 95% test coverage on any assertion code added.
• Documented metric names must match the registry.
• Timeframe: 96 hours.

🏷️ Labels

type-documentation · area-backend · MAYBE REWARDED · GRANTFOX OSS · OFFICIAL CAMPAIGN

💬 Community & Support

• Join the contributor Discord to coordinate, ask questions, and get unblocked fast: https://discord.gg/xvNAvMJf
• Please introduce yourself in the channel before you start so we can avoid duplicate work, pair you with a reviewer, and get your PR merged quickly.
• Maintainers actively triage this channel and aim for fast, clear, respectful reviews — reach out any time you're blocked.

[nelly439]

I'd like to work on this issue.

I have experience documenting observability systems and validating documentation against implementation. I can author a comprehensive observability guide covering OpenTelemetry trace propagation, Prometheus metrics, correlation between traces, logs, and metrics, and practical incident triage workflows. I'll cross-link the existing metrics and SLO runbooks, add tests to verify that documented metric names stay synchronized with the metrics registry and required documentation sections remain present, and ensure the guide is accurate, maintainable, and aligned with the current implementation.

[linoxbt]

Hi, I'd like to work on this issue. I have experience with backend systems, observability tooling, and technical documentation. I can create a clear guide that explains how traces, metrics, and logs work together, how trace context flows through the application, and how to use the existing dashboards and runbooks during incident investigation. I'll also add tests to ensure documented metric names stay in sync with the implementation and that the required sections and links remain valid. My goal is to keep the documentation accurate, practical, and easy for both developers and operators to follow.

[samlogy1]

@samlogy1 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

please i would like to work on this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @samlogy1 to this issue.

[grantfox-oss]

🦊 GrantFox — @samlogy1 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #889)
2. Your PR will be reviewed by the Disciplr-Org maintainers

Good luck! Track your progress on GrantFox.

[drips-wave]

Congratulations, @samlogy1! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @samlogy1: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊