Repository navigation
docs(observability): restructure the Observability section to remove overlap between pages #4561
Copy link
Copy link
Open
Labels
area:docsDocumentation and examplesDocumentation and examplestopic:observabilityLogging, metrics, and observability workLogging, metrics, and observability work
Description
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/logfiles, rotation, and storage per compute driver, and both showopenshell logsoutput. 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.mdxalready 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:
- Viewing logs with the CLI and TUI.
- Reading the format: tracing compared with OCSF shorthand, the parts of a shorthand line, denial reasons, filesystem events, and the grep recipes.
- Where logs live: supervisor files per compute driver, main process output, and the gateway's buffer, each described once.
- 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-exportredirect to the new pages, and in-repo links are updated.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
area:docsDocumentation and examplesDocumentation and examplestopic:observabilityLogging, metrics, and observability workLogging, metrics, and observability work
Type
Projects
- StatusShow more project fieldsPlanning
Activity