Repository navigation
docs: add an Observability troubleshooting page #4550
Description
User Story
As an operator of OpenShell,
I want a docs page that shows how to use traces, metrics, and OCSF events to diagnose common problems,
so that I don't have to work out from source code which signal answers my question.
Problem Statement
Once observability is enabled (#4548), the published docs say what each signal is, but not how to use it. Operators who see a symptom, such as a slow operation, a denied connection, or missing telemetry, have no guidance on which spans, metrics, or events to look at, or how to read them.
Proposed Design
Add a troubleshooting page to the Observability section of the published docs.
- It links to the docs: add an Observability overview page covering traces, metrics, and OCSF events #4548 overview page for enabling each signal.
- It walks through a few concrete scenarios, from symptom to signal to interpretation.
- It shows only the spans, metrics, and event fields that a scenario needs. It doesn't list them all.
Which scenarios to cover is open, and suggestions from the community are welcome. Some possible examples:
- tracing the phases of a slow sandbox create;
- explaining a denied connection from its OCSF event;
- noticing dropped telemetry from the export metrics.
Acceptance Criteria
- The Observability section has a troubleshooting page with at least one worked scenario that uses traces, metrics, or OCSF events.
- The page links to the observability overview page (docs: add an Observability overview page covering traces, metrics, and OCSF events #4548) for enabling signals.
- The page is linked from
docs/index.yml.
Activity