[DOCS]:

[vishu-bh]

Problem

The observability documentation has several issues:

• Duplication of Prometheus metrics content in the landing page
• Confusing file naming (observability/observability.md)
• Prescriptive language that recommends specific tools rather than describing capabilities
• Missing dedicated Prometheus metrics guide
• OTEL span attributes reference in repository root instead of docs structure

Solution

PR #4249 restructures the observability documentation to:

• Extract Prometheus metrics to dedicated guide
• Rename files for clarity (observability.md → opentelemetry.md, internal-observability.md → internal.md)
• Use neutral, descriptive language instead of prescriptive recommendations
• Move OTEL span attributes to architecture documentation
• Fix all cross-references and broken links
• Add comprehensive comparison matrix

Documentation Structure After Fix

docs/docs/
├── manage/
│   ├── observability.md (landing page)
│   └── observability/
│       ├── opentelemetry.md (external backends)
│       ├── internal.md (built-in tracing)
│       ├── prometheus.md (NEW - metrics)
│       ├── langfuse.md (LLM observability)
│       └── phoenix.md (AI/LLM observability)
└── architecture/
    ├── observability-otel.md (OTEL architecture)
    └── otel-span-attributes.md (NEW - span reference)