Skip to content

docs(observability): restructure the Observability section to remove overlap between pages #4561

Open

Description

@krishicks

User Story

As an operator of OpenShell,
I want each Observability docs page to cover one topic, described in one place,
so that I don't have to piece together how sandbox logs and OCSF events work from pages that repeat each other.

Problem Statement

The Observability section splits sandbox logging across two pages and spreads OCSF export across three:

  • Logging and Accessing Logs both describe the supervisor's /var/log files, rotation, and storage per compute driver, and both show openshell logs output. The grep recipes for reading the shorthand format are on Accessing Logs, away from the format they parse.
  • Logging includes Proxy Error Responses, which describes the JSON body an agent receives on a denied or failed request. That isn't logging, and how-it-works/policies/network-rules.mdx already covers those error codes.
  • The table of OCSF event classes appears on both Logging and OCSF JSON Export.
  • OCSF export over OTLP has no Observability page. Its record format, delivery, and loss reporting are only in the gateway configuration reference. The schema version downgrade, which applies to both JSONL and OTLP, is documented only for JSONL.
  • Telemetry includes a section on selecting compute drivers at build time, which has nothing to do with observability.

Proposed Design

Observability
├── Overview
├── Traces
├── Gateway Metrics
├── Sandbox Logs   (Logging and Accessing Logs merged)
├── OCSF Export    (renamed from OCSF JSON Export)
└── Telemetry
  • Sandbox Logs:
    1. Viewing logs with the CLI and TUI.
    2. Reading the format: tracing compared with OCSF shorthand, the parts of a shorthand line, denial reasons, filesystem events, and the grep recipes.
    3. Where logs live: supervisor files per compute driver, main process output, and the gateway's buffer, each described once.
    4. Loss and resume.
  • OCSF Export:
    • Event structure, with the single table of event classes and an example record.
    • JSONL files: the gateway, supervisor, and Windows MXC outputs.
    • OTLP log export: the record format and delivery details, moved from the gateway configuration reference, which keeps only the settings.
    • Schema versions for both outputs.
    • SIEM integration.
  • Proxy Error Responses moves to Network Rules.
  • Telemetry's compute-driver build section moves to wherever building the gateway is documented.
  • Old URLs redirect to the new pages.

The Overview trim, the new Traces page, and moving metric names into Gateway Metrics happen in #4560.

Acceptance Criteria

  • Sandbox log locations, rotation, and storage are described on one page.
  • The OCSF event class table appears once.
  • OCSF Export documents both JSONL and OTLP output, and schema versions for both.
  • Proxy Error Responses and the compute-driver build section live outside Observability.
  • /observability/logging, /observability/accessing-logs, and /observability/ocsf-json-export redirect to the new pages, and in-repo links are updated.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsDocumentation and examplestopic:observabilityLogging, metrics, and observability work

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions