Heka Insights Agent Update: Architecture + Configuration Docs Now Reflect Runtime Behavior

#python #linux #devops #observability

Build Update (April 16, 2026)

This week I focused on documentation quality and operational clarity for heka-insights-agent.

The goal was simple: make docs match the code exactly, so contributors and operators can reason about behavior without reading every module first.

What I updated

Rewrote docs/architecture.md from scratch
Rewrote docs/configuration.md from scratch
Expanded README.md with project context, setup, and environment guidance

Architecture documentation improvements

docs/architecture.md now documents:

the actual runtime topology and control loop in src/main.py
collector boundaries and behavior (CPUCollector, MemoryCollector, DiskCollector)
logging subsystem behavior in src/logger/config.py
current payload shapes emitted by collectors
known gaps (no sender layer yet, no tests yet, no schema versioning yet)
practical extension points for next phases

This gives a real “as-implemented” architecture baseline instead of aspirational text.

Configuration documentation improvements

docs/configuration.md now includes exact behavior for the two active runtime settings:

LOG_LOCATION
CPU_POLL_INTERVAL_SECONDS

It also documents:

source/precedence rules
defaults and validation behavior
failure modes
local setup and production recommendations

Important behavior clarified

Current config loading is split across two env files:

root .env is used for LOG_LOCATION
src/.env is used for CPU_POLL_INTERVAL_SECONDS

That split is now explicitly documented to reduce startup/debug confusion.

Why this matters

For an agent project, docs are part of reliability.

Operators need to know what can fail at startup, where config is read from, and what telemetry shape to expect downstream.

This update makes onboarding and future refactors safer.