Skip to content

docs: add an Observability troubleshooting page #4550

Open

Description

@krishicks

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.

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

Related: #1055, #4548

Activity

  1. added
    retired:area:docsRetired; 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.
    on Oct 14, 2026
  2. moved this from Planning to Backlog in OpenShell Roadmapon Oct 19, 2026
  3. github-actions commented on Nov 12, 2026

    @github-actions

    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.

  4. removed
    state:staleInactive item at risk of automatic closure.
    on Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    retired:area:docsRetired; 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.

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions