Elasticsearch IP Range Aggregation - Syntax, Example, and Tips

What it does

The IP Range Aggregation allows you to define ranges of IP addresses and count the number of documents that fall within each range. It supports both IPv4 and IPv6 addresses and can work with CIDR notation or specific IP ranges.

Syntax and Documentation

The basic syntax for an IP Range Aggregation is:

{
  "aggs": {
    "ip_ranges": {
      "ip_range": {
        "field": "ip_address",
        "ranges": [
          { "to": "10.0.0.5" },
          { "from": "10.0.0.5", "to": "10.0.0.10" },
          { "from": "10.0.0.10" }
        ]
      }
    }
  }
}

For more detailed information, refer to the official Elasticsearch documentation on IP Range Aggregation.

Example Usage

Here's an example of how you might use IP Range Aggregation to analyze web server logs:

GET /web_logs/_search
{
  "size": 0,
  "aggs": {
    "ip_ranges": {
      "ip_range": {
        "field": "client_ip",
        "ranges": [
          { "to": "10.0.0.0" },
          { "from": "10.0.0.0", "to": "10.0.255.255" },
          { "from": "10.1.0.0", "to": "10.1.255.255" },
          { "from": "10.2.0.0" }
        ]
      }
    }
  }
}

This query would group the logs into four buckets: IPs below 10.0.0.0, IPs in the 10.0.x.x range, IPs in the 10.1.x.x range, and IPs above 10.2.0.0.

Common Issues

1. Field Mapping: Ensure that the field you're aggregating on is properly mapped as an "ip" field type in your index mapping.
2. CIDR Notation: When using CIDR notation, make sure it's correctly formatted to avoid errors.
3. Range Overlaps: Be careful not to create overlapping ranges, as this can lead to unexpected results.

Best Practices

1. Use CIDR notation for more concise and readable range definitions when possible.
2. Consider using the keyed parameter to assign names to your ranges for easier interpretation of results.
3. Combine with other aggregations (like date histogram) for more complex analysis of network data over time.

Frequently Asked Questions

Q: Can IP Range Aggregation handle both IPv4 and IPv6 addresses?
A: Yes, IP Range Aggregation in Elasticsearch supports both IPv4 and IPv6 addresses.

Q: How can I use CIDR notation in IP Range Aggregation?
A: You can use CIDR notation in the "ranges" array like this: { "mask": "10.0.0.0/24" }.

Q: Is it possible to name the ranges in the aggregation results?
A: Yes, you can use the keyed parameter and provide keys for each range to name them in the results.

Q: Can IP Range Aggregation be used with other types of aggregations?
A: Absolutely. IP Range Aggregation can be combined with other aggregations for more complex analysis.

Q: What happens if an IP address falls outside all defined ranges?
A: IP addresses that don't fall within any defined range will not be included in the aggregation results.