docs(observability): developer onboarding page + per-component pages + CONTEXT.md#208
Merged
Merged
Conversation
…TEXT Add the documentation deliverables for the ADR-0007 self-hosted observability stack (tracer-bullet #8 of the #176 PRD). - Developer onboarding page (platform/observability-for-developers): the ServiceMonitor metrics contract, zero-action log collection, the PrometheusRule path for per-namespace alerting, the documented OTLP endpoint (with a clear Phase-3/Tempo callout), and the Scratch → code dashboard workflow. Each contract carries a copy-paste YAML snippet. - Per-component pages for kube-prometheus-stack, Loki, and Alloy under applications/, mirroring the existing adguard-home / homepage shape. - A stack-level Observability page narrating how the three components fit together, with a data-flow diagram. - CONTEXT.md: a new Observability section defining the `observability` namespace, the stack, and the Discord/healthchecks.io alert pipeline. - Register the three new addons in the applications index, and correct now-stale "observability is deferred" framing in hubble-ui.md and metrics-server.md so the docs site is internally consistent. Closes: #185 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Documentation deliverables for the ADR-0007 self-hosted observability
stack — tracer-bullet #8 of the #176 PRD. Five new docs pages plus
CONTEXT.md updates, all in one PR so the cross-links resolve.
New pages
platform/observability-for-developers.md— the one-pagedeveloper contract: the
ServiceMonitormetrics contract, zero-actionlog collection, the
PrometheusRulepath for per-namespace alerting,the documented OTLP push endpoint (with a clear callout that Tempo is
Phase 3), and the Scratch → code dashboard promotion workflow. The
ServiceMonitorandPrometheusRulesnippets are valid YAML —verified with
kubectl apply --dry-run=client.applications/kube-prometheus-stack.md,loki.md,alloy.md— per-component pages mirroring the existingadguard-home.md/homepage.mdstructure.applications/observability.md— stack-level page narrating howthe three components fit together, with a data-flow diagram (story 29).
CONTEXT.md
A new
## Observabilitysection defines theobservabilitynamespace,the observability stack, and the Discord/healthchecks.io alert pipeline.
Also in this PR
applications/index table.platform/index.mdgains a pointer to the developer page.hubble-ui.mdandmetrics-server.mdboth stillsaid observability was "a deferred Phase-2 deep-dive" / "there is no
Prometheus, no Grafana." Corrected to the now-true coexistence framing
(ADR-0007 explicitly keeps Hubble UI alongside the new stack) so the
docs site is not self-contradicting.
overview/architecture.md'sStatus snapshot was left alone — it couples observability with the
separate Longhorn phase question and is a broader refresh.
Testing
npm run build(Astro/Starlight) passes — 24 pages, all five newpages built.
files resolve to existing pages/anchors.
kubectl apply --dry-run=clientcleanly.Note
The Discord/healthchecks.io alert pipeline is documented per its
ADR-0007 design; the receivers themselves ship in a separate stack
slice (#176 tracer-bullet #6). The CONTEXT.md entry and the
Observability page both state plainly that until that slice lands,
Alertmanager runs but routes nothing externally.
Closes: #185
🤖 Generated with Claude Code