Skip to content

Metric Definition

Purpose

Metric Definition is the single-measurement contract. Its unique job is to define exactly what is measured, how to collect it, what unit it uses, whether higher or lower is better, what tolerance applies, and how dashboards, ratchets, experiments, or monitoring should interpret it.

It is not a dashboard, alert policy, or improvement backlog item. Those artifacts consume metric definitions.

Example

Show a worked example of this artifact
---
ddx:
  id: example.metric-definition.depositmatch.csv-import-validation-seconds
  depends_on:
    - example.test-plan.depositmatch
    - example.deployment-checklist.depositmatch.csv-import
---

# Metric Definition: csv-import-validation-seconds

> Store at `docs/helix/06-iterate/metrics/csv-import-validation-seconds.yaml`

```yaml
name: csv-import-validation-seconds
description: Time required to validate and summarize a representative DepositMatch CSV import fixture totaling 10,000 rows.
unit: seconds
direction: lower
command: pnpm metric:csv-import-validation -- --fixture fixtures/import/acme-10000-rows
output_pattern: "METRIC csv-import-validation-seconds=([0-9]+\\.?[0-9]*)"
tolerance: "5%"
interpretation: A value above 5 seconds violates the FEAT-001 performance target and should create an improvement backlog item unless the fixture changed.
labels:
  product: depositmatch
  feature: FEAT-001
  area: import
  signal: latency
```

Reference

ActivityIterate — Measure, align, and improve. Close the feedback loop back into the planning strand.
Default locationdocs/helix/06-iterate/metrics/[name].yaml
RequiresNone
EnablesNone
InformsMetrics Dashboard
Monitoring Setup
Generation prompt
Show the full generation prompt
# Metric Definition Prompt

Create one reusable metric definition.


Purpose
    
Metric Definition is the single-measurement contract. Its unique job is to
define exactly what is measured, how to collect it, what unit it uses, whether
higher or lower is better, what tolerance applies, and how dashboards,
ratchets, experiments, or monitoring should interpret it.


It is not a dashboard, alert policy, or improvement backlog item. Those artifacts
consume metric definitions.


Reference Anchors
    
Use this local resource summary as grounding:


    

  • docs/resources/google-sre-monitoring-distributed-systems.md grounds metric
definitions as precise quantitative signals with clear interpretation.
    • 



Focus
    
Define the metric as the authoritative source for ratchets, dashboards, experiments, and monitoring.


Keep the definition minimal: required fields are name, description, unit, direction, and command. Add output_pattern, tolerance, and labels only when needed.


The command must be deterministic, repeatable, and free of side effects or external service dependencies. Prefer METRIC <name>=<value> output unless an output_pattern is required.


Boundary Test
    

  
      

          If you are writing…
          Put it in…
      

  
  
      

          One metric's unit, command, direction, tolerance, and labels
          Metric Definition
      

      

          A view comparing multiple metrics over time
          Metrics Dashboard
      

      

          A decision about what to improve next
          Improvement Backlog
      

      

          Production alerting or runbook behavior
          Monitoring Setup / Runbook
      

  



Completion Criteria
    
    

  • All required fields are populated.
    • 

  • The command is deterministic and repeatable.
    • 

  • The filename matches the name field.
Template
Show the template structure
---
ddx:
  id: METRIC-name
---

Metric Definition: [NAME]
> Store at docs/helix/06-iterate/metrics/[NAME].yaml





name: [kebab-case-identifier]
description: [What this metric measures]
unit: [seconds|bytes|percent|count|...]
direction: [lower|higher]
command: [repeatable shell command]
output_pattern: "[regex with capture group]"
tolerance: [noise band, e.g. "5%" or "100ms"]
interpretation: [How to read meaningful changes]
labels:
  [key]: [value]
```</code></pre></details></td></tr>
</tbody>
</table>
© 2025 Hextra Project.