Metrics

Measurements record observed values; counters record change over time.

Measurements and counters

Metrics are numeric data points, distinct from events. There are two kinds, and the kind is fixed per metric name within a project:

• Measurement: an observed value at a point in time, such as a request taking 84 milliseconds or the number of bytes of memory in use. Think of it as a gauge-like snapshot.
• Counter: a quantity that changes over time through increments and decrements, such as the number of jobs processed. Think of it as a tally that moves.

The mental model side by side: a measurement answers “what is the value right now or on average,” while a counter answers “how much did this change.”

Recording measurements

Record a measurement with vanta.measure(), which emits an $measure internal event:

import { Vanta } from '@vanta-dev/node'

const vanta = new Vanta({
  apiKey: process.env.VANTA_API_KEY,
})

await vanta.measure({
  name: 'api.latency',
  value: 84,
  unit: 'ms',
})

await vanta.measure({
  name: 'memory.heap',
  value: 512000000,
  unit: 'bytes',
})

When querying a measurement, the default aggregation is avg. Supported aggregations are avg, min, max, sum, count, p50, p90, p95, and p99.

Recording counters

Increment and decrement a counter with vanta.increment() and vanta.decrement(), which emit $increment and $decrement events. The value defaults to 1 and must be a non-negative finite number:

await vanta.increment('jobs.processed')
await vanta.increment('items.enqueued', 25)
await vanta.decrement('queue.depth')
await vanta.decrement('active.connections', 3)

Over any time range, a counter's sum is the net change: all increments minus all decrements. It is not a running total from zero.

Units and tags

Metrics can carry an optional unit, such as ms, bytes, count, or seconds. Units help with display and interpretation.

Metrics can also carry tags, key/value pairs that add dimensions for filtering and breaking down results:

await vanta.measure({
  name: 'api.latency',
  value: 91,
  unit: 'ms',
  tags: {
    route: '/v1/users',
    method: 'GET',
  },
})

Querying metrics

The vanta.metrics helpers cover submitting, querying, and listing metrics:

• submit - submit one or more metric changes in a batch
• query - run an aggregated query over a time range
• timeseries - get values bucketed over time
• current - get the latest state of a metric
• list - list all metrics recorded for the project

Query an aggregated value with query(). The metric name is required; the aggregation defaults to avg for measurements:

const latency = await vanta.metrics.query({
  name: 'api.latency',
  time: { start: '2026-08-20T00:00:00Z', end: '2026-08-21T00:00:00Z' },
  aggregation: 'avg',
})

const processed = await vanta.metrics.query({
  name: 'jobs.processed',
  time: { start: '2026-08-20T00:00:00Z', end: '2026-08-21T00:00:00Z' },
})

For counters, the query result reflects the net change over the range, computed as increments minus decrements.

Current values

Use current() to get the latest state of a metric without a time range:

const total = await vanta.metrics.current({ name: 'jobs.processed' })

const latest = await vanta.metrics.current({ name: 'api.latency' })

For a counter, current() returns the all-time cumulative value. For a measurement it returns the most recent observation along with its timestamp.

Time series

Get values bucketed over time with timeseries(). For a counter, each bucket contains the net change during that bucket:

const series = await vanta.metrics.timeseries({
  name: 'api.latency',
  interval: '1h',
  time: { start: '2026-08-20T00:00:00Z', end: '2026-08-21T00:00:00Z' },
  aggregation: 'avg',
})