Repository navigation
Open
Labels
retired:area:docsRetired; do not apply. See #5151 for item-specific migration to the current taxonomy.Retired; do not apply. See #5151 for item-specific migration to the current taxonomy.topic:observabilityLogs, metrics, traces, telemetry, dashboards, event correlation, and operational data export.Logs, metrics, traces, telemetry, dashboards, event correlation, and operational data export.
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.
Metadata
Metadata
Assignees
Labels
retired:area:docsRetired; do not apply. See #5151 for item-specific migration to the current taxonomy.Retired; do not apply. See #5151 for item-specific migration to the current taxonomy.topic:observabilityLogs, metrics, traces, telemetry, dashboards, event correlation, and operational data export.Logs, metrics, traces, telemetry, dashboards, event correlation, and operational data export.
Type
Projects
- StatusShow more project fieldsBacklog
Activity
github-actions commentedon Nov 12, 2026
This issue has had no activity for 28 days and is now marked stale. It may be closed in 14 days if there is no further activity. Comment or remove the state:stale label to keep it open.