{"id":13521966,"url":"https://github.com/aws/event-ruler","last_synced_at":"2025-05-15T10:02:34.120Z","repository":{"id":58795844,"uuid":"504597635","full_name":"aws/event-ruler","owner":"aws","description":"Event Ruler is a Java library that allows matching many thousands of Events per second to any number of expressive and sophisticated rules.","archived":false,"fork":false,"pushed_at":"2025-05-14T23:13:36.000Z","size":64997,"stargazers_count":598,"open_issues_count":24,"forks_count":69,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-05-15T00:26:51.410Z","etag":null,"topics":["event-driven","events","filtering","java","json","matching","rule","rules"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-17T16:10:12.000Z","updated_at":"2025-05-14T23:13:32.000Z","dependencies_parsed_at":"2023-02-18T19:15:26.307Z","dependency_job_id":"7c6d4f3e-028e-4e7e-b353-03a15efd7248","html_url":"https://github.com/aws/event-ruler","commit_stats":{"total_commits":160,"total_committers":17,"mean_commits":9.411764705882353,"dds":"0.48124999999999996","last_synced_commit":"dc9ef885638e519a25ab51f0fec001cb06761a21"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fevent-ruler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fevent-ruler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fevent-ruler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fevent-ruler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/event-ruler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319716,"owners_count":22051072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["event-driven","events","filtering","java","json","matching","rule","rules"],"created_at":"2024-08-01T06:00:40.384Z","updated_at":"2025-05-15T10:02:26.858Z","avatar_url":"https://github.com/aws.png","language":"Java","readme":"# Event Ruler\n\n[![License](https://img.shields.io/github/license/aws/event-ruler.svg?color=blue\u0026logo=apache)]([https://www.apache.org/licenses/LICENSE-2.0.html](https://github.com/aws/event-ruler/blob/main/LICENSE))\n[![Build](https://github.com/aws/event-ruler/actions/workflows/CI.yml/badge.svg)](https://github.com/aws/event-ruler/actions/workflows/CI.yml)\n[![Latest Release](https://img.shields.io/github/release/aws/event-ruler.svg?logo=github\u0026style=flat-square)](https://github.com/aws/event-ruler/releases/latest)\n![Maven Central](https://img.shields.io/maven-central/v/software.amazon.event.ruler/event-ruler?logo=apachemaven)\n\n\nEvent Ruler (called Ruler in rest of the doc for brevity) is a Java library \nthat allows matching **Rules** to **Events**. An event is a list of fields, which \nmay be given as name/value pairs or as a JSON object.  A rule associates event \nfield names with lists of possible values.  There are two reasons to use Ruler:\n\n1. It's fast; the time it takes to match Events doesn't depend on the number of Rules.\n2. Customers like the JSON \"query language\" for expressing rules.\n\nContents:\n\n1. [Ruler by Example](#ruler-by-example)\n2. [And and Or With Ruler](#and-and-or-relationship-among-fields-with-ruler)\n3. [How to Use Ruler](#how-to-use-ruler)\n4. [JSON Text Matching](#json-text-matching)\n5. [JSON Array Matching](#json-array-matching)\n6. [Compiling and Checking Rules](#compiling-and-checking-rules)\n7. [Performance](#performance)\n\nIt's easiest to explain by example.\n\n##  Ruler by Example\n\nAn Event is a JSON object.  Here's an example:\n\n```javascript\n{\n  \"version\": \"0\",\n  \"id\": \"ddddd4-aaaa-7777-4444-345dd43cc333\",\n  \"detail-type\": \"EC2 Instance State-change Notification\",\n  \"source\": \"aws.ec2\",\n  \"account\": \"012345679012\",\n  \"time\": \"2017-10-02T16:24:49Z\",\n  \"region\": \"us-east-1\",\n  \"resources\": [\n    \"arn:aws:ec2:us-east-1:123456789012:instance/i-000000aaaaaa00000\"\n  ],\n  \"detail\": {\n    \"c-count\": 5,\n    \"d-count\": 3,\n    \"x-limit\": 301.8,\n    \"source-ip\": \"10.0.0.33\",\n    \"instance-id\": \"i-000000aaaaaa00000\",\n    \"state\": \"running\"\n  }\n}\n```\n\nYou can also see this as a set of name/value pairs. For brevity, we present\nonly a sampling.  Ruler has APIs for providing events both in JSON form and\nas name/value pairs:\n\n```\n    +--------------+------------------------------------------+\n    | name         | value                                    |\n    |--------------|------------------------------------------|\n    | source       | \"aws.ec2\"                                |\n    | detail-type  | \"EC2 Instance State-change Notification\" |\n    | detail.state | \"running\"                                |\n    +--------------+------------------------------------------+\n```\n\nEvents in the JSON form may be provided in the form of a raw JSON String,\nor a parsed [Jackson JsonNode](https://fasterxml.github.io/jackson-databind/javadoc/2.12/com/fasterxml/jackson/databind/JsonNode.html).\n\n### Simple matching\n\nThe rules in this section all match the sample event above:\n\n```javascript\n{\n  \"detail-type\": [ \"EC2 Instance State-change Notification\" ],\n  \"resources\": [ \"arn:aws:ec2:us-east-1:123456789012:instance/i-000000aaaaaa00000\" ],\n  \"detail\": {\n    \"state\": [ \"initializing\", \"running\" ]\n  }\n}\n```\nThis will match any event with the provided values for the `resource`,\n`detail-type`, and `detail.state` values, ignoring any other fields in the\nevent. It would also match if the value of `detail.state` had been\n`\"initializing\"`.\n\nValues in rules are always provided as arrays, and match if the value in the\nevent is one of the values provided in the array.  The reference to `resources`\nshows that if the value in the event is also an array, the rule matches if the\nintersection between the event array and rule-array is non-empty.\n\n### Prefix matching\n\n```javascript\n{\n  \"time\": [ { \"prefix\": \"2017-10-02\" } ]\n}\n```\nPrefix matches only work on string-valued fields.\n\n### Prefix equals-ignore-case matching\n\n```javascript\n{\n  \"source\": [ { \"prefix\": { \"equals-ignore-case\": \"EC2\" } } ]\n}\n```\nPrefix equals-ignore-case matches only work on string-valued fields.\n\n### Suffix matching\n\n```javascript\n{\n  \"source\": [ { \"suffix\": \"ec2\" } ]\n}\n```\nSuffix matches only work on string-valued fields.\n\n### Suffix equals-ignore-case matching\n\n ```javascript\n {\n   \"source\": [ { \"suffix\": { \"equals-ignore-case\": \"EC2\" } } ]\n }\n ```\nSuffix equals-ignore-case matches only work on string-valued fields.\n\n### Equals-ignore-case matching\n\n```javascript\n{\n  \"source\": [ { \"equals-ignore-case\": \"EC2\" } ]\n}\n```\nEquals-ignore-case matches only work on string-valued fields.\n\n### Wildcard matching\n\n```javascript\n{\n  \"source\": [ { \"wildcard\": \"Simple*Service\" } ]\n}\n```\nWildcard matches only work on string-valued fields. A single value can contain zero to many wildcard characters, but\nconsecutive wildcard characters are not allowed. To match the asterisk character specifically, a wildcard character can\nbe escaped with a backslash. Two consecutive backslashes (i.e. a backslash escaped with a backslash) represents the\nactual backslash character. A backslash escaping any character other than asterisk or backslash is not allowed.\n\n### Anything-but matching\n\nAnything-but matching does what the name says: matches anything *except* what's provided in the rule.\n\nAnything-but works with single string and numeric values or lists, which have to contain entirely strings or entirely\nnumerics. It also may be applied to a prefix, suffix, or equals-ignore-case match of a string or a list of strings.\n\nSingle anything-but (string, then numeric):\n```javascript\n{\n  \"detail\": {\n    \"state\": [ { \"anything-but\": \"initializing\" } ]\n  }\n}\n\n{\n  \"detail\": {\n    \"x-limit\": [ { \"anything-but\": 123 } ]\n  }\n}\n```\nAnything-but list (strings):\n```javascript\n{\n  \"detail\": {\n    \"state\": [ { \"anything-but\": [ \"stopped\", \"overloaded\" ] } ]\n  }\n}\n```\n\nAnything-but list (numbers):\n```javascript\n{\n  \"detail\": {\n    \"x-limit\": [ { \"anything-but\": [ 100, 200, 300 ] } ]\n  }\n}\n```\n\nAnything-but prefix:\n```javascript\n{\n  \"detail\": {\n    \"state\": [ { \"anything-but\": { \"prefix\": \"init\" } } ]\n  }\n}\n```\n\nAnything-but prefix list (strings):\n```javascript\n{\n  \"detail\": {\n    \"state\": [ { \"anything-but\": { \"prefix\": [ \"init\", \"error\" ] } } ]\n  }\n}\n```\n\nAnything-but suffix:\n```javascript\n{\n  \"detail\": {\n    \"instance-id\": [ { \"anything-but\": { \"suffix\": \"1234\" } } ]\n  }\n}\n```\n\nAnything-but suffix list (strings):\n```javascript\n{\n  \"detail\": {\n    \"instance-id\": [ { \"anything-but\": { \"suffix\": [ \"1234\", \"6789\" ] } } ]\n  }\n}\n```\n\nAnything-but-ignore-case:\n```javascript\n{\n  \"detail\": {\n    \"state\": [ { \"anything-but\": {\"equals-ignore-case\": \"Stopped\" } } ]\n  }\n}\n```\n\nAnything-but-ignore-case list (strings):\n```javascript\n{\n  \"detail\": {\n    \"state\": [ { \"anything-but\": {\"equals-ignore-case\": [ \"Stopped\", \"OverLoaded\" ] } } ]\n  }\n}\n```\n\nAnything-but wildcard:\n```javascript\n{\n  \"detail\": {\n    \"state\": [ { \"anything-but\": { \"wildcard\": \"*/bin/*.jar\" } } ]\n  }\n}\n```\n\nAnything-but wildcard list (strings):\n```javascript\n{\n  \"detail\": {\n    \"state\": [ { \"anything-but\": { \"wildcard\": [ \"*/bin/*.jar\", \"*/bin/*.class\" ] } } ]\n  }\n}\n```\n\n### Numeric matching\n```javascript\n{\n  \"detail\": {\n    \"c-count\": [ { \"numeric\": [ \"\u003e\", 0, \"\u003c=\", 5 ] } ],\n    \"d-count\": [ { \"numeric\": [ \"\u003c\", 10 ] } ],\n    \"x-limit\": [ { \"numeric\": [ \"=\", 3.018e2 ] } ]\n  }\n}  \n```\n\nAbove, the references to `c-count`, `d-count`, and `x-limit` illustrate numeric matching,\nand only work with values that are JSON numbers.  Numeric matching supports the same \nprecision and range as Java's `double` primitive which implements IEEE 754 `binary64` standard. \n\n### IP Address Matching\n```javascript\n{\n  \"detail\": {\n    \"source-ip\": [ { \"cidr\": \"10.0.0.0/24\" } ]\n  }\n}\n```\n\nThis also works with IPv6 addresses.\n\n### Exists matching\n\nExists matching works on the presence or absence of a field in the JSON event.\n\nThe rule below will match any event which has a detail.c-count field present.\n\n```javascript\n{\n  \"detail\": {\n    \"c-count\": [ { \"exists\": true  } ]\n  }\n}  \n```\n\nThe rule below will match any event which has no detail.c-count field.\n\n```javascript\n{\n  \"detail\": {\n    \"c-count\": [ { \"exists\": false  } ]\n  }\n}  \n```\n\n**Note** ```Exists``` match **only works on the leaf nodes.** It does not work on intermediate nodes.\n\nAs an example, the above example for ```exists : false ``` would match the event below:\n\n```javascript\n{\n  \"detail-type\": [ \"EC2 Instance State-change Notification\" ],\n  \"resources\": [ \"arn:aws:ec2:us-east-1:123456789012:instance/i-000000aaaaaa00000\" ],\n  \"detail\": {\n    \"state\": [ \"initializing\", \"running\" ]\n  }\n}\n```\n\nbut would also match the event below because ```c-count``` is not a leaf node:\n\n```javascript\n{\n  \"detail-type\": [ \"EC2 Instance State-change Notification\" ],\n  \"resources\": [ \"arn:aws:ec2:us-east-1:123456789012:instance/i-000000aaaaaa00000\" ],\n  \"detail\": {\n    \"state\": [ \"initializing\", \"running\" ]\n    \"c-count\" : {\n       \"c1\" : 100\n    }\n  }\n}\n```\n\n\n### Complex example\n\n```javascript\n{\n  \"time\": [ { \"prefix\": \"2017-10-02\" } ],\n  \"detail\": {\n    \"state\": [ { \"anything-but\": \"initializing\" } ],\n    \"c-count\": [ { \"numeric\": [ \"\u003e\", 0, \"\u003c=\", 5 ] } ],\n    \"d-count\": [ { \"numeric\": [ \"\u003c\", 10 ] } ],\n    \"x-limit\": [ { \"anything-but\": [ 100, 200, 300 ] } ],\n    \"source-ip\": [ { \"cidr\": \"10.0.0.0/8\" } ]\n  }\n}\n```\n\nAnd and Or Relationship among fields with Ruler\n=====================\n### Default \"And\" relationship\nAs the examples above show, Ruler considers a rule to match if **all** of the fields\nnamed in the rule match, and it considers a field to match if **any** of the provided\nfield values match, __that is to say Ruler has applied \"And\" logic to all fields by\ndefault without \"And\" primitive is required__.\n\n### \"Or\" relationship\nThere are two ways to reach the \"Or\" effects:\n* Add multiple rules with the same rule name and each individual rule will be treated as one of \"Or\" condition by Ruler.\n  Refer to below under **addRule()** section on how to achieve an \"Or\" effect in that way.\n* Use the \"$or\" primitive to express the \"Or\" relationship within the rule.\n\n#### The \"$or\" Primitive\nThe \"$or\" primitive to allow the customer directly describe the \"Or\" relationship among fields in the rule.\n\nRuler recognizes \"Or\" relationship **only** when the rule has met **all** below conditions:\n* There is \"$or\" on field attribute in the rule followed with an array – e.g. \"$or\": []\n* There are 2+ objects in the \"$or\" array at least : \"$or\": [{}, {}]\n* There is no filed name using Ruler keywords in Object of \"$or\" array, refer to RESERVED_FIELD_NAMES_IN_OR_RELATIONSHIP in `/src/main/software/amazon/event/ruler/Constants.java#L38`\n  for example, below rule will be not parsed as \"Or\" relationship because \"numeric\" and \"prefix\" are Ruler reserved keywords.\n  ```\n  { \n     \"$or\": [ {\"numeric\" : 123}, {\"prefix\": \"abc\"} ] \n  } \n  ```\nOtherwise, Ruler just treats the \"$or\" as normal filed name the same as other string in the rule.\n\n#### Rule examples with \"$or\" Primitive\nNormal \"Or\":\n```javascript\n// Effect of \"source\" \u0026\u0026 (\"metricName\" || \"namespace\")\n{\n  \"source\": [ \"aws.cloudwatch\" ], \n  \"$or\": [\n    { \"metricName\": [ \"CPUUtilization\", \"ReadLatency\" ] },\n    { \"namespace\": [ \"AWS/EC2\", \"AWS/ES\" ] }\n  ] \n}\n```\nParallel \"Or\":\n```javascript\n// Effect of (\"metricName\" || \"namespace\") \u0026\u0026 (\"detail.source\" || \"detail.detail-type\")\n{\n  \"$or\": [\n    { \"metricName\": [ \"CPUUtilization\", \"ReadLatency\" ] },\n    { \"namespace\": [ \"AWS/EC2\", \"AWS/ES\" ] }\n  ], \n  \"detail\" : {\n    \"$or\": [\n      { \"source\": [ \"aws.cloudwatch\" ] },\n      { \"detail-type\": [ \"CloudWatch Alarm State Change\"] }\n    ]\n  }\n}\n```\n\"Or\" has an \"And\" inside\n```javascript\n// Effect of (\"source\" \u0026\u0026 (\"metricName\" || (\"metricType \u0026\u0026 \"namespace\") || \"scope\"))\n{\n  \"source\": [ \"aws.cloudwatch\" ],\n  \"$or\": [\n    { \"metricName\": [ \"CPUUtilization\", \"ReadLatency\" ] },\n    {\n      \"metricType\": [ \"MetricType\" ] ,\n      \"namespace\": [ \"AWS/EC2\", \"AWS/ES\" ]\n    },\n    { \"scope\": [ \"Service\" ] }\n  ]\n}\n```\nNested \"Or\" and \"And\"\n```javascript\n// Effect of (\"source\" \u0026\u0026 (\"metricName\" || (\"metricType \u0026\u0026 \"namespace\" \u0026\u0026 (\"metricId\" || \"spaceId\")) || \"scope\"))\n{\n  \"source\": [ \"aws.cloudwatch\" ],\n  \"$or\": [\n    { \"metricName\": [ \"CPUUtilization\", \"ReadLatency\" ] },\n    {\n      \"metricType\": [ \"MetricType\" ] ,\n      \"namespace\": [ \"AWS/EC2\", \"AWS/ES\" ],\n      \"$or\" : [\n        { \"metricId\": [ 1234 ] },\n        { \"spaceId\": [ 1000 ] }\n      ]\n    },\n    { \"scope\": [ \"Service\" ] }\n  ]\n}\n```\n\n#### The backward compatibility of using \"$or\" as field name in the rule\n\"$or\" is possibly already used as a normal key in some applications (though its likely rare). For these cases, \nRuler tries its best to maintain the backward compatibility. Only when the 3 conditions mentioned above, will \nruler change behaviour because it assumes your rule really wanted an OR and was mis-configured until today. For example, \nthe rule below will keep working as normal rule with treating \"$or\" as normal field name in the rule and event:\n```javascript\n{\n    \"source\": [ \"aws.cloudwatch\" ],\n    \"$or\": {\n        \"metricType\": [ \"MetricType\" ] , \n        \"namespace\": [ \"AWS/EC2\", \"AWS/ES\" ]\n    }\n}\n```\nRefer to `/src/test/data/normalRulesWithOrWording.json` for more examples that \"$or\" is parsed as normal field name by Ruler.\n\n#### Caveat\nThe keyword \"$or\" as \"Or\" relationship primitive should not be designed as normal field in both Events and Rules.\nRuler supports the legacy rules where \"$or\" is parsed as normal field name to keep backward\ncompatibility and give time for team to migrate their legacy \"$or\" usage away from their events and rules as normal filed name. \nMix usage of \"$or\" as \"Or\" primitive, and \"$or\" as normal field name is not supported\nintentionally by Ruler to avoid the super awkward ambiguities on \"$or\" from occurring.\n\nHow to use Ruler\n================\n\nThere are two ways to use Ruler.  You can compile multiple rules\ninto a \"Machine\", and then use either of its `rulesForEvent()` method\nor `rulesForJSONEvent()` methods to check  which of the rules match any Event.\nThe difference between these two methods is discussed below.  This discussion\nwill use `rulesForEvent()` generically except where the difference matters.\n\nAlternatively, you can use a single static boolean method to determine\nwhether an individual event matches a particular rule.\n\n## Static Rule Matching\n\nThere is a single static boolean method `Ruler.matchesRule(event, rule)` -\nboth arguments are provided as JSON strings. \n\nNOTE: There is another deprecated method called `Ruler.matches(event, rule)`which \nshould not be used as its results are inconsistent with `rulesForJSONEvent()` and \n`rulesForEvent()`. See the documentation on `Ruler.matches(event, rule)` for details.\n\n## Matching with a Machine\n\nThe matching time does not depend on the number of rules.  This is the best choice\nif you have multiple possible rules you want to select from, and especially\nif you have a way to store the compiled Machine.\n\nThe matching time is impacted by the degree of non-determinism caused by wildcard and anything-but-wildcard rules.\nPerformance deteriorates as an increasing number of the wildcard rule prefixes match a theoretical worst-case event. To\navoid this, wildcard rules pertaining to the same event field should avoid common prefixes leading up to their first\nwildcard character. If a common prefix is required, then use the minimum number of wildcard characters and limit\nrepeating character sequences that occur following a wildcard character. MachineComplexityEvaluator can be used to\nevaluate a machine and determine the degree of non-determinism, or \"complexity\" (i.e. how many wildcard rule prefixes\nmatch a theoretical worst-case event). Here are some data points showing a typical decrease in performance for\nincreasing complexity scores.\n\n- Complexity = 1, Events per Second = 140,000\n- Complexity = 17, Events per Second = 12,500\n- Complexity = 34, Events per Second = 3500\n- Complexity = 50, Events per Second = 2500\n- Complexity = 100, Events per Second = 1250\n- Complexity = 275, Events per Second = 100 (extrapolated data point)\n- Complexity = 650, Events per Second = 10 (extrapolated data point)\n\nIt is important to limit machine complexity to protect your application. There are at least two different strategies for\nlimiting machine complexity. Which one makes more sense may depend on your application.\n\n1. Aggregate Complexity. Create a machine using all rules, evaluate the complexity, and reject the rule set (or the\n   current rule being added) if it exceeds the threshold.\n2. Individual Complexity. Create a machine using just an individual rule (not all rules), evaluate the complexity, and\n   reject the rule if it exceeds the threshold. In addition, limit the number of rules that can be created that contain\n   a wildcard pattern.\n\nStrategy #1 is more ideal in that it measures the actual complexity of the machine containing all the rules. When\npossible, this strategy should be used. The downside is, let's say you have a control plane that allows the creation of\none rule at a time, up to a very large number. Then for each of these control plane operations, you must load all the\nexisting rules to perform the validation. This could be very expensive. It is also prone to race conditions.\nStrategy #2 is a compromise. The threshold used by strategy #2 will be lower than strategy #1 since it is a per-rule\nthreshold. Let's say you want a machine's complexity, with all rules added, to be no more than 300. Then with\nstrategy #2, for example, you could limit each single-rule machine to complexity of 10, and allow for 30 rules containing\nwildcard patterns. In an absolute worst case where complexity is perfectly additive (unlikely), this would lead to a\nmachine with complexity of 300. The downside is that it is unlikely that the complexity will be perfectly additive, and\nso the number of wildcard-containing rules will likely be limited unnecessarily.\n\nFor strategy #2, depending on how rules are stored, an additional attribute may need to be added to rules to indicate\nwhich ones are nondeterministic (i.e. contain wildcard patterns) in order to limit the number of wildcard-containing\nrules.\n\nThe following is a code snippet illustrating how to limit complexity for a given pattern, like for strategy #2.\n\n```java\npublic class Validate {\n    private void validate(String pattern, MachineComplexityEvaluator machineComplexityEvaluator) {\n        // If we cannot compile, then return exception.\n        List\u003cMap\u003cString, List\u003cPatterns\u003e\u003e\u003e compilationResult = Lists.newArrayList();\n        try {\n            compilationResult.addAll(JsonRuleCompiler.compile(pattern));\n        } catch (Exception e) {\n            InvalidPatternException internalException =\n                    EXCEPTION_FACTORY.invalidPatternException(e.getLocalizedMessage());\n            throw ExceptionMapper.mapToModeledException(internalException);\n        }\n\n        // Validate wildcard patterns. Look for wildcard patterns out of all patterns that have been used.\n        Machine machine = new Machine();\n        int i = 0;\n        for (Map\u003cString, List\u003cPatterns\u003e\u003e rule : compilationResult) {\n            if (containsWildcard(rule)) {\n                // Add rule to machine for complexity evaluation.\n                machine.addPatternRule(Integer.toString(++i), rule);\n            }\n        }\n\n        // Machine has all rules containing wildcard match types. See if the complexity is under the limit.\n        int complexity = machine.evaluateComplexity(machineComplexityEvaluator);\n        if (complexity \u003e MAX_MACHINE_COMPLEXITY) {\n            InvalidPatternException internalException = EXCEPTION_FACTORY.invalidPatternException(\"Rule is too complex\");\n            throw ExceptionMapper.mapToModeledException(internalException);\n        }\n    }\n    \n    private boolean containsWildcard(Map\u003cString, List\u003cPatterns\u003e\u003e rule) {\n        for (List\u003cPatterns\u003e fieldPatterns : rule.values()) {\n            for (Patterns fieldPattern : fieldPatterns) {\n                if (fieldPattern.type() == WILDCARD || fieldPattern.type() == ANYTHING_BUT_WILDCARD) {\n                    return true;\n                }\n            }\n        }\n        return false;\n    }\n}\n```\n\nThe main class you'll interact with implements state-machine based rule\nmatching.  The interesting methods are:\n\n* `addRule()` - adds a new rule to the machine\n* `deleteRule()` - deletes a rule from the machine\n* `rulesForEvent()`/`rulesForJSONEvent()` - finds the rules in the machine that match an event\n\nThere are two flavors: `Machine` and `GenericMachine\u003cT\u003e`.  Machine is simply `GenericMachine\u003cString\u003e`.  The\nAPI refers to the generic type as \"name\", which reflects history: The String version was built first and\nthe strings it stored and returned were thought of as rule names.\n\nFor safety, the type used to \"name\" rules should be immutable. If you change the content of an object while\nit's being used as a rule name, this may break the operation of Ruler.\n\n### Configuration\n\nThe GenericMachine and Machine constructors optionally accept a GenericMachineConfiguration object, which exposes the\nfollowing configuration options.\n\n#### additionalNameStateReuse\nDefault: false\nNormally, NameStates are re-used for a given key subsequence and pattern if this key subsequence and pattern have been\npreviously added, or if a pattern has already been added for the given key subsequence. Hence, by default, NameState\nre-use is opportunistic. But by setting this flag to true, NameState re-use will be forced for a key subsequence. This\nmeans that the first pattern being added for a key subsequence will re-use a NameState if that key subsequence has been\nadded before. Meaning each key subsequence has a single NameState. This improves memory utilization exponentially in\nsome cases but does lead to more sub-rules being stored in individual NameStates, which Ruler sometimes iterates over,\nwhich can cause a modest runtime performance regression. This defaults to false for backwards compatibility, but likely,\nall but the most latency sensitive of applications would benefit from setting this to true.\n\nHere's a simple example. Consider:\n\n```javascript\nmachine.addRule(\"0\", \"{\\\"key1\\\": [\\\"a\\\", \\\"b\\\", \\\"c\\\"]}\");\n```\n\nThe pattern \"a\" creates a NameState, and then, even with additionalNameStateReuse=false, the second pattern (\"b\") and\nthird pattern (\"c\") re-use that same NameState. But consider the following instead:\n\n```javascript\nmachine.addRule(\"0\", \"{\\\"key1\\\": [\\\"a\\\"]}\");\nmachine.addRule(\"1\", \"{\\\"key1\\\": [\\\"b\\\"]}\");\nmachine.addRule(\"2\", \"{\\\"key1\\\": [\\\"c\\\"]}\");\n```\n\nNow, with additionalNameStateReuse=false, we end up with three NameStates, because the first pattern encountered for a\nkey subsequence on each rule addition will create a new NameState. So, \"a\", \"b\", and \"c\" all get their own NameStates.\nHowever, with additionalNameStateReuse=true, \"a\" will create a new NameState, then \"b\" and \"c\" will reuse this same\nNameState. This is accomplished by storing that we already have a NameState for the key subsequence \"key1\".\n\nNote that it doesn't matter if each addRule uses a different rule name or the same rule name.\n\n### addRule()\n\nAll forms of this method have the same first argument, a String which provides\nthe name of the Rule and is returned by `rulesForEvent()`.  The rest of the\narguments provide the name/value pairs.  They may be provided in JSON as in\nthe examples above (via a String, a Reader, an InputStream, or `byte[]`), or as\na `Map\u003cString, List\u003cString\u003e\u003e`, where the keys are the field names and the\nvalues are the list of possible matches; using the example above, there would\nbe a key named `detail.state` whose value would be the list containing\n`\"initializing\"` and `\"running\"`.\n\nNote: This method (and also `deleteRule()`) is synchronized, so only one thread\nmay be updating the machine at any point in time.\n\n#### Rules and rule names\n\nYou can call `addRule()` multiple times with the same name but multiple different\nname/value patterns, thus  achieving an \"or\" relationship;\n`rulesForEvent()` will return that name if any of the patterns match.\n\nFor example, suppose you call `addRule()` with rule name as \"R1\" and add\nthe following pattern:\n```javascript\n{\n  \"detail\": {\n    \"c-count\": [ { \"numeric\": [ \"\u003e\", 0, \"\u003c=\", 5 ] } ]\n  }\n}\n```\nThen you call it again with the same name but a different pattern:\n\n```javascript\n{\n  \"detail\": {\n    \"x-limit\": [ { \"numeric\": [ \"=\", 3.018e2 ] } ]\n  }\n}\n```\nAfter this, `rulesForEvent()` will return \"R1\" for **either** a `c-count` value of 2\n**or** an `x-limit` value of 301.8.\n\n### deleteRule()\n\nThis is a mirror-image of `addRule()`; in each case the first argument is the rule\nname, given as a String.  Subsequent arguments provide the names and values,\nand may be given in any of the same ways as with `addRule()`.\n\nNote: This method (and also `addRule()`) is synchronized, so only one thread may\nbe updating the machine at any point in time.\n\nThe operation of this API can be subtle.  The Machine compiles the mapping\nof name/value patterns to Rule names into a finite automaton, but does not\nremember what patterns are mapped to a given Rule name. Thus, there is no\nrequirement that the pattern in a `deleteRule()` exactly match that in the\ncorresponding `addRule()`.  Ruler will look for matches to the name/value patterns\nand see if they give a match to a rule with the provided name, and if so\nremove them. Bear in mind that while performing `deleteRule()` calls that do not exactly\nmatch the corresponding `addRule()` calls will not fail and will not leave the\nmachine in an inconsistent state, they may cause \"garbage\" to build up in the\nMachine.\n\nA specific consequence is that if you have called `addRule()` multiple times with\nthe same name but different patterns, as illustrated above in the *Rules and rule\nnames* section, you would have to call `deleteRule()` the same number of times,\nwith the same associated patterns, to remove all references to that rule name\nfrom the machine.\n\n### rulesForEvent() / rulesForJSONEvent()\n\nThis method returns a `List\u003cString\u003e` for Machine (and `List\u003cT\u003e` for GenericMachine) which contains\nthe names of the rules that match the provided event.  The event may be provided to either method\nas a single `String` representing its JSON form.\n\nThe event may also be provided to `rulesForEvent()` as a collection of strings which alternate field\nnames and values, and must be sorted lexically by field-name.  This may be a `List\u003cString\u003e` or `String[]`.\n\nProviding the event in JSON is the recommended approach and has several advantages. First of all,\npopulating the String list or array with alternating name/value quantities, in an order sorted by name,\nis tricky, and Ruler doesn't help, just fails to work correctly if the list is improperly structured.  Adding\nto the difficulty, the representation of field values, provided as strings, must follow JSON-syntax\nrules - see below under *JSON text matching*.\n\nFinally, the list/array version of an event makes it impossible for Ruler to recognize array\nstructures and provide array-consistent matching, described below in this document. The\n`rulesForEvent(String eventJSON)` API is deprecated in favor of `rulesForJSONEvent()`\nspecifically because it does not support array-consistent matching.\n\n`rulesForJSONEvent()` also has the advantage that the code which turns the JSON form\nof the event into a sorted list has been extensively profiled and optimized.\n\nThe performance of `rulesForEvent()` and `rulesForJSONEvent()` do not depend on the number of rules added\nwith `addRule()`.  `rulesForJSONEvent()` is generally faster because of the optimized\nevent processing. If you do your own event processing and call `rulesForEvent()`\nwith a pre-sorted list of name and values, that is faster still; but you may not\nbe able to do the field-list preparation as fast as `rulesForJSONEvent()` does.\n\n### approximateObjectCount()\n\nThis method roughly the number of objects within the machine. It's value only varies as rule are added or\nremoved. This is useful to identify large machines that potentially require loads of memory.\nAs this method is dependent on number of internal objects, this counts may change when ruler library internals\nare changed. The method performs all of its calculation at runtime to avoid taking up memory and making the\nimpact of large rule-machines worse. Its computation is intentionally NOT thread-safe to avoid blocking rule\nevaluations and machine changes. It means that if a parallel process is adding or removing from the machine,\nyou may get a different results compared to when such parallel processes are complete. Also, as the library\nmakes optimizations to its internals for some patterns (see `ShortcutTransition.java` for more details), you\nmay also get different results depending on the order in which rules were added or removed.\n\n### The Patterns API\n\nIf you think of your events as name/value pairs rather than nested JSON-style\ndocuments, the `Patterns` class (and its `Range` subclass) may be useful in constructing rules.  The following\nstatic methods are useful.\n\n```java\npublic static ValuePatterns exactMatch(final String value);\npublic static ValuePatterns prefixMatch(final String prefix);\npublic static ValuePatterns prefixEqualsIgnoreCaseMatch(final String prefix);\npublic static ValuePatterns suffixMatch(final String suffix);\npublic static ValuePatterns suffixEqualsIgnoreCaseMatch(final String suffix);\npublic static ValuePatterns equalsIgnoreCaseMatch(final String value);\npublic static ValuePatterns wildcardMatch(final String value);\npublic static AnythingBut anythingButMatch(final String anythingBut);\npublic static AnythingBut anythingButMatch(final Set\u003cString\u003e anythingButs);\npublic static AnythingBut anythingButMatch(final double anythingBut);\npublic static AnythingBut anythingButNumberMatch(final Set\u003cDouble\u003e anythingButs);\npublic static AnythingButValuesSet anythingButPrefix(final String prefix);\npublic static AnythingButValuesSet anythingButPrefix(final Set\u003cString\u003e anythingButs);\npublic static AnythingButValuesSet anythingButSuffix(final String suffix);\npublic static AnythingButValuesSet anythingButSuffix(final Set\u003cString\u003e anythingButs);\npublic static AnythingButValuesSet anythingButIgnoreCaseMatch(final String anythingBut);\npublic static AnythingButValuesSet anythingButIgnoreCaseMatch(final Set\u003cString\u003e anythingButs);\npublic static AnythingButValuesSet anythingButWildcard(final String value);\npublic static AnythingButValuesSet anythingButWildcard(final Set\u003cString\u003e anythingButs);\npublic static ValuePatterns numericEquals(final double val);\npublic static Range lessThan(final double val);\npublic static Range lessThanOrEqualTo(final double val);\npublic static Range greaterThan(final double val);\npublic static Range greaterThanOrEqualTo(final double val);\npublic static Range between(final double bottom, final boolean openBottom, final double top, final boolean openTop);\n```\n\nOnce you have constructed appropriate `Patterns` matchers with these methods, you can use the\nfollowing methods to add to or delete from your machine:\n\n```java\npublic void addPatternRule(final String name, final Map\u003cString, List\u003cPatterns\u003e\u003e namevals);\npublic void deletePatternRule(final String name, final Map\u003cString, List\u003cPatterns\u003e\u003e namevals);\n```\n\nNOTE: The cautions listed in [`deleteRule()`](#deleterule) apply\nto `deletePatternRule()` as well.\n\n## JSON text matching\n\nThe field values in rules must be provided in their JSON representations.\nThat is to say, string values must be enclosed in \"quotes\". Unquoted values\nare allowed, such as numbers (`-3.0e5`) and certain JSON-specific literals (`true`,\n`false`, and `null`).\n\nThis can be entirely ignored if rules are provided to `addRule()`() in JSON form,\nor if you are working with Patterns as opposed to literal strings.\nBut if you are providing rules as name/value pairs, and you want to specify\nthat the field \"xyz\" matches the string \"true\", that has to be expressed as\n`\"xyz\", \"\\\"true\\\"\"`.  On the other hand, `\"xyz\", \"true\"` would match only the\nJSON literal `true`.\n\n## JSON Array Matching\n\nRuler supports rule-matching for events containing arrays, but only when the event\nis provided in JSON form - when it's a list of pre-sorted fields, the array structure\nin the event is lost.  The behavior also depends on whether you use `rulesForEvent()`\nor `rulesForJSONEvent`.\n\nConsider the following Event.\n\n\n```javascript\n{\n  \"employees\":[\n    { \"firstName\":\"John\", \"lastName\":\"Doe\" },\n    { \"firstName\":\"Anna\", \"lastName\":\"Smith\" },\n    { \"firstName\":\"Peter\", \"lastName\":\"Jones\" }\n  ]\n}\n```\n\nThen this rule will match:\n\n```javascript\n{ \"employees\": { \"firstName\": [ \"Anna\" ] } }\n```\n\nThat is to say, the array structure is \"crushed out\" of the rule pattern,\nand any contained objects are treated as if they are the value of the\nparent field.  This works for multi-level arrays too:\n\n```javascript\n{\n  \"employees\":[\n    [\n      { \"firstName\":\"John\", \"lastName\":\"Doe\" },\n      { \"firstName\":\"Anna\", \"lastName\":\"Smith\" }\n    ],\n    [\n      { \"firstName\":\"Peter\", \"lastName\":\"Jones\" }\n    ]\n  ]\n}\n```\n\nIn earlier versions of Ruler, the only Machine-based matching method\nwas `rulesForEvent()` which unfortunately will also match the following rule:\n\n```javascript\n{ \"employees\": { \"firstName\": [ \"Anna\" ], \"lastName\": [ \"Jones\" ] } }\n```\n\nAs a fix, Ruler introduced `rulesForJSONEvent()` which, as the name suggests, only\nmatches events provided in JSON form. `rulesForJsonEvent()` will *not* match the\n\"Anna\"/\"Jones\" rule above.\n\nFormally: `rulesForJSONEvent()` will refuse to recognize any match in which\nany two fields are within JSON objects that are in different elements of the same array.\nIn practice, this means that it does about what you would expect.\n\n## Compiling and checking rules\n\nThere is a supporting class `com.amazon.fsm.ruler.RuleCompiler`.  It contains a\nmethod named `check()` which accepts a JSON rule definition and returns a\nString value which, if null, means that the rule was syntactically valid.  If\nthe return value is non-Null it contains a human-readable error message\ndescribing the problem.\n\nFor convenience, it also contains a method named `compile()` which works just\nlike `check()` but signals an error by throwing an IOException and, on\nsuccess, returns a `Map\u003cString\u003e, List\u003cString\u003e\u003e` in the form that Machine's\n`addRule()` method expects. Since the Machine class uses this internally,\nthis method may be a time-saver.\n\n#### Caveat: Compiled rules and JSON keys with dots\n\nWhen Ruler compiles keys, it uses dot (`.`) as the joining character. This means \nit will compile the following two rules to the same internal representation \n\n```javascript\n## has no dots in keys\n{ \"detail\" : { \"state\": { \"status\": [ \"running\" ] } } }\n\n## has dots in keys\n{ \"detail\" : { \"state.status\": [ \"running\" ] } }\n```\n\nIt also means that these rules will match against following two events : \n\n```javascript\n## has no dots in keys\n{ \"detail\" : { \"state\": { \"status\": \"running\" } } }\n\n## has dots in keys\n{ \"detail\" : { \"state.status\": \"running\"  } }\n```\n\nThis behaviour may change in future version (to avoid any confusions) and should not be relied upon.\n\n## Performance\n\nWe measure Ruler's performance by compiling multiple rules into a Machine and matching events provided as JSON strings.\n\nA benchmark which processes 213,068 JSON events with average size about 900 bytes against 5 each exact-match,\nprefix-match, suffix-match, equals-ignore-case-match, wildcard-match, numeric-match, and anything-but-match rules and\ncounts the matches, yields the following on a 2019 MacBook:\n\nEvents are processed at over 220K/second except for:\n - equals-ignore-case matches, which are processed at over 200K/second.\n - prefix/equals-ignore-case matches, which are processed at over 200K/second.\n - suffix/equals-ignore-case matches, which are processed at over 200K/second.\n - wildcard matches, which are processed at over 170K/second.\n - anything-but matches, which are processed at over 150K/second.\n - numeric matches, which are processed at over 120K/second.\n - complex array matches, which are processed at over 35K/second.\n\n### Suggestions for better performance\n\nHere are some suggestions on processing rules and events:\n1. If your team is still using old API -- rulesForEvent, switch to rulesForJSONEvent API. Due to limited resource, old API will not be maintained well thought contributions are always welcomed.\n2. If your team does event flattening by yourself,  you are recommended to use Ruler to flatten the event, just pass Json string or Json node. We have many optimizations within Ruler parsing code.\n3. if your team does Rule Json parsing by yourself, you are recommended to just pass the Json described rule string directly to Ruler, in which will do some pre-processing, e.g. add “”.\n4. In order to well protect the system and prevent ruler from hitting worse condition, limit number of fields in event and rule, e.g. for big event, consider to split to multiple small event and call ruler multiple times. while number of rule is purely depending on your memory budget which is up to you to decide that, but number of fields described in the rule is most important and sensitive on performance, if possible, try to design it as small as possible.\n\nFrom performance consideration, Ruler is sensitive on below items, so, when you design the schema of your event and rule, here are some suggestions:\n1. Try to make Key be diverse both in event and rules, the more heterogeneous fields in event and rule, the higher performance.\n2. Shorten number of fields inside rules, the less key in the rules, the short path to find them out.\n3. Shorten number of fields inside event,  the less key inside event, the less attempts will be required to find out rules.\n4. Shorten number of possible value in […](e.g. “a”:[1,2,3 …100] ) both inside event and rules, the more value, the more branches produced in FSM to iterator, then the more time takes for matching.\n\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License. See [LICENSE](LICENSE) for more information.\n\n\n","funding_links":[],"categories":["Tools","Java"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Fevent-ruler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Fevent-ruler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Fevent-ruler/lists"}