| 1 | # runtimechartemit |
| 2 | |
| 3 | This package is the runtime/internal metrics bridge between component-owned |
| 4 | `metrix.RuntimeStore` writers and Netdata chart protocol output. |
| 5 | |
| 6 | ## Registration flow |
| 7 | |
| 8 | 1. Component code creates/owns a `metrix.RuntimeStore` (writer side). |
| 9 | 2. Component registers itself via `runtimecomp.Service.RegisterComponent(...)` with: |
| 10 | - stable `Name` |
| 11 | - `Store` |
| 12 | - optional `TemplateYAML` (or `Autogen.Enabled=true` for fallback template) |
| 13 | - cadence metadata (`UpdateEvery`) and emit env metadata (`TypeID`, `Plugin`, `Module`, `JobName`, `JobLabels`). |
| 14 | 3. Service normalizes config and upserts it into the internal component registry. |
| 15 | 4. Runtime metrics job snapshots registry entries on each tick. |
| 16 | 5. For each component due on this tick: |
| 17 | - read component store via `Read(metrix.ReadRaw(), metrix.ReadFlatten())` |
| 18 | - build plan with chartengine |
| 19 | - emit plan through `chartemit.ApplyPlan(...)`. |
| 20 | 6. When component is unregistered, runtime job emits obsolete/remove actions for previously known charts. |
| 21 | |
| 22 | ## Lifecycle ownership |
| 23 | |
| 24 | - `Service.Start(pluginName, out)` starts runtime metrics job and cadence ticker. |
| 25 | - `Service.Stop()` stops ticker and runtime job. |
| 26 | - Components should register on start and unregister on stop to avoid stale runtime charts. |
| 27 | |
| 28 | ## Producers vs components |
| 29 | |
| 30 | - Components: register a runtime store to be charted. |
| 31 | - Producers: register a `tickFn` callback via `RegisterProducer` when a runtime source has no independent owner loop and must be advanced by runtime service cadence. |
| 32 | |
| 33 | ## Operational notes |
| 34 | |
| 35 | - Runtime metrics job is intentionally single-flight; overlapping ticks are skipped and logged. |
| 36 | - Observer chartengine runs with `WithRuntimeStore(nil)` (no self-instrumentation loop). |
| 37 | - `Name` is the registry identity; re-registering the same name replaces generation and reinitializes runtime chart state. |