Skip to content

docs(vector): restore diagrams and correct docs - #172

Merged
catinspace-au merged 3 commits into
mainfrom
docs/suite-review
Nov 16, 2026
Merged

catinspace-au merged 3 commits into
mainfrom
docs/suite-review

Conversation

@catinspace-au

Copy link
Copy Markdown
Contributor

Correct docs in the README, docs pages, CONTRIBUTING, TESTING and filebeat README.

The ledger has 921 rows: 471 PASS, 10 FAIL and 440 UNCHECKABLE. Fix the 10 FAILs.
hyperi-ai docs claims still reports 55 FAILs. Each names something defined in scalo, dfe-infra, dfe-transform-vrl, librdkafka or Vector.

Restore:

  • The README pod diagram deleted in docs(readme): explain the supervisor, build and config #157, redrawn as the top L3 view.
  • The Vector counter behind each record metric.
  • What a failed scrape does.
  • The 4 MiB cap.
  • The two flat env vars that set TLS and the SASL mechanism on both endpoints.
  • The kafka and grpc aliases.
  • The hyperi-ci chart assemble preview command.
  • The sink stall rule counting refused records as well as held ones, on all three pages that state it.

The 2 diagrams failed the checker. All 4 replacement diagrams pass on Mermaid 12.3.0.
The architecture diagram was 2129 px wide with 5 skip arrows and two levels in one picture. Replace it with separate L4 diagrams for config assembly and the direct transport bridge.
The lifecycle state diagram has its wrapper and uses landscape layout.

Fix five further doc errors:

  • Bus and direct are set per end.
  • Vector inherits the interpolation env var.
  • enable.auto.offset.store: true is rejected.
  • A custom image must hold transforms outside the config directory.
  • The DLQ start failure is caused by permissions.

Trim config comments in .hyperi-ci.yaml, Cargo.toml, deny.toml, clippy.toml, .cargo/config.toml, .gitignore and the Makefile, with every value unchanged.

Restore the README pod diagram as the repo's top L3 view, drawn to the house standard. Replace the architecture page's mixed-level diagram with an L4 of config assembly. Add an L4 of the direct transport bridge. Add a wrapper to the lifecycle state diagram in internals.md.

All four pass the checker on Mermaid 12.3.0.

Restore internals.md details:
- The Vector counter behind each record metric.
- What a failed scrape does.
- The 4 MiB scrape cap.

It names the two flat env vars that set TLS and the SASL mechanism on both endpoints. It lists the kafka and grpc transport aliases and the chart preview command.

Readiness docs match the scrape code: the sink stalls on held or refused records. TESTING.md says the filebeat case fails under CI without its sibling checkout.

Config comments are cut to pointers and short reasons in .hyperi-ci.yaml, Cargo.toml, deny.toml, clippy.toml, .cargo/config.toml, .gitignore and the Makefile. No value changes.
Figure 1 in the README drew the bridge as one box feeding Vector, but the bridge takes Vector's output back. The diagram has two bridge boxes: intake into Vector and return from Vector, matching the two listeners in src/bridge.rs. The diagram passes the checker at 864x593 on Mermaid 12.3.0.

Correct librdkafka.md's claim that config-check rejects enable.auto.offset.store: true from any layer. The check in src/config/loader.rs reads the source consumer's layers alone.
@catinspace-au
catinspace-au merged commit dff9ced into main Nov 16, 2026
13 checks passed
@catinspace-au
catinspace-au deleted the docs/suite-review branch November 16, 2026 03:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant