Skip to content

README.md

Latest commit

 

History

History
54 lines (39 loc) · 5.45 KB

README.md

File metadata and controls

54 lines (39 loc) · 5.45 KB
Raw

ObservMe documentation

This page is the entry point for ObservMe user, operator, and contributor documentation. Start with the task-oriented guides, then open the deeper reference only when you need implementation or telemetry-contract detail.

Start here

Goal Read first Then, if needed
Install ObservMe and learn /obs commands ../README.md configuration.md
Configure a trusted project configuration.md reference/12-configuration-reference.md
Validate Grafana and /obs together validation-flow.md reference/11-deployment-runbooks.md
Check supported versions compatibility-matrix.md reference/10-testing-release-operations.md
Understand privacy and content capture ../SECURITY.md reference/06-security-privacy-redaction.md
Configure an OTEL Collector ../examples/README.md reference/05-otel-pipeline-and-collector.md
Understand metrics, spans, logs, and labels ../README.md#available-telemetry reference/04-telemetry-semantic-conventions.md
Operate dashboards, alerts, and SLOs ../README.md#dashboards-and-examples reference/09-dashboards-alerts-slos.md
Understand architecture and lifecycle reference/02-reference-architecture.md reference/03-pi-event-and-session-model.md
Integrate another Pi extension or orchestrator extension-integration.md agent-subagent-observability-requirements.md
Diagnose parent/subagent lineage (every agent shows as root) extension-integration.md#troubleshooting-every-agent-appears-as-its-own-root agent-subagent-observability-requirements.md

User and operator guides

  • configuration.md — project config creation, fields to edit, credentials, privacy defaults, and precedence.
  • validation-flow.md — secret-safe troubleshooting when Grafana or /obs does not behave as expected.
  • compatibility-matrix.md — tested Pi, Node.js, OpenTelemetry, Collector, and Grafana-stack versions.
  • ../examples/README.md — purpose and safe use of the shipped configuration and integration examples.
  • extension-integration.md — public event-bus API for orchestrators, subagent runners, and other Pi extensions.
  • ../SECURITY.md — package trust model and vulnerability reporting.

Technical reference

reference/00-README.md is the reference index. Use it for architecture, Pi event mapping, telemetry semantics, Collector design, privacy rules, query behavior, dashboards, testing, deployment, and the complete configuration schema.

The reference set is detailed and may describe reserved contracts as well as live behavior. The telemetry tables in ../README.md#available-telemetry identify signals that are reserved or registered but not currently recorded.

Contributor and design notes

These documents support extension development and are not the shortest path for normal setup:

Documentation precedence

Runtime code and shipped configuration are the behavioral source of truth. For documentation-only overlap, use this order:

  1. ../README.md and the task-oriented guides in this directory for current user-facing behavior.
  2. reference/12-configuration-reference.md for the documented configuration contract.
  3. The remaining production reference documents for architecture and implementation detail.
  4. Contributor/design notes for repository work and future integration requirements.

For an exact or disputed behavior, verify the owning source: src/commands/ for /obs, src/config/ for configuration, src/semconv/ plus src/pi/ recording points for telemetry, src/privacy/ for capture/redaction, src/integration.ts plus src/pi/integration-api.ts for integration, and observability-stack/ for the repository-only stack. If source and docs conflict, state the drift and correct the docs rather than silently combining them. Never include credentials, raw prompts, raw commands, or other sensitive values in examples or troubleshooting output.