Skip to main content
Metrics allow you to collect and aggregate data while running codemods. This is useful for:
  • Codebase analysis: Count occurrences of patterns, prop usages, component instances
  • Migration tracking: Track what was rewritten (and in which shapes) while applying transforms
  • Read-only codemods: Gather insights without modifying code

When to emit metrics

Prefer one metric name per js-ast-grep step, with cardinality dimensions for the variants you care about—not a separate metric for every edge case. Keep the metric count small. Encode differences as cardinality keys/values on the same atom. Snapshot metrics.json next to fixtures that produce counts (jssg test -u).

Basic Usage

Import useMetricAtom from codemod:metrics to create a metric tracker:

Cardinality

Cardinality dimensions are key-value pairs that let you group and filter metrics. When you call increment(), you pass an object with string keys and values:
This creates a unique metric entry for each combination of cardinality values. You can later group by any dimension (e.g., all entries where component=Button).
Use cardinality to capture context about what you’re counting. For example, when counting prop usages, include both the prop name and the component it belongs to.

Example: Counting Prop Usage

This read-only codemod counts how many times each prop is used on Button components:
Running this codemod produces output like:

Insights

Insights binds each dashboard query to one workflow step and loads that step’s js-ast-grep script from the published package. Metric names must be statically visible in that script (useMetricAtom + increment)—not only in a different package file or helper import. This is the selected step’s script, not necessarily the package entry (for example scripts/codemod.ts). For scale (transforms or mining), see Performant codemods. Insights runs the selected step on its own, so that step must compute its metric from the repository directly. Don’t rely on files written by an earlier step (for example, a collect step that writes JSON shards for an analyze step); the widget will return no results.