{"id":50515132,"url":"https://github.com/dc-tec/openbao-observability","last_synced_at":"2026-06-02T23:04:22.953Z","repository":{"id":360071478,"uuid":"1248293774","full_name":"dc-tec/openbao-observability","owner":"dc-tec","description":"OpenBao observability reference architecture with metrics, logs, dashboards, alerts, fixtures, and runbooks.","archived":false,"fork":false,"pushed_at":"2026-05-24T22:10:17.000Z","size":2841,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T22:24:39.542Z","etag":null,"topics":["alloy","grafana","loki","observability","openbao","sre"],"latest_commit_sha":null,"homepage":"https://dc-tec.github.io/openbao-observability/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dc-tec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T13:01:48.000Z","updated_at":"2026-05-24T22:09:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dc-tec/openbao-observability","commit_stats":null,"previous_names":["dc-tec/openbao-observability"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dc-tec/openbao-observability","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dc-tec%2Fopenbao-observability","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dc-tec%2Fopenbao-observability/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dc-tec%2Fopenbao-observability/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dc-tec%2Fopenbao-observability/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dc-tec","download_url":"https://codeload.github.com/dc-tec/openbao-observability/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dc-tec%2Fopenbao-observability/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33840235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alloy","grafana","loki","observability","openbao","sre"],"created_at":"2026-06-02T23:04:22.109Z","updated_at":"2026-06-02T23:04:22.948Z","avatar_url":"https://github.com/dc-tec.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenBao observability reference architecture\n\n[![CI](https://github.com/dc-tec/openbao-observability/actions/workflows/ci.yml/badge.svg)](https://github.com/dc-tec/openbao-observability/actions/workflows/ci.yml)\n\nUse this repository as an OpenBao observability reference architecture for\nmetrics, operational logs, audit logs, dashboards, alerts, runbooks, and local\nvalidation fixtures. It defines portable observability intent first, then\nprovides a tested Prometheus, Loki, Grafana, and Grafana Alloy profile that you\ncan adapt to your monitoring and logging platforms.\n\nThe project starts from verified OpenBao behavior instead of copied Vault\ndashboard assumptions. Contracts under `contracts/` describe the source signal\nmodel; generated artifacts under `generated/` show one concrete implementation\nprofile.\n\n![Grafana dashboard collage showing OpenBao overview, HA/Raft, audit, and feature-specific observability panels](docs/assets/grafana-dashboards.png)\n\n*Figure 1: Generated Grafana dashboards from the local OpenBao observability\nprofile.*\n\n## What this repository provides\n\n- Signal contracts for OpenBao metrics, log streams, alerts, and dashboards.\n- Generated Prometheus recording rules and alert rules.\n- Generated Loki alert reference artifacts.\n- Generated Grafana dashboard JSON files.\n- Grafana Alloy examples for operational logs, audit logs, and collection\n  pipelines.\n- Runnable Docker Compose and Kubernetes examples.\n- Fixture capture and validation for verified OpenBao behavior.\n- Documentation for operating OpenBao observability safely.\n\n## Project status\n\nThis repository is a validated reference architecture with an implemented local\nprofile. It is not a drop-in production monitoring distribution. See\n[Project status and maturity](docs/reference-architecture/project-status.md)\nfor the detailed maturity matrix, adoption paths, roadmap, and non-goals.\n\n| Area | Current state | Confidence |\n| ---- | ------------- | ---------- |\n| Metrics contracts and prefix variants | Generated and fixture-backed for OpenBao `2.5.4`, with `vault_*` and `openbao_*` variants. | High |\n| Prometheus rules and alert rules | Generated from source contracts with runbook links. | High |\n| Grafana dashboards | Generated from dashboard contracts and validated for syntax and query structure. | Medium to high |\n| Docker Compose profile | Implemented local HA profile for evaluation, screenshots, fixture scenarios, and live query validation. | High for local evaluation |\n| Kubernetes examples | Implemented scrape and generated-artifact examples. | Medium |\n| OpenBao Operator companion profile | Implemented profile and integration contract for operator-managed clusters. | Medium |\n| Audit archive and security detections | Reference design, local profile, and generated detection artifacts. | Early to medium |\n\n## Architecture at a glance\n\nEvery implementation profile maps the same OpenBao signals to a local\nmonitoring stack. The included profile uses Prometheus for metrics, Loki for\nlogs and audit logs, Grafana Alloy for collection, and Grafana for dashboards.\n\n```mermaid\nflowchart LR\n  bao[\"OpenBao nodes\"]\n  metrics[\"Metrics backend\"]\n  oplogs[\"Operational log backend\"]\n  auditlogs[\"Audit log backend\"]\n  archive[\"Audit archive\"]\n  rules[\"Recording and alert rules\"]\n  dashboards[\"Dashboards\"]\n  runbooks[\"Runbooks\"]\n\n  bao --\u003e metrics\n  bao --\u003e oplogs\n  bao --\u003e auditlogs\n  auditlogs --\u003e archive\n\n  metrics --\u003e rules\n  oplogs --\u003e rules\n  auditlogs --\u003e rules\n\n  metrics --\u003e dashboards\n  oplogs --\u003e dashboards\n  auditlogs --\u003e dashboards\n\n  rules --\u003e runbooks\n```\n\n## Start here\n\n| Goal | Start with |\n| ---- | ---------- |\n| Understand the architecture | [Reference architecture overview](docs/reference-architecture/overview.md) |\n| Understand maturity and boundaries | [Project status and maturity](docs/reference-architecture/project-status.md) |\n| Learn the signal model | [OpenBao observability model](docs/concepts/openbao-observability-model.md) |\n| Run the local stack | [Run the Docker Compose stack](docs/docker-compose.md) |\n| Adopt the design in your platform | [Adopt the reference architecture](docs/reference-architecture/adoption.md) |\n| Use the included implementation profile | [Prometheus, Loki, Grafana, and Alloy profile][prometheus-loki-grafana-alloy] |\n| Configure metrics scraping | [Secure metrics scrape](docs/metrics/secure-metrics-scrape.md) and [all-node metrics scrape](docs/metrics/all-node-metrics-scrape.md) |\n| Read the dashboards | [Dashboard documentation](docs/README.md#dashboards) |\n| Respond to alerts | [Alert runbooks](docs/README.md#respond) |\n| Use this with the OpenBao Operator | [OpenBao Operator companion profile](docs/implementation-profiles/openbao-operator.md) |\n\nUse the [documentation index](docs/README.md) when you want the complete\ndocumentation set.\n\n## Run locally\n\nRun the local Docker Compose profile when you want to inspect the generated\ndashboards and alerts with a working OpenBao HA fixture.\n\n```shell\nmake compose-up\n```\n\nOpen Grafana at `http://127.0.0.1:13000` and sign in with `admin` / `admin`.\nSee [Run the Docker Compose stack](docs/docker-compose.md) for endpoints,\nverification steps, and troubleshooting.\n\nStop the local stack when you finish.\n\n```shell\nmake compose-down\n```\n\nRegenerate fixtures and artifacts when you change contracts, generators, or\nfixture scenarios.\n\n```shell\nmake fixtures-openbao\nmake generate\n```\n\n\u003e [!WARNING]\n\u003e The Docker Compose stack is for local evaluation and contract validation. It\n\u003e uses HTTP, deterministic local credentials, and local-only OpenBao setup. You\n\u003e must not use it for production, shared environments, or sensitive data.\n\n## Use this with your platform\n\nAdopt the architecture by preserving the OpenBao signal semantics and mapping\nthe storage, query, alerting, and dashboard layers to your environment.\n\n- Port metric contracts and alert intent to your metrics backend.\n- Port log and audit log detections to your log analytics backend.\n- Keep label and attribute choices low-cardinality and safe for shared systems.\n- Treat audit logs as protected security records with explicit retention and\n  access controls.\n- Treat dashboard panels as operator questions, then implement those questions\n  in your visualization layer.\n- Keep runbooks close to the alerts that page your team.\n\n## Tested profile\n\nThe current implementation profile includes:\n\n- OpenBao `2.5.4` fixture capture.\n- Prometheus-compatible OpenBao metrics.\n- Prometheus recording rules and alert rules.\n- Loki log and audit log alert reference artifacts.\n- Grafana dashboards generated from dashboard contracts.\n- Grafana Alloy collection examples.\n- A local Docker Compose stack with OpenBao, PostgreSQL, Prometheus, Loki,\n  Grafana Alloy, and Grafana.\n- Kubernetes examples for secure active-node and private all-node metrics\n  scrape profiles.\n\n## Generated artifacts\n\nThe repository publishes generated artifacts from source contracts under\n`contracts/`. Use these artifacts directly, or port their intent into your own\ndelivery pipeline:\n\n- `generated/prometheus/`: native Prometheus rule files.\n- `generated/prometheusrules/`: Prometheus Operator `PrometheusRule` manifests.\n- `generated/loki/`: Loki alert reference artifacts.\n- `generated/grafana/`: Grafana dashboard JSON files.\n- `generated/docs/`: generated reference documents.\n\nGenerated artifacts are outputs. Edit contracts first, then regenerate.\n\n```shell\nmake generate\n```\n\n## Validate and contribute\n\nRun the full verification before you publish or propose changes.\n\n```shell\nmake verify\n```\n\nBuild the Hugo documentation site locally when you change `docs/`, `website/`,\nor `hugo.toml`.\n\n```shell\nmake docs-build\n```\n\nValidate dashboard PromQL and LogQL against a running Compose stack when\ndashboard queries change.\n\n```shell\nmake validate-dashboard-queries\n```\n\nUse [Contributing](CONTRIBUTING.md) before you change docs, contracts,\nexamples, generated artifacts, or validation code.\n\n## Repository layout\n\n| Path | Purpose |\n| ---- | ------- |\n| `.github/` | CI and release automation. |\n| `cmd/` | Go command-line entry points for project tooling. |\n| `contracts/` | Source contracts for metrics, log streams, alerts, and dashboards. |\n| `dashboards/` | Dashboard-specific source material. |\n| `docs/` | User-facing documentation. |\n| `examples/` | Runnable local and deployment examples, including Docker Compose. |\n| `fixtures/` | Captured metrics and log fixtures used by tests. |\n| `generated/` | Generated artifacts produced from contracts. |\n| `hugo.toml` | Hugo site configuration for the documentation site. |\n| `internal/` | Go packages that implement fixture capture and validation. |\n| `website/` | Hugo layouts, assets, and site-only content. |\n\n## License\n\nThis project is licensed under the [Apache License, Version 2.0](LICENSE).\n\nCopyright 2026 OpenBao Observability contributors.\n\n[prometheus-loki-grafana-alloy]: docs/implementation-profiles/prometheus-loki-grafana-alloy.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdc-tec%2Fopenbao-observability","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdc-tec%2Fopenbao-observability","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdc-tec%2Fopenbao-observability/lists"}