metabench Telemetry Contracts
Triggers
- "telemetry", "drift", "status/health endpoints", "event naming"
Scope
This Skill helps keep telemetry reliable over time by:
- identifying the contract surfaces (events + endpoints)
- updating code + tests together
- validating that drift risks are addressed
Out of scope:
- designing brand-new telemetry systems (that’s a separate design task)
Inputs
- Which server/module emits telemetry (file path(s) if known)
- What changed (new fields, renamed events, endpoint shape change)
- Which consumer(s) are impacted (e.g. z-server, UI dashboards, tests)
Procedure
- Locate current contract docs + recent telemetry work.
- Start from the most recent telemetry session docs under
docs/sessions/.
- Start from the most recent telemetry session docs under
- Identify the contract surfaces that must remain stable:
- telemetry JSONL envelope shape
- event names + required fields
/api/healthand/api/statuspayload shape
- Update emitter and consumer in lockstep.
- Add/adjust the smallest test(s) that enforce the contract.
- Record the rationale (why the shape changed, migration plan if needed).
Validation
- Run the most targeted test suite(s) that cover telemetry shape.
- If the change affects diagrams/docs, update the relevant session diagrams.
Anti-Patterns to Avoid
- Blindly Renaming Events: Changing core event names without verifying downstream consumers (z-server, UI dashboards).
- Bloated Payloads: Adding massive, deeply nested objects to the
/api/statusendpoint, violating compact telemetry contracts.
Escalation / Research request
Ask for dedicated research if:
- a contract change affects multiple servers and you need a migration strategy
- you need a formal schema/versioning plan
References
- Telemetry explainer session:
docs/sessions/2025-12-13-telemetry-setup-explainer/ - AGI workflows:
docs/agi/WORKFLOWS.md