Custom Metrics Configuration

Angie can collect custom numeric metrics in shared memory and expose them via the real-time statistics API at /status/http/metric_zones/. This is provided by the HTTP Metric module.

Note

This guide covers metrics for HTTP traffic. For TCP and UDP traffic, see the Stream Metric module, which exposes its zones at /status/stream/metric_zones/.

Related modules

• HTTP Metric module: creates the zones and updates them.

• API module: serves the zones in the metric_zones branch.

Configuration Steps

1. Define a metric zone in the http block:

   • metric_zone creates a zone with a single metric mode.

   • metric_complex_zone creates a zone with multiple named metrics.

2. Update metrics in request processing with the metric directive. Use a key=value pair (both are complex values), and choose the update stage with on= (request, response, or end).

3. Expose the API with a location:

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

Example

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

http {
    metric_zone requests:128k count;

    server {
        listen 80;

        location / {
            metric requests $host=1;
        }

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

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.