MetricsHub
MetricsHub Community Connectors 1.0.24
-
Home
- Connector Developer Guide Connector Structure 7
Design Principles
This page defines the default engineering bar for connector contributions.
1. Determinism Over Cleverness
A connector should behave predictably across runs and environments.
- Use stable IDs, not display labels, for
attributes.id. - Keep detection based on deterministic signatures.
- Avoid brittle regexes tied to formatting noise.
2. Cost-Aware Detection
Detection should be ordered from cheapest to most expensive.
- cheap protocol/table existence check first
- authenticated/product-specific check next
- expensive data pulls last (if needed at all)
For HTTP detection, prefer status checks when body parsing is unnecessary.
3. Reuse Data, Do Not Re-fetch
Use source composition to minimize remote calls:
beforeAllfor login/bootstrap/shared datacopyfor branchingtableJoinandtableUnionfor compositioninternalDbQueryfor dedup/aggregation when joins alone are not enough
4. Normalize Early
Perform status and unit normalization before mapping:
translatefor status/code dictionariesconvertfor format conversionsdivide/multiplyfor unitskeepOnlyMatchingLines/excludeMatchingLinesearly to reduce volume
5. Make Mapping Boring
Good mapping is mostly straightforward column assignment.
mapping:
source: ${source::sensors}
attributes:
id: $1
name: $2
metrics:
hw.status{hw.type="fan"}: $3
hw.fan.speed: $4
If mapping is doing heavy parsing, push that logic back into computes.
6. Prefer Modern Connector Style
For new or heavily revised connectors:
- prefer explicit source names (
ports,inventory,clusterInfo) - prefer
simplejobs when two-phase behavior is not required - prefer canonical type names (
commandLine,json2Csv,xml2Csv)
7. Design for Reviewability
Reviewers should infer behavior quickly.
- Keep source pipelines short and coherent.
- Use comments only where they explain non-obvious transforms.
- Group related monitors and avoid copy-paste drift.
8. Validate with Replay Tests
No connector change is complete until replay test behavior is understood.
- update emulation inputs when behavior intentionally changes
- update expected output only for deliberate semantic changes
- keep expected payload stable and host-normalized
9. Build Instances from an Inventory
From MetricsHub Community 3.9.08, an instance that a trusted discovery or simple run no longer returns is removed (see When Instances Are Removed[1]). The rows that create the instances must list every entity that exists, not only the ones that are active, healthy, or reporting a value.
- Take the mapping source from an inventory, and attach the statistics to it:
- keep the inventory as the left table of a
tableJoin[2] and set adefaultRightLine, so an entity without statistics keeps its row with empty cells (or look the statistics up from the inventory in anawkcompute); - or split the monitor:
discoverymaps the inventory,collectmaps the statistics. A row missing from acollectjob never removes anything.
- keep the inventory as the left table of a
- Do not filter on a state or a value in a job that creates monitors:
Enabledsensors only, interfacesuponly, non-zero readings only, sensors that have a reading,virsh listwithout--all,systemctl list-units(only the units loaded in memory). Filter on a type or a class, and map the state as a metric. - In a fan-out, a failed request must not drop the entity's row. Join the
executeForEachEntryOfresult back onto the inventory (left table,defaultRightLine); in anawkscript callingexecuteHttpRequest, print the row with empty cells instead of skipping it withnext. - Entities defined by their activity (sessions, connected replicas, running queries) have no inventory: set
removalDelay[3] on the monitor, and prefer gauges torate()/fakeCounter(), whose state restarts each time the instance is recreated.
Anti-Patterns To Avoid
- many scalar queries where one table query would do
- long replacement chains instead of translation tables
- IDs derived from mutable names
- hidden dependency on locale-specific output text
- filtering the rows that create monitors on a state or a value
- an inner join or a fan-out that drops the row of an entity whose statistics are missing
- [1] monitors-and-jobs.html#when-instances-are-removed
- [2] sources/table-join.html
- [3] monitors-and-jobs.html#removaldelay
