From aabf9273b256fcaabf36d896755bd9cd62993b9c Mon Sep 17 00:00:00 2001 From: Oleg Don <31502412+HeadHunter483@users.noreply.github.com> Date: Tue, 14 Nov 2023 19:59:48 +0500 Subject: [PATCH] Update pipeline and sidebar docs --- Insanedocfile | 6 + _sidebar.idoc.md | 4 + _sidebar.md | 4 + pipeline/README.idoc.md | 24 +++- pipeline/README.md | 285 +++++++++++++++++++++++++++++++++++++++- 5 files changed, 321 insertions(+), 2 deletions(-) diff --git a/Insanedocfile b/Insanedocfile index 8c4d85fa1..ea312f2d0 100644 --- a/Insanedocfile +++ b/Insanedocfile @@ -2,10 +2,16 @@ extractors: config-params: '"config-params" /json:\"([a-z_]+)\"/ #2 /default:\"([^"]+)\"/ /(required):\"true\"/ /options:\"([^"]+)\"/' fn-list: '"fn-list" #4 /Plugin\)\s(.+)\s{/' match-modes: '"match-modes" /MatchMode(.*),/ /\"(.*)\"/' + do-if-node: '"do-if-node" /DoIfNode(\w+)\s/' + do-if-field-op: '"do-if-field-op" /doIfField(\w+)OpBytes\s/' + do-if-logical-op: '"do-if-logical-op" /doIfLogical(\w+)Bytes\s/' decorators: config-params: '_ _ /*`%s`* / /*`default=%s`* / /*`%s`* / /*`options=%s`* /' fn-list: '_ _ /`%s`/' match-modes: '_ /%s/ /`match_mode: %s`/' + do-if-node: '_ /%s/' + do-if-field-op: '_ /%s/' + do-if-logical-op: '_ /%s/' templates: - template: docs/*.idoc.md files: ["../pipeline/*.go"] diff --git a/_sidebar.idoc.md b/_sidebar.idoc.md index 42abcb341..bb2e9630e 100644 --- a/_sidebar.idoc.md +++ b/_sidebar.idoc.md @@ -19,6 +19,10 @@ - Output @global-contents-table-plugin-output|links-list +- **Pipeline** + - [Match modes](pipeline/README.md#match-modes) + - [Experimental: Do If rules](pipeline/README.md#experimental-do-if-rules) + - **Other** - [Contributing](/docs/contributing.md) - [License](/docs/license.md) \ No newline at end of file diff --git a/_sidebar.md b/_sidebar.md index 46663300a..4a42a4a30 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -56,6 +56,10 @@ - [stdout](plugin/output/stdout/README.md) +- **Pipeline** + - [Match modes](pipeline/README.md#match-modes) + - [Experimental: Do If rules](pipeline/README.md#experimental-do-if-rules) + - **Other** - [Contributing](/docs/contributing.md) - [License](/docs/license.md) \ No newline at end of file diff --git a/pipeline/README.idoc.md b/pipeline/README.idoc.md index e35179ddb..abb775a21 100644 --- a/pipeline/README.idoc.md +++ b/pipeline/README.idoc.md @@ -1,2 +1,24 @@ -### Match modes +## Match modes @match-modes|header-description + +## Experimental: Do If rules + +This is experimental feature and represents an advanced version of `match_fields`. +The Do If rules are a tree of nodes. The tree is stored in the Do If Checker instance. +When Do If Checker's Match func is called it calls to the root Match func and then +the chain of Match func calls are performed across the whole tree. + +### Node types +@do-if-node|description + +### Field op node +@do-if-field-op-node + +### Field operations +@do-if-field-op|description + +### Logical op node +@do-if-logical-op-node + +### Logical operations +@do-if-logical-op|description diff --git a/pipeline/README.md b/pipeline/README.md index 7fd40a443..11cdb546a 100755 --- a/pipeline/README.md +++ b/pipeline/README.md @@ -1,4 +1,4 @@ -### Match modes +## Match modes #### And `match_mode: and` — matches fields with AND operator @@ -105,4 +105,287 @@ result:
+## Experimental: Do If rules + +This is experimental feature and represents an advanced version of `match_fields`. +The Do If rules are a tree of nodes. The tree is stored in the Do If Checker instance. +When Do If Checker's Match func is called it calls to the root Match func and then +the chain of Match func calls are performed across the whole tree. + +### Node types +**`FieldOp`** Type of node where matching rules for fields are stored. + +
+ +**`LogicalOp`** Type of node where logical rules for applying other rules are stored. + +
+ + +### Field op node +DoIf field op node is considered to always be a leaf in the DoIf tree. +It contains operation to be checked on the field value, the field name to extract data and +the values to check against. + +Params: + - `field_op` - value from field operations list. Required. + - `field` - name of the field to apply operation. Required. + - `values` - list of values to check field. Required non-empty. + - `case_sensitive` - flag indicating whether checks are performed in case sensitive way. Default `true`. + Note: case insensitive checks can cause CPU and memory overhead since every field value will be converted to lower letters. + +Example: +```yaml +pipelines: + tests: + actions: + - type: discard + do_if: + - field_op: suffix + field: pod + values: [pod-1, pod-2] + case_sensitive: true +``` + + +### Field operations +**`Equal`** checks whether the field value is equal to one of the elements in the values list. + +Example: +```yaml +pipelines: + test: + actions: + - type: discard + do_if: + - field_op: equal + field: pod + values: [test-pod-1, test-pod-2] +``` + +result: +``` +{"pod":"test-pod-1","service":"test-service"} # discarded +{"pod":"test-pod-2","service":"test-service-2"} # discarded +{"pod":"test-pod","service":"test-service"} # not discarded +{"pod":"test-pod","service":"test-service-1"} # not discarded +``` + +
+ +**`Contains`** checks whether the field value contains one of the elements the in values list. + +Example: +```yaml +pipelines: + test: + actions: + - type: discard + do_if: + - field_op: contains + field: pod + values: [my-pod, my-test] +``` + +result: +``` +{"pod":"test-my-pod-1","service":"test-service"} # discarded +{"pod":"test-not-my-pod","service":"test-service-2"} # discarded +{"pod":"my-test-pod","service":"test-service"} # discarded +{"pod":"test-pod","service":"test-service-1"} # not discarded +``` + +
+ +**`Prefix`** checks whether the field value has prefix equal to one of the elements in the values list. + +Example: +```yaml +pipelines: + test: + actions: + - type: discard + do_if: + - field_op: prefix + field: pod + values: [test-1, test-2] +``` + +result: +``` +{"pod":"test-1-pod-1","service":"test-service"} # discarded +{"pod":"test-2-pod-2","service":"test-service-2"} # discarded +{"pod":"test-pod","service":"test-service"} # not discarded +{"pod":"test-pod","service":"test-service-1"} # not discarded +``` + +
+ +**`Suffix`** checks whether the field value has suffix equal to one of the elements in the values list. + +Example: +```yaml +pipelines: + test: + actions: + - type: discard + do_if: + - field_op: suffix + field: pod + values: [pod-1, pod-2] +``` + +result: +``` +{"pod":"test-1-pod-1","service":"test-service"} # discarded +{"pod":"test-2-pod-2","service":"test-service-2"} # discarded +{"pod":"test-pod","service":"test-service"} # not discarded +{"pod":"test-pod","service":"test-service-1"} # not discarded +``` + +
+ +**`Regex`** checks whether the field matches any regex from the values list. + +Example: +```yaml +pipelines: + test: + actions: + - type: discard + do_if: + - field_op: regex + field: pod + values: [pod-\d, my-test.*] +``` + +result: +``` +{"pod":"test-1-pod-1","service":"test-service"} # discarded +{"pod":"test-2-pod-2","service":"test-service-2"} # discarded +{"pod":"test-pod","service":"test-service"} # not discarded +{"pod":"my-test-pod","service":"test-service-1"} # discarded +{"pod":"my-test-instance","service":"test-service-1"} # discarded +{"pod":"service123","service":"test-service-1"} # not discarded +``` + +
+ + +### Logical op node +DoIf logical op node is a node considered to be the root or an edge between nodes. +It always has at least one operand which are other nodes and calls their checks +to apply logical operation on their results. + +Params: + - `logical_op` - value from logical operations list. Required. + - `operands` - list of another do-if nodes. Required non-empty. + +Example: +```yaml +pipelines: + test: + actions: + - type: discard + do_if: + - logical_op: and + operands: + - field_op: equal + field: pod + values: [test-pod-1, test-pod-2] + case_sensitive: true + - field_op: equal + field: service + values: [test-service] + case_sensitive: true +``` + + +### Logical operations +**`Or`** accepts at least one operand and returns true on the first returned true from its operands. + +Example: +```yaml +pipelines: + test: + actions: + - type: discard + do_if: + - logical_op: or + operands: + - field_op: equal + field: pod + values: [test-pod-1, test-pod-2] + - field_op: equal + field: service + values: [test-service] +``` + +result: +``` +{"pod":"test-pod-1","service":"test-service"} # discarded +{"pod":"test-pod-2","service":"test-service-2"} # discarded +{"pod":"test-pod","service":"test-service"} # discarded +{"pod":"test-pod","service":"test-service-1"} # not discarded +``` + +
+ +**`And`** accepts at least one operand and returns true if all operands return true +(in other words returns false on the first returned false from its operands). + +Example: +```yaml +pipelines: + test: + actions: + - type: discard + do_if: + - logical_op: and + operands: + - field_op: equal + field: pod + values: [test-pod-1, test-pod-2] + - field_op: equal + field: service + values: [test-service] +``` + +result: +``` +{"pod":"test-pod-1","service":"test-service"} # discarded +{"pod":"test-pod-2","service":"test-service-2"} # not discarded +{"pod":"test-pod","service":"test-service"} # not discarded +{"pod":"test-pod","service":"test-service-1"} # not discarded +``` + +
+ +**`Not`** accepts exactly one operand and returns inverted result of its operand. + +Example: +```yaml +pipelines: + test: + actions: + - type: discard + do_if: + - logical_op: not + operands: + - field_op: equal + field: service + values: [test-service] +``` + +result: +``` +{"pod":"test-pod-1","service":"test-service"} # not discarded +{"pod":"test-pod-2","service":"test-service-2"} # discarded +{"pod":"test-pod","service":"test-service"} # not discarded +{"pod":"test-pod","service":"test-service-1"} # discarded +``` + +
+ +
*Generated using [__insane-doc__](https://github.com/vitkovskii/insane-doc)* \ No newline at end of file