Logstash range Filter Plugin

The Logstash range filter plugin is used to check if a specified field's value falls within a defined numeric range. This plugin is particularly useful for categorizing numeric data, setting flags based on thresholds, or filtering events based on numeric criteria.

Syntax

The basic syntax for the range filter plugin is as follows:

filter {
  range {
    field => number
    ranges => [ "range1", "range2", ... ]
  }
}

For detailed information, refer to the official Logstash range filter plugin documentation.

Example Use Case and Usage

A common use case for the range filter is categorizing response times in web server logs. Here's an example:

filter {
  range {
    field => "response_time"
    ranges => [
      "0-300",
      "301-600",
      "601-1000",
      "1001-"
    ]
    add_field => { "response_category" => "%{[@metadata][range]}" }
  }
}

In this example, the plugin categorizes the "response_time" field into different ranges and adds a new field "response_category" with the corresponding range value.

Common Issues and Best Practices

1. Ensure that the field you're applying the range filter to contains numeric values.
2. Be careful with overlapping ranges, as an event may match multiple ranges.
3. Consider using the tag or add_field options to mark or categorize events based on their range.
4. Remember that the range filter only works with numeric fields. For date ranges, use the date filter instead.

Frequently Asked Questions

Q: Can I use the range filter with non-numeric fields?
A: No, the range filter is designed to work only with numeric fields. For date ranges, use the date filter, and for string comparisons, consider using the ruby or grok filter.

Q: What happens if a value doesn't fall into any of the specified ranges?
A: If a value doesn't match any of the specified ranges, no action is taken on that event for this filter.

Q: Can I use variables or dynamic values in the range definitions?
A: Yes, you can use Logstash's variable substitution to define ranges dynamically. For example: ranges => [ "%{min_value}-%{max_value}" ]

Q: Is it possible to apply multiple range filters to the same field?
A: While it's possible to apply multiple range filters, it's generally more efficient to define all your ranges within a single range filter instance.

Q: How does the range filter handle decimal values?
A: The range filter can handle both integer and floating-point numbers. Make sure your ranges are defined appropriately for the precision of your data.