Event Ruler matches thousands of events per second against JSON rules

The problem: many rules, one event stream

Event driven systems accumulate two kinds of pressure. The event volume grows, and so does the pile of conditions that decide what happens next. A team ends up with rules spread across lambda functions, configuration files and hand written filter code, which means every new condition needs a code change and a deploy. Event Ruler, called Ruler in the rest of the documentation, addresses that shape of problem directly: a Java library that matches rules to events, where an event is a list of fields given either as name/value pairs or as a JSON object, and a rule associates event field names with lists of possible values. The project description claims matching many thousands of events per second, and the documentation gives the reason to believe that is a design property rather than a benchmark result: the time it takes to match events does not depend on the number of rules. The second stated reason to use it is that customers like the JSON query language for expressing rules, which is the part that actually changes how a team works. A rule author writes a JSON document, and a support engineer can read the same document.

A rule is a field path mapped to a list of acceptable values

The rule format is closer to a filter document than to a program. A simple rule against the sample EC2 instance event in the documentation looks like this.

{
  "detail-type": [ "EC2 Instance State-change Notification" ],
  "resources": [ "arn:aws:ec2:us-east-1:123456789012:instance/i-000000aaaaaa00000" ],
  "detail": {
    "state": [ "initializing", "running" ]
  }
}

Three things about that shape drive everything else. First, values in rules are always provided as arrays, and a match happens when the value in the event is one of the values in the rule array. Second, nested event structure is mirrored by nesting in the rule, so detail.state is addressed by nesting detail then state. Third, fields present in the event but absent from the rule are ignored, so a rule does not need to enumerate the whole event. The resources entry shows the array case: when the event field is itself an array, the rule matches if the intersection between the event array and the rule array is non-empty, so one rule entry covers an event carrying several resources.

String operators and the limits they impose

Beyond plain equality, the rule language offers prefix, suffix, wildcard and case insensitive variants, each expressed as an object rather than a bare string inside the value array. A prefix match on a timestamp field is written like this.

{
  "time": [ { "prefix": "2017-10-02" } ]
}

The case insensitive forms nest one level deeper, putting an equals-ignore-case object inside the prefix or suffix object.

{
  "source": [ { "prefix": { "equals-ignore-case": "EC2" } } ]
}

A wildcard value may contain zero to many wildcard characters, but consecutive wildcards are not allowed, and an asterisk can be escaped with a backslash to match it literally. Two consecutive backslashes represent a single literal backslash, and a backslash escaping anything other than an asterisk or a backslash is not allowed. Those escape rules are strict enough that they are worth reading twice before you build patterns by hand, since a stray backslash is a rejected pattern rather than a literal character. The limitation to keep in mind across this family is that prefix, suffix, wildcard and equals-ignore-case matches only work on string-valued fields.

Anything-but and its type restrictions

Anything-but inverts a condition and is the operator with the most rules attached to it. It works with single string and numeric values, or with lists, and a list has to contain entirely strings or entirely numerics. It can also wrap a prefix, suffix or equals-ignore-case match of a string or a list of strings. A list of forbidden string values looks like this.

{
  "detail": {
    "state": [ { "anything-but": [ "stopped", "overloaded" ] } ]
  }
}

The same operator accepts a wildcard inside it, which is how you exclude a path pattern rather than a literal value.

{
  "detail": {
    "state": [ { "anything-but": { "wildcard": "*/bin/*.jar" } } ]
  }
}

This form is the one to think about carefully when you write rules at scale, because a single anything-but rule silently accepts a wide space of values. Combined with the rule that unused event fields are ignored, an anything-but on a field that may be absent in some event shapes is a rule that behaves differently depending on the producer. If that distinction matters to you, the safer style is an explicit list of accepted values, which fails closed when the field is missing rather than matching.

Where the events come from: raw JSON or a Jackson node

Ruler accepts events in two forms, which matters for how you wire it into a pipeline. Events in JSON form may be provided as a raw JSON string or as a parsed Jackson JsonNode. If your producer already hands you Jackson nodes, there is no serialization step between the event and the matcher, and that is the shape most Java pipelines end up with. The alternative view of an event is a set of name/value pairs, and the documentation presents it as a table with names such as source, detail-type and detail.state rather than as nested JSON, which is the form you would use when the event arrives from a system that flattens its structure. Ruler has APIs for providing events both ways. The important point for evaluation is that the rule format is the same either way, so you can start with raw strings while a producer is being changed, and move to parsed nodes later without rewriting any rules.

Compiling rules before you put them in front of traffic

The documentation has a dedicated section on compiling and checking rules, and the presence of that step is the tell about how this library expects to be used. Rules are treated as something to validate ahead of time rather than something to interpret on every event, which is the mechanism behind the claim that match time does not depend on rule count. A rule that fails to compile is caught before it reaches the hot path, and a rule that compiles is ready to be evaluated against the stream. The library also has a section on how AND and OR relationships among fields work, and a performance section. Two cautions belong here. The visible documentation text stops partway through the operator reference, and the section describing the rule compiler is listed in the table of contents rather than shown in full, so the details of what a compiler rejects and how the boolean relationships are expressed are not all visible from what is published. If your rules use combinations beyond field level matching, expect to read the source in src/ before committing.

Doing it yourself, and when that is the better answer

The honest alternative is not a competing library, it is writing the filter yourself. A hand built matcher for a handful of fields is a few dozen lines of code over a Map, and it gives you exactly the semantics you want, including conditions beyond the documented operator set. That approach wins when the rule set is small and stable, when you need conditions the operator list does not cover, and when you want to avoid adding a dependency to a service that currently has none. Ruler earns its place in the opposite situation: when rules are numerous, when rule authors are not all Java programmers, when the rules change often enough that a code change per condition is the bottleneck, and when matching throughput matters enough that you do not want your own filter to become the slowest thing in the pipeline. The trade is that you accept a fixed operator vocabulary and JSON as the authoring format, both of which are hard to extend later.

Licence, release cadence and the shape of the repository

Event Ruler is published under the Apache-2.0 licence, which is the permissive choice and carries the usual attribution conditions without the copyleft reach of GPL style licences. The library is published to Maven Central under the coordinates software.amazon.event.ruler and the artifact name event-ruler, with a CI workflow badge and a separate maintainers and governance file in the repository. Releases in the recent history include v2.0.2 on 2026-08-28, v2.1.0 on 2026-09-03 and v2.2.0 on 2026-09-10, and the last push to the repository was on 2026-10-19. The repository carries a pom.xml, a config directory, a scripts directory and src, which is the conventional Maven layout. One gap worth flagging for a team planning a long term dependency: the published README does not give an explicit installation snippet, a Java version requirement or a dependency declaration block, so the version floor you end up on has to be confirmed against the pom.xml in the repository or the artifact page on Maven Central rather than assumed.

Editorial conclusion

Event Ruler suits Java teams that already produce structured events, need rule authoring that non-programmers can read, and want matching cost that does not grow with the rule count. It is the wrong choice for free text search, for numeric range conditions, and for teams that need a query language with explicit boolean grouping, since the documentation covers AND and OR relationships among fields but the published README stops short of showing the whole rule compiler. Before adopting it, check the operator set against your real event shapes: prefix, suffix, wildcard and equals-ignore-case all work on string-valued fields only, and anything-but lists must contain entirely strings or entirely numerics. Pull software.amazon.event.ruler:event-ruler from Maven Central, feed it one JSON event with a Jackson JsonNode or a raw string, and confirm the operator you rely on behaves the way the README describes before wiring it into a production path.

Frequently asked questions

Official sources

1. aws/event-ruler on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases