> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grafana/k6/llms.txt
> Use this file to discover all available pages before exploring further.

# k6/metrics

> Create and use custom metrics in your k6 tests.

The `k6/metrics` module provides classes for creating custom metrics.

## Metric Types

### Counter

A metric that cumulatively sums added values.

```javascript theme={null}
import { Counter } from 'k6/metrics';

const myCounter = new Counter('my_counter');

export default function () {
  myCounter.add(1);
}
```

<ParamField path="name" type="string">
  Metric name (must be unique)
</ParamField>

<ParamField path="isTime" type="boolean" optional>
  Whether the metric represents time values
</ParamField>

#### add(value, \[tags])

Adds a value to the counter.

<ParamField path="value" type="number">
  Value to add
</ParamField>

<ParamField path="tags" type="object" optional>
  Custom tags for this data point
</ParamField>

### Gauge

A metric that stores the latest value added to it.

```javascript theme={null}
import { Gauge } from 'k6/metrics';

const myGauge = new Gauge('my_gauge');

export default function () {
  myGauge.add(42);
}
```

<ParamField path="name" type="string">
  Metric name (must be unique)
</ParamField>

<ParamField path="isTime" type="boolean" optional>
  Whether the metric represents time values
</ParamField>

#### add(value, \[tags])

Sets the gauge to the specified value.

### Rate

A metric that tracks the percentage of added values that are non-zero.

```javascript theme={null}
import { Rate } from 'k6/metrics';

const myRate = new Rate('my_rate');

export default function () {
  myRate.add(true);  // or 1
  myRate.add(false); // or 0
}
```

<ParamField path="name" type="string">
  Metric name (must be unique)
</ParamField>

<ParamField path="isTime" type="boolean" optional>
  Whether the metric represents time values
</ParamField>

#### add(value, \[tags])

Adds a boolean or numeric value to the rate.

### Trend

A metric that calculates statistics (min, max, avg, percentiles) on added values.

```javascript theme={null}
import { Trend } from 'k6/metrics';

const myTrend = new Trend('my_trend');

export default function () {
  myTrend.add(100);
  myTrend.add(200);
}
```

<ParamField path="name" type="string">
  Metric name (must be unique)
</ParamField>

<ParamField path="isTime" type="boolean" optional>
  Whether the metric represents time values (enables time-based formatting)
</ParamField>

#### add(value, \[tags])

Adds a value to the trend.

## Complete Example

```javascript theme={null}
import http from 'k6/http';
import { Counter, Gauge, Rate, Trend } from 'k6/metrics';
import { check } from 'k6';

let myCounter = new Counter('my_counter');
let myGauge = new Gauge('my_gauge');
let myRate = new Rate('my_rate');
let myTrend = new Trend('my_trend');

let maxResponseTime = 0.0;

export default function () {
  let res = http.get('http://httpbin.org/');
  let passed = check(res, { 'status is 200': (r) => r.status === 200 });

  // Add one for number of requests
  myCounter.add(1);

  // Set max response time seen
  maxResponseTime = Math.max(maxResponseTime, res.timings.duration);
  myGauge.add(maxResponseTime);

  // Add check success or failure
  myRate.add(passed);

  // Track response time
  myTrend.add(res.timings.duration);
}
```

## Usage Notes

<Warning>
  Custom metrics must be declared in the init context (outside the default function). Adding values to metrics can only be done in the VU context.
</Warning>

```javascript theme={null}
// ✅ Correct - declare in init context
import { Counter } from 'k6/metrics';
const myCounter = new Counter('my_counter');

export default function () {
  // ✅ Correct - add values in VU context
  myCounter.add(1);
}
```

## Metric Tags

You can attach custom tags to individual metric data points:

```javascript theme={null}
import { Counter } from 'k6/metrics';

const myCounter = new Counter('api_requests');

export default function () {
  myCounter.add(1, { endpoint: '/users', method: 'GET' });
  myCounter.add(1, { endpoint: '/posts', method: 'POST' });
}
```