Repository navigation
docs: Document the telemetry architecture as built - #271
Merged
Merged
Conversation
The batch processor comment cited an issue in a private deployment repository, which readers of this public repository can't open. The comment already explains the sizing, so the reference adds nothing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The repository is gaining architecture docs under docs/, and nothing checked their formatting. task docs:lint runs markdownlint-cli2 from its pinned Docker image, the same way the docs task already renders the PlantUML diagrams, so the repository takes on no Node tooling. The root lint task, and so task ci, now includes it, and a Docs workflow runs it on every pull request. Prose wraps at 80 columns. Tables, code blocks, and headings are exempt. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The telemetry architecture was documented only as design proposals in another repository, written before most of the system was built, and those had drifted from the code. These docs describe the system as built: ingest from the edge collectors through NATS, edge-to-hub trust, log storage and retention in ClickHouse, the query API and its clients, and export policies, with one C4 container diagram for each. Each claim was checked against the code at this commit and against a running deployment, and content describing unbuilt work was removed. The unbuilt designs need major revisions and will follow separately. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
0xmc
force-pushed
the
docs/architecture-port
branch
from
November 10, 2026 22:07
1a2b95e to
cb39a02
Compare
0xmc
marked this pull request as ready for review
November 10, 2026 22:25
0xmc
enabled auto-merge
November 10, 2026 22:25
ecv
approved these changes
Nov 10, 2026
ecv
left a comment
ecv
left a comment
Contributor
There was a problem hiding this comment.
Approve.
Spot-checked the most specific claims against the code at head and found none false. The sink-collector.yaml change only drops the "(infra#5519)" reference from a comment.
- Verified against code: queryapi defaults (limit 100 clamped to 5000, 30s timeout, 31-day max range, 32 MiB response cap,
CLICKHOUSE_USERdefaultqueryapi); retention migration 000003 (internal 1d cold and 30d delete, others 7d, 36500d sentinel);nkey-generatoruser table (edge publisho11y.{logs,metrics,traces}.<cluster>.*, subscribe_INBOX.>;nackand sink CN mappings and permissions); ExportPolicy 1 to 20 items and 63-char DNS-label names; gateway collector 2 replicas on 4317;handshake_firstinconfig/collectors/nats.yaml; internal project assignment intransform/milo_project_id. - Not checkable in this repo: hub port 7422, the 10-minute CronJob schedule, and the Let's Encrypt and DNS-01 setup. The docs already say the CronJob manifest lives outside the repo (#145), so these rest on the deployment rather than on code.
.github/workflows/docs.ymlhaspermissions: contents: readand a pinnedarduino/setup-taskSHA, butactions/checkout@v7is a tag. That matches the repo's other workflows (lint.ymluses tags too), so not a regression.
Follow-ups:
- Pin
actions/checkoutby SHA indocs.yml, ideally across the workflows together. - The docs correctly state that no test shows the hub refusing a forged publish; worth filing as a test gap.
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
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.
Summary
The only architecture docs for this system were design proposals that had drifted far from the code.
This adds architecture docs for ingest, edge-to-hub trust, log storage and retention, the query API, and export policies, each with a C4 container diagram, with every claim checked against the code and a running deployment. Unbuilt designs follow in a separate pull request.
Markdown in the docs is now linted in CI, and a private issue reference is dropped from a collector config.
Test plan
Fixes #270
🤖 Generated with Claude Code