<!-- review: finished -->

<a id="custom-metrics-config"></a>

# Custom Metrics Configuration

Angie can collect custom numeric metrics in shared memory and expose them via
the real-time [statistics API](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) at
`/status/http/metric_zones/`. This is provided by the
[Metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) module.

<a id="configuration-steps-1"></a>

## Configuration Steps

1. Define a metric zone in the `http` block:
   - [metric_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) creates a zone with a single metric mode.
   - [metric_complex_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) creates a zone with multiple named metrics.
2. Update metrics in request processing with the [metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#id3) directive.
   Use a `key=value` pair (both are [complex values](https://en.angie.software//angie/docs/configuration/configfile.md#syntax)), and
   choose the update stage with `on=` (`request`, `response`,
   or `end`).
3. Expose the API with a `location`:
   ```nginx
   location /status/ {
       api /status/http/metric_zones/;
   }
   ```

<a id="example"></a>

## Example

Count requests per host and expose the metrics in the API:

```nginx
http {
    metric_zone requests:128k count;

    server {
        listen 80;

        location / {
            metric requests $host=1;
        }

        location /status/ {
            api /status/http/metric_zones/;
        }
    }
}
```

<a id="notes"></a>

## Notes

- If `expire=on` is set on the zone and the shared memory is full, the
  least recently used entries are expired. If `expire=off`, new updates
  are discarded and the `discarded` counter grows.
- If `discard_key` is set, metrics from expired entries are aggregated
  under that key in the API output.
- Keys and values are limited to 255 bytes; longer keys are truncated in the API.
- An empty value is treated as `0`, and a non-empty value without a
  leading number is treated as `1`.