# Telemetry Contracts

> Enforce telemetry contract stability (event naming, JSONL envelopes, /api/health + /api/status shape). Use when investigating telemetry drift, adding new telemetry fields, or updating z-server ingestion/UI.

- Skill: `metabench/telemetry-contracts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add metabench/telemetry-contracts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/metabench/telemetry-contracts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: metabench (https://skillmd.com/u/metabench)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/metabench/telemetry-contracts

---


# 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

1. Locate current contract docs + recent telemetry work.
   - Start from the most recent telemetry session docs under `docs/sessions/`.
2. Identify the contract surfaces that must remain stable:
   - telemetry JSONL envelope shape
   - event names + required fields
   - `/api/health` and `/api/status` payload shape
3. Update emitter and consumer in lockstep.
4. Add/adjust the smallest test(s) that enforce the contract.
5. 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/status` endpoint, 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`