From d3f9b39e72213b710a2c3de0a4f72f25e9ceb589 Mon Sep 17 00:00:00 2001 From: Robb Kidd Date: Thu, 1 Feb 2024 16:53:53 -0500 Subject: [PATCH] docs: include a warning about surprising not-exists behavior (#979) ## Which problem is this PR solving? - Partially addresses #965 "not-exists is a footgun" ## Short description of the changes - Update rulesMeta description for the Condition Operator to include a warning about using `not-exists` in a rule without also scoping that rule to "span". --------- Co-authored-by: Kent Quirk Co-authored-by: Faith Chikwekwe Co-authored-by: Mary J --- RELEASING.md | 4 +++- config/metadata/rulesMeta.yaml | 6 ++++++ rules_conditions.md | 12 ++++++++++++ 3 files changed, 21 insertions(+), 1 deletion(-) diff --git a/RELEASING.md b/RELEASING.md index 0f89fa1127..c5802f42f0 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -3,7 +3,9 @@ 1. Check that licenses are current with `make verify-licenses` 2. Regenerate documentation with `make all` from within the `tools/convert` folder. If there have been changes to `rules.md`, you may need to manually modify the `rules_complete.yaml` to reflect the same change. -3. If either `refinery_config.md` or `refinery_rules.md` were modified in this release, you must also copy these files to [docs](https://github.com/honeycombio/docs) and do a docs PR. Address any feedback from the the docs team and apply that feedback back into this repo. +3. If either `refinery_config.md` or `refinery_rules.md` were modified in this release, you must also open a [docs](https://github.com/honeycombio/docs) PR and update these files there under `subpages/refinery/` . + Replace the underscores (`_`) in the filenames with a dash (`-`) or the docs linter will be upset. + Address any feedback from the the docs team and apply that feedback back into this repo. 4. After addressing any docs change, add release entry to [changelog](./CHANGELOG.md) - Use below command to get a list of all commits since last release ``` diff --git a/config/metadata/rulesMeta.yaml b/config/metadata/rulesMeta.yaml index fb608fd9fd..52e68448c2 100644 --- a/config/metadata/rulesMeta.yaml +++ b/config/metadata/rulesMeta.yaml @@ -651,6 +651,12 @@ groups: summary: is the comparison operator to use. description: > The comparison operator to use. String comparisons are case-sensitive. + For most cases, use negative operators (`!=`, `does-not-contain`, and + `not-exists`) in a rule with a scope of "span". + WARNING: Rules can have `Scope: trace` or `Scope: span`; a negative + operator with `Scope: trace` will be true if **any** single span in the + entire trace matches the negative condition. + This is almost never desired behavior. - name: Value type: anyscalar summary: is the value to compare against. diff --git a/rules_conditions.md b/rules_conditions.md index 186ddb45ba..2f1c1b2bb4 100644 --- a/rules_conditions.md +++ b/rules_conditions.md @@ -116,6 +116,10 @@ Basic comparison -- `not equals`. The result is true if the value of the named `Field` is not equal to the `Value` specified. See [`Datatype`](#datatype) for how different datatypes are handled. +For most cases, use `'!='` in a rule with a scope of "span". +WARNING: Rules can have `Scope: trace` or `Scope: span`; `'!='` used with `Scope: trace` will be true if **any** single span in the entire trace matches the negative condition. +This is almost never desired behavior. + ### `'<'` Basic comparison -- `less than`. @@ -161,6 +165,10 @@ Comparisons are case-sensitive and exact. Values are always coerced to strings -- the `Datatype` parameter is ignored. +For most cases, use `does-not-contain` in a rule with a scope of "span". +WARNING: Rules can have `Scope: trace` or `Scope: span`; `does-not-contain` used with `Scope: trace` will be true if **any** single span in the entire trace matches the negative condition. +This is almost never desired behavior. + ### `exists` Tests if the specified span contains the field named by the `Field` parameter, without considering its value. @@ -173,6 +181,10 @@ Tests if the specified span does not contain the field named by the `Field` para Both the `Value` and the `Datatype` parameters are ignored. +For most cases, use `not-exists` in a rule with a scope of "span". +WARNING: Rules can have `Scope: trace` or `Scope: span`; `not-exists` used with `Scope: trace` will be true if **any** single span in the entire trace matches the negative condition. +This is almost never desired behavior. + ### `matches` Tests if the span value specified by the `Field` parameter matches the regular expression specified by the `Value` parameter.