promql/aggregate

This check is used to inspect promql expressions and ensure that specific labels are kept or stripped away when aggregating results. It’s mostly useful in recording rules.

Configuration

Syntax:

aggregate "$pattern" {
  comment  = "..."
  severity = "bug|warning|info"
  keep     = [ "...", ... ]
  strip    = [ "...", ... ]
}

• $pattern - regexp pattern to match rule name on, this can be templated to reference checked rule fields, see Configuration for details.
• comment - set a custom comment that will be added to reported problems.
• severity - set custom severity for reported issues, defaults to a warning.
• keep - list of label names that must be preserved.
• strip - list of label names that must be stripped.

How to enable it

This check is not enabled by default as it requires explicit configuration to work. To enable it add one or more rule {...} blocks and specify all required rules there.

Examples:

Ensure that all series generated from recording rules have job labels preserved:

rule {
  match {
    kind = "recording"
  }
  aggregate ".+" {
    keep    = ["job"]
    comment = "`job` label must be kept on all aggregated metrics so we can link it with a scrape job"
  }
}

In some cases you might want to ensure that specific labels are removed in aggregations. For example in recording rules that are producing series consumed by federation, where only aggregated results (not per instance) are allowed:

rule {
  match {
    kind = "recording"
  }
  aggregate "cluster:.+" {
    strip = ["instance"]
  }
}

By default all issues found by this check will be reported as warnings. To adjust severity set a custom severity key:

aggregate ".+" {
  ...
  severity = "bug"
}

How to disable it

You can disable this check globally by adding this config block:

checks {
  disabled = ["promql/aggregate"]
}

You can also disable it for all rules inside given file by adding a comment anywhere in that file. Example:

# pint file/disable promql/aggregate

Or you can disable it per rule by adding a comment to it. Example:

# pint disable promql/aggregate

If you want to disable only individual instances of this check you can add a more specific comment.

If keep is set

# pint disable promql/aggregate($label:true)

Example:

# pint disable promql/aggregate(job:true)

If strip is set

# pint disable promql/aggregate($label:false)

Example:

# pint disable promql/aggregate(instance:false)

How to snooze it

You can disable this check until given time by adding a comment to it. Example:

# pint snooze $TIMESTAMP promql/aggregate

Where $TIMESTAMP is either use RFC3339 formatted or YYYY-MM-DD. Adding this comment will disable promql/aggregate until $TIMESTAMP, after that check will be re-enabled.