From 80b88641e52f5bfd2c8f3677eee7b0001c659c4b Mon Sep 17 00:00:00 2001 From: Artem Kovalov Date: Wed, 30 Sep 2026 01:17:11 +0200 Subject: [PATCH 1/2] docs: promote observability to a top-level section Move observability docs out of storage/ into a dedicated top-level section, reflecting that Prometheus, Perses, and Prysm cover the whole platform rather than storage alone. - Add Observability to the Documentation nav - Introduce observabilitySidebar() matching the Storage pattern: non-link section header with Overview as the first linked entry - Update cross-links in architecture, getting-started, management, and storage overview pages - Add Storage Overview as a highlighted sidebar entry using storageSidebar() with the same non-link header pattern Signed-off-by: Artem Kovalov --- docs/.vitepress/config.mts | 224 +++++++++++------- docs/getting-started/full-deployment.md | 6 +- docs/management/greenhouse.md | 2 +- docs/{storage => }/observability/index.md | 6 +- docs/{storage => }/observability/perses.md | 0 .../{storage => }/observability/prometheus.md | 0 docs/{storage => }/observability/prysm.md | 0 docs/overview/architecture.md | 6 +- docs/overview/index.md | 2 +- docs/storage/index.md | 10 +- 10 files changed, 147 insertions(+), 109 deletions(-) rename docs/{storage => }/observability/index.md (96%) rename docs/{storage => }/observability/perses.md (100%) rename docs/{storage => }/observability/prometheus.md (100%) rename docs/{storage => }/observability/prysm.md (100%) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index fa3c700..13cfc59 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -2,6 +2,51 @@ import { withMermaid } from "vitepress-plugin-mermaid"; import { generateSidebar } from 'vitepress-sidebar'; import { fileURLToPath, URL } from 'node:url' +function storageSidebar() { + const generated = generateSidebar([{ + documentRootPath: '/docs/', + scanStartPath: 'storage', + resolvePath: '/storage/', + capitalizeFirst: false, + useTitleFromFrontmatter: true, + useFolderLinkFromIndexFile: true, + useFolderTitleFromIndexFile: true, + sortMenusByFrontmatterOrder: true, + excludePattern: ['observability/**'], + }]); + const items = generated['/storage/'].items.filter((i: any) => i.link !== 'index.md'); + return { + '/storage/': { + base: '/storage/', + items: [ + { text: 'Storage', items: [{ text: 'Overview', link: 'index.md' }, ...items] }, + ], + }, + }; +} + +function observabilitySidebar() { + const generated = generateSidebar([{ + documentRootPath: '/docs/', + scanStartPath: 'observability', + resolvePath: '/observability/', + capitalizeFirst: false, + useTitleFromFrontmatter: true, + useFolderLinkFromIndexFile: true, + useFolderTitleFromIndexFile: true, + sortMenusByFrontmatterOrder: true, + }]); + const items = generated['/observability/'].items.filter((i: any) => i.link !== 'index.md'); + return { + '/observability/': { + base: '/observability/', + items: [ + { text: 'Observability', items: [{ text: 'Overview', link: 'index.md' }, ...items] }, + ], + }, + }; +} + // https://vitepress.dev/reference/site-config export default withMermaid({ title: "CobaltCore", @@ -34,6 +79,7 @@ export default withMermaid({ { text: 'OpenStack', link: '/openstack/' }, { text: 'Storage', link: '/storage/' }, { text: 'Networking', link: '/networking/' }, + { text: 'Observability', link: '/observability/' }, { text: 'Management', link: '/management/' }, { text: 'API Reference', link: '/api/' }, ], @@ -56,98 +102,92 @@ export default withMermaid({ provider: 'local' }, - sidebar: generateSidebar([ - { - documentRootPath: '/docs/', - scanStartPath: 'overview', - resolvePath: '/overview/', - capitalizeFirst: false, - useTitleFromFrontmatter: true, - useFolderLinkFromIndexFile: true, - useFolderTitleFromIndexFile: true, - sortMenusByFrontmatterOrder: true, - }, - { - documentRootPath: '/docs/', - scanStartPath: 'getting-started', - resolvePath: '/getting-started/', - capitalizeFirst: false, - useTitleFromFrontmatter: true, - useFolderLinkFromIndexFile: true, - useFolderTitleFromIndexFile: true, - sortMenusByFrontmatterOrder: true, - }, - { - documentRootPath: '/docs/', - scanStartPath: 'platform', - resolvePath: '/platform/', - capitalizeFirst: false, - useTitleFromFrontmatter: true, - useFolderLinkFromIndexFile: true, - useFolderTitleFromIndexFile: true, - sortMenusByFrontmatterOrder: true, - }, - { - documentRootPath: '/docs/', - scanStartPath: 'compute', - resolvePath: '/compute/', - capitalizeFirst: false, - useTitleFromFrontmatter: true, - useFolderLinkFromIndexFile: true, - useFolderTitleFromIndexFile: true, - sortMenusByFrontmatterOrder: true, - }, - { - documentRootPath: '/docs/', - scanStartPath: 'openstack', - resolvePath: '/openstack/', - capitalizeFirst: false, - useTitleFromFrontmatter: true, - useFolderLinkFromIndexFile: true, - useFolderTitleFromIndexFile: true, - sortMenusByFrontmatterOrder: true, - }, - { - documentRootPath: '/docs/', - scanStartPath: 'storage', - resolvePath: '/storage/', - capitalizeFirst: false, - useTitleFromFrontmatter: true, - useFolderLinkFromIndexFile: true, - useFolderTitleFromIndexFile: true, - sortMenusByFrontmatterOrder: true, - }, - { - documentRootPath: '/docs/', - scanStartPath: 'networking', - resolvePath: '/networking/', - capitalizeFirst: false, - useTitleFromFrontmatter: true, - useFolderLinkFromIndexFile: true, - useFolderTitleFromIndexFile: true, - sortMenusByFrontmatterOrder: true, - }, - { - documentRootPath: '/docs/', - scanStartPath: 'management', - resolvePath: '/management/', - capitalizeFirst: false, - useTitleFromFrontmatter: true, - useFolderLinkFromIndexFile: true, - useFolderTitleFromIndexFile: true, - sortMenusByFrontmatterOrder: true, - }, - { - documentRootPath: '/docs/', - scanStartPath: 'community', - resolvePath: '/community/', - capitalizeFirst: false, - useTitleFromFrontmatter: true, - useFolderLinkFromIndexFile: true, - useFolderTitleFromIndexFile: true, - sortMenusByFrontmatterOrder: true, - }, - ]), + sidebar: { + ...generateSidebar([ + { + documentRootPath: '/docs/', + scanStartPath: 'overview', + resolvePath: '/overview/', + capitalizeFirst: false, + useTitleFromFrontmatter: true, + useFolderLinkFromIndexFile: true, + useFolderTitleFromIndexFile: true, + sortMenusByFrontmatterOrder: true, + }, + { + documentRootPath: '/docs/', + scanStartPath: 'getting-started', + resolvePath: '/getting-started/', + capitalizeFirst: false, + useTitleFromFrontmatter: true, + useFolderLinkFromIndexFile: true, + useFolderTitleFromIndexFile: true, + sortMenusByFrontmatterOrder: true, + }, + { + documentRootPath: '/docs/', + scanStartPath: 'platform', + resolvePath: '/platform/', + capitalizeFirst: false, + useTitleFromFrontmatter: true, + useFolderLinkFromIndexFile: true, + useFolderTitleFromIndexFile: true, + sortMenusByFrontmatterOrder: true, + }, + { + documentRootPath: '/docs/', + scanStartPath: 'compute', + resolvePath: '/compute/', + capitalizeFirst: false, + useTitleFromFrontmatter: true, + useFolderLinkFromIndexFile: true, + useFolderTitleFromIndexFile: true, + sortMenusByFrontmatterOrder: true, + }, + { + documentRootPath: '/docs/', + scanStartPath: 'openstack', + resolvePath: '/openstack/', + capitalizeFirst: false, + useTitleFromFrontmatter: true, + useFolderLinkFromIndexFile: true, + useFolderTitleFromIndexFile: true, + sortMenusByFrontmatterOrder: true, + }, + { + documentRootPath: '/docs/', + scanStartPath: 'networking', + resolvePath: '/networking/', + capitalizeFirst: false, + useTitleFromFrontmatter: true, + useFolderLinkFromIndexFile: true, + useFolderTitleFromIndexFile: true, + sortMenusByFrontmatterOrder: true, + }, + { + documentRootPath: '/docs/', + scanStartPath: 'management', + resolvePath: '/management/', + capitalizeFirst: false, + useTitleFromFrontmatter: true, + useFolderLinkFromIndexFile: true, + useFolderTitleFromIndexFile: true, + sortMenusByFrontmatterOrder: true, + }, + { + documentRootPath: '/docs/', + scanStartPath: 'community', + resolvePath: '/community/', + capitalizeFirst: false, + useTitleFromFrontmatter: true, + useFolderLinkFromIndexFile: true, + useFolderTitleFromIndexFile: true, + sortMenusByFrontmatterOrder: true, + }, + ]), + ...storageSidebar(), + ...observabilitySidebar(), + }, socialLinks: [ { icon: 'github', link: 'https://github.com/cobaltcore-dev' } diff --git a/docs/getting-started/full-deployment.md b/docs/getting-started/full-deployment.md index 7de5e0d..4e5542c 100644 --- a/docs/getting-started/full-deployment.md +++ b/docs/getting-started/full-deployment.md @@ -80,9 +80,9 @@ Follow the [Minimal Environment](/getting-started/minimal) guide first to unders ### Observability layer -- [ ] Prysm deployed and collecting events - see [Observability - Prysm](/storage/observability/prysm) -- [ ] Prometheus scraping all targets - see [Observability - Prometheus](/storage/observability/prometheus) -- [ ] Perses dashboards deployed - see [Observability - Perses](/storage/observability/perses) +- [ ] Prysm deployed and collecting events - see [Observability - Prysm](/observability/prysm) +- [ ] Prometheus scraping all targets - see [Observability - Prometheus](/observability/prometheus) +- [ ] Perses dashboards deployed - see [Observability - Perses](/observability/perses) - [ ] Alerting rules configured and routing verified ### Management layer diff --git a/docs/management/greenhouse.md b/docs/management/greenhouse.md index 0f02b31..6695459 100644 --- a/docs/management/greenhouse.md +++ b/docs/management/greenhouse.md @@ -22,4 +22,4 @@ Greenhouse aggregates operational views from multiple tools - Prometheus, Perses - [Greenhouse documentation](https://cloudoperators.github.io/greenhouse/) - [Greenhouse GitHub](https://github.com/cloudoperators/greenhouse) -- [Observability](/storage/observability/) - Prometheus and Perses, which Greenhouse surfaces +- [Observability](/observability/) - Prometheus and Perses, which Greenhouse surfaces diff --git a/docs/storage/observability/index.md b/docs/observability/index.md similarity index 96% rename from docs/storage/observability/index.md rename to docs/observability/index.md index e0d295e..fa0521c 100644 --- a/docs/storage/observability/index.md +++ b/docs/observability/index.md @@ -1,10 +1,10 @@ --- -title: Observability & Audit -order: 80 +title: Overview +order: 1 outline: deep --- -# Observability & Audit +# Observability CobaltCore's observability stack provides real-time visibility into every layer - compute, storage, networking, and OpenStack services. It combines Prometheus for metrics, Perses for dashboards, and Prysm for storage-specific monitoring and audit. diff --git a/docs/storage/observability/perses.md b/docs/observability/perses.md similarity index 100% rename from docs/storage/observability/perses.md rename to docs/observability/perses.md diff --git a/docs/storage/observability/prometheus.md b/docs/observability/prometheus.md similarity index 100% rename from docs/storage/observability/prometheus.md rename to docs/observability/prometheus.md diff --git a/docs/storage/observability/prysm.md b/docs/observability/prysm.md similarity index 100% rename from docs/storage/observability/prysm.md rename to docs/observability/prysm.md diff --git a/docs/overview/architecture.md b/docs/overview/architecture.md index 627806a..c1ca33b 100644 --- a/docs/overview/architecture.md +++ b/docs/overview/architecture.md @@ -42,9 +42,9 @@ The infrastructure data plane - the raw execution environment for virtual machin ## Observability -Cross-cutting. [Prysm](/storage/observability/prysm) collects audit and operational -events. [Prometheus](/storage/observability/prometheus) scrapes metrics from all -layers. [Perses](/storage/observability/perses) provides dashboards. +Cross-cutting. [Prysm](/observability/prysm) collects audit and operational +events. [Prometheus](/observability/prometheus) scrapes metrics from all +layers. [Perses](/observability/perses) provides dashboards. ## OpenStack diff --git a/docs/overview/index.md b/docs/overview/index.md index ddea7e2..a673e77 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -36,4 +36,4 @@ CobaltCore is for teams that: - **[Architecture](/overview/architecture)** - understand how the layers fit together - **[Why CobaltCore](/overview/why)** - the reasoning behind the design decisions - **[Showroom](/showroom/)** - live examples and demos of CobaltCore in action -- Layer sections (**Platform**, **Compute**, **OpenStack**, **Storage**, **Networking**, **Management**) - deep-dive reference for each part of the stack. Storage includes the observability documentation. +- Layer sections (**Platform**, **Compute**, **OpenStack**, **Storage**, **Networking**, **Observability**, **Management**) - deep-dive reference for each part of the stack. diff --git a/docs/storage/index.md b/docs/storage/index.md index 87faa42..96ed9fc 100644 --- a/docs/storage/index.md +++ b/docs/storage/index.md @@ -1,17 +1,16 @@ --- -title: Storage +title: Overview order: 1 outline: deep --- -# Storage +# Storage Overview CobaltCore's cloud storage layer is built on [Ceph](./ceph.md), a distributed storage system that delivers object, block, and file storage in a single unified platform. The surrounding components handle lifecycle automation, data replication, high-availability quorum, observability, and quota and usage metering - each with a focused responsibility. ## Architecture -The storage stack is organized into three layers, with observability providing -cross-cutting metrics, dashboards, alerting, and audit across them: +The storage stack is organized into three layers. See [Observability & Audit](/observability/) for metrics, dashboards, and alerting across the stack. **Foundation** - Ceph provides the core distributed storage engine. All other components either operate it, extend it, or observe it. @@ -28,7 +27,6 @@ cross-cutting metrics, dashboards, alerting, and audit across them: | [Arbiter](./arbiter.md) | Operations | External Ceph monitors for quorum in stretched clusters | | [Chorus](./chorus.md) | Data Services | Zero-downtime object storage replication and migration | | [Liquid-Ceph](./liquid-ceph.md) | Data Services | Limes integration for RGW quota, capacity, and usage metering | -| [Observability & Audit](./observability/) | Cross-cutting | Metrics, dashboards, alerting, and audit - Prometheus, Perses, Prysm | ## Storage Interfaces @@ -75,4 +73,4 @@ Ceph achieves HA through monitor quorum (typically 3 or 5 monitors), OSD replica - [Ceph Upstream Architecture Docs](https://docs.ceph.com/en/latest/architecture/) - [Rook Documentation](https://rook.io/docs/rook/latest-release/Getting-Started/intro/) -- [Observability & Audit](./observability/) - Prometheus metrics, Perses dashboards, and Prysm CLI for the storage stack +- [Observability & Audit](/observability/) - Prometheus metrics, Perses dashboards, and Prysm CLI for the storage stack From 62af8440d604e386889abe841f035f7476c64112 Mon Sep 17 00:00:00 2001 From: Artem Kovalov Date: Wed, 30 Sep 2026 01:22:18 +0200 Subject: [PATCH 2/2] docs: fix dead link in prysm.md after observability move Update relative ../ceph link to absolute /storage/ceph now that prysm.md lives under observability/ rather than storage/observability/. Signed-off-by: Artem Kovalov --- docs/observability/prysm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/observability/prysm.md b/docs/observability/prysm.md index 22ccfb4..40003b4 100644 --- a/docs/observability/prysm.md +++ b/docs/observability/prysm.md @@ -63,4 +63,4 @@ Prysm supports three output modes: ## See also - [Observability - Prometheus](./prometheus) -- [Storage - Ceph](../ceph) +- [Storage - Ceph](/storage/ceph)