Skip to content

README.md

Latest commit

 

History

History
57 lines (38 loc) · 5 KB

README.md

File metadata and controls

57 lines (38 loc) · 5 KB
Raw

ObservMe examples

The npm package ships configuration examples and an extension-integration example. They are starting points, not credential stores or a complete orchestration product. Copy only what you need, review every endpoint and lifecycle transition, and keep tokens, passwords, and hash salts in environment variables or a trusted project .env file.

observme.yaml

observme.yaml is a privacy-preserving local-development profile for the repository's supported Grafana stack:

  • OTLP/HTTP exports to http://localhost:4318.
  • Grafana queries use authenticated Nginx at http://localhost; Grafana is not published directly on port 3000.
  • TLS bypass and forced IPv4 are disabled for this local HTTP profile.
  • Prompt, response, thinking, tool, and Bash capture remain disabled; capture.filePaths remains false but has no direct live recording point.
  • Redaction remains enabled and unsafe capture remains disabled.
  • Metrics export every 15 seconds and renew a 60-second active-agent lease; keep producer and Prometheus clocks synchronized within 5 seconds.

To use it in a trusted project:

  1. Copy it to <project>/<CONFIG_DIR_NAME>/observme.yaml (normally .pi/observme.yaml).
  2. Set Grafana and OTLP credentials through environment variables or a trusted project .env.
  3. Restart Pi so the session-scoped configuration is reloaded.
  4. Run /obs status and /obs health.

Read ../docs/configuration.md for the quick guide and ../docs/reference/12-configuration-reference.md for every setting.

collector.yaml

collector.yaml is a production-oriented Collector reference for a Grafana stack:

  • traces are exported to Tempo;
  • logs are exported to Loki;
  • metrics are exposed on a Prometheus scrape endpoint;
  • the five-minute metric_expiration applies to all exported metric types only as stale-series/cardinality cleanup, not active-agent liveness;
  • lease-aware PromQL joins the positive lifecycle claim and lease on generated observme_instance_id; raw observme_active_agents sums are diagnostics, not production live totals;
  • high-cardinality workflow, agent, session, and spawn attributes are removed from metrics;
  • accidental content attributes are removed from logs as defense in depth.

The example uses Collector components commonly provided by the Collector Contrib distribution. Verify that your deployed distribution includes every receiver, processor, and exporter, then replace backend endpoints and security settings for your environment.

Read ../docs/reference/05-otel-pipeline-and-collector.md for pipeline design, ../docs/reference/09-dashboards-alerts-slos.md for canonical queries and raw-query migration, and ../docs/reference/11-deployment-runbooks.md for deployment and incident checks.

For GitHub Actions, prefer graceful Pi/sidecar shutdown and an if: always() cleanup step, but do not depend on either after force cancellation. Lease expiry provides correctness without a Collector restart. GitHub-hosted runner clocks meet the supported expectation; self-hosted runners must use reliable time synchronization.

integrations/subagent-runner.ts

integrations/subagent-runner.ts demonstrates how another Pi extension can wrap any child transport with ObservMe's versioned integration API. The transport interface can represent a local subprocess, Pi RPC, tmux, SSH, a container, a queue, or another process manager.

The generic adapter records launcher success immediately after transport-handle acquisition, keeps terminal child completion separate, and records launcher failure, wait, join, cancellation, timeout, and failure propagation while passing the returned environment to the transport unchanged. Returned terminal child statuses end the child; timeout, wait abort, and transport-read failure keep it active. Use start() and retry the returned execution's wait() method when later completion must remain reachable after a non-terminal outcome. The adapter does not prescribe task delivery, process management, result encoding, concurrency, retries, durable state, or child-ID handshake.

Read ../docs/extension-integration.md before adapting it and ../docs/agent-subagent-observability-requirements.md for the complete orchestration contract.

Safety notes

  • Do not place real secrets directly in either YAML file.
  • Keep content capture disabled unless there is an explicit, reviewed need.
  • Keep redaction enabled for captured content and configure OBSERVME_HASH_SALT.
  • Do not promote session, workflow, agent, trace, span, entry, or tool-call IDs to Prometheus labels.
  • Use insecure transport or certificate verification bypass only for controlled local development.