cloudflare/pint
Publicmirrored from https://github.com/cloudflare/pintAvailable
docs/configuration.md
307lines · modecode
| 1 | --- |
| 2 | layout: default |
| 3 | title: Configuration |
| 4 | parent: Documentation |
| 5 | nav_order: 2 |
| 6 | --- |
| 7 | |
| 8 | # Configuration syntax |
| 9 | |
| 10 | ## Table of contents |
| 11 | {: .no_toc .text-delta } |
| 12 | |
| 13 | 1. TOC |
| 14 | {:toc} |
| 15 | |
| 16 | ## Regexp matchers |
| 17 | |
| 18 | All regexp patterns use [Go regexp](https://pkg.go.dev/regexp) module and are fully anchored. |
| 19 | This means that when you pass `.*` regexp expression internally it will be represented as |
| 20 | `^.*$`, where `^` indicates beginning of a string and `$` is the end of string. |
| 21 | This follow [PromQL behavior](https://prometheus.io/docs/prometheus/latest/querying/basics/) |
| 22 | for consistency with Prometheus. |
| 23 | If you have a string `alice bob john` and you want to match a substring `bob`, then be sure to use |
| 24 | `.*bob.*`. |
| 25 | |
| 26 | When using regexp matcher in checks configuration you can reference alerting and recording rule |
| 27 | fields in the regexp using [Go text/template](https://pkg.go.dev/text/template) syntax. |
| 28 | Rule fields are exposed as: |
| 29 | |
| 30 | - `$alert` - rule `alert` field |
| 31 | - `$record` - rule `record` field |
| 32 | - `$expr` - rule `expr` field |
| 33 | - `$for` - rule `for` field |
| 34 | - `$labels` - rule `labels` map, individual labels can be accessed as `$labels.foo` |
| 35 | - `$annotations` - rule `annotations` map, individual annotations can be accessed as `$annotations.foo` |
| 36 | |
| 37 | Accessing a field that's not present in the rule will return an empty string. |
| 38 | |
| 39 | ## Parser |
| 40 | |
| 41 | Configure how pint parses Prometheus rule files. |
| 42 | |
| 43 | Syntax: |
| 44 | |
| 45 | ```js |
| 46 | parser { |
| 47 | relaxed = [ "(.*)", ... ] |
| 48 | } |
| 49 | ``` |
| 50 | |
| 51 | - `relaxed` - by default pint will now parse all files in strict mode, where |
| 52 | all rule files must have the exact syntax Prometheus expects: |
| 53 | |
| 54 | ```yaml |
| 55 | groups: |
| 56 | - name: example |
| 57 | rules: |
| 58 | - record: ... |
| 59 | expr: ... |
| 60 | ``` |
| 61 | |
| 62 | If you're using pint to lint rules that are embedded inside a different structure |
| 63 | you can set this option to allow fuzzy parsing, which will try to find rule |
| 64 | definitions anywhere in the file, without requiring `groups -> rules -> rule` |
| 65 | structure to be present. |
| 66 | This option takes a list of file patterns, all files matching those regexp rules |
| 67 | will be parsed in relaxed mode. |
| 68 | |
| 69 | ## CI |
| 70 | |
| 71 | Configure continuous integration environments. |
| 72 | |
| 73 | Syntax: |
| 74 | |
| 75 | ```js |
| 76 | ci { |
| 77 | include = [ "(.*)", ... ] |
| 78 | maxCommits = 20 |
| 79 | baseBranch = "master" |
| 80 | } |
| 81 | ``` |
| 82 | |
| 83 | - `include` - list of file patterns to check when running checks. Only files |
| 84 | matching those regexp rules will be checked, other modified files will be ignored. |
| 85 | - `maxCommits` - by default pint will try to find all commits on the current branch, |
| 86 | this requires full git history to be present, if we have a shallow clone this |
| 87 | might fail to find only current branch commits and give us a huge list. |
| 88 | If the number of commits returned by branch discovery is more than `maxCommits` |
| 89 | then pint will fail to run. |
| 90 | - `baseBranch` - base branch to compare `HEAD` commit with when calculating the list |
| 91 | of commits to check. |
| 92 | |
| 93 | ## Repository |
| 94 | |
| 95 | Configure supported code hosting repository, used for reporting PR checks from CI |
| 96 | back to the repository, to be displayed in the PR UI. |
| 97 | Currently it only supports [BitBucket](https://bitbucket.org/) and [GitHub](https://github.com/). |
| 98 | |
| 99 | **NOTE**: BitBucket integration requires `BITBUCKET_AUTH_TOKEN` environment variable |
| 100 | to be set. It should contain a personal access token used to authenticate with the API. |
| 101 | |
| 102 | **NOTE**: GitHub integration requires `GITHUB_AUTH_TOKEN` environment variable |
| 103 | to be set to a personal access key that can access your repository. Also, `GITHUB_PULL_REQUEST_NUMBER` |
| 104 | environment variable needs to point to the pull request number which will be used whilst |
| 105 | submitting comments. |
| 106 | |
| 107 | Syntax: |
| 108 | |
| 109 | ```js |
| 110 | repository { |
| 111 | bitbucket { |
| 112 | uri = "https://..." |
| 113 | timeout = "30s" |
| 114 | project = "..." |
| 115 | repository = "..." |
| 116 | } |
| 117 | } |
| 118 | ``` |
| 119 | |
| 120 | - `bitbucket:uri` - base URI of this repository, will be used for HTTP |
| 121 | requests to the BitBucket API. |
| 122 | - `bitbucket:timeout` - timeout to be used for API requests. |
| 123 | - `bitbucket:project` - name of the BitBucket project for this repository. |
| 124 | - `bitbucket:repository` - name of the BitBucket repository. |
| 125 | |
| 126 | ```js |
| 127 | repository { |
| 128 | github { |
| 129 | baseuri = "https://..." |
| 130 | uploaduri = "https://..." |
| 131 | timeout = "30s" |
| 132 | owner = "..." |
| 133 | repo = "..." |
| 134 | } |
| 135 | } |
| 136 | ``` |
| 137 | |
| 138 | - `github:baseuri` - base URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API. |
| 139 | - `github:uploaduri` - upload URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API. |
| 140 | |
| 141 | If `github:baseuri` _or_ `github:uploaduri` are not specified then [GitHub](https://github.com) will be used. |
| 142 | |
| 143 | - `github:timeout` - timeout to be used for API requests; |
| 144 | - `github:owner` - name of the GitHub owner i.e. the first part that comes before the repository's name in the URI; |
| 145 | - `github:repo` - name of the GitHub repository (e.g. `monitoring`). |
| 146 | |
| 147 | ## Prometheus servers |
| 148 | |
| 149 | Some checks work by querying a running Prometheus instance to verify if |
| 150 | metrics used in rules are present. If you want to use those checks then you |
| 151 | first need to define one or more Prometheus servers. |
| 152 | |
| 153 | Syntax: |
| 154 | |
| 155 | ```js |
| 156 | prometheus "$name" { |
| 157 | uri = "https://..." |
| 158 | failover = ["https://...", ...] |
| 159 | timeout = "60s" |
| 160 | required = true|false |
| 161 | paths = ["...", ...] |
| 162 | } |
| 163 | ``` |
| 164 | |
| 165 | - `$name` - each defined server should have a unique name that can be used in check |
| 166 | definitions. |
| 167 | - `uri` - base URI of this Prometheus server, used for API requests and queries. |
| 168 | - `failover` - list of URIs to try (in order they are specified) if `uri` doesn't respond |
| 169 | to requests or returns an error. This allows to configure failover Prometheus servers |
| 170 | to avoid CI failures in case main Prometheus server is unreachable. |
| 171 | Failover URIs are not used if Prometheus returns an error caused by the query, like |
| 172 | `many-to-many matching not allowed`. |
| 173 | It's highly recommended that all URIs point to Prometheus servers with identical |
| 174 | configuration, otherwise pint checks might return unreliable results and potential |
| 175 | false positives. |
| 176 | - `timeout` - timeout to be used for API requests. |
| 177 | - `required` - decides how pint will report errors if it's unable to get a valid response |
| 178 | from this Prometheus server. If `required` is `true` and all API calls to this Prometheus |
| 179 | fail pint will report those as `bug` level problem. If it's set to `false` pint will |
| 180 | report those with `warning` level. |
| 181 | Default value for `required` is `false`. Set it to `true` if you want to hard fail |
| 182 | in case of remote Prometheus issues. Note that setting it to `true` might block |
| 183 | PRs when running `pint ci` until pint is able to talk to Prometheus again. |
| 184 | - `paths` - optional path filter, if specified only paths matching one of listed regexp |
| 185 | patterns will use this Prometheus server for checks. |
| 186 | |
| 187 | Example: |
| 188 | |
| 189 | ```js |
| 190 | prometheus "prod" { |
| 191 | uri = "https://prometheus-prod.example.com" |
| 192 | timeout = "60s" |
| 193 | } |
| 194 | |
| 195 | prometheus "dev" { |
| 196 | uri = "https://prometheus-dev.example.com" |
| 197 | timeout = "30s" |
| 198 | paths = [ "alerts/test/.*" ] |
| 199 | } |
| 200 | ``` |
| 201 | |
| 202 | ## Matching rules to checks |
| 203 | |
| 204 | Most checks, except basic syntax verification, requires some configuration to decide |
| 205 | which checks to run against which files and rules. |
| 206 | |
| 207 | Syntax: |
| 208 | |
| 209 | ```js |
| 210 | rule { |
| 211 | match { |
| 212 | path = "(.+)" |
| 213 | name = "(.+)" |
| 214 | kind = "alerting|recording" |
| 215 | command = "ci|lint|watch" |
| 216 | annotation "(.*)" { |
| 217 | value = "(.*)" |
| 218 | } |
| 219 | label "(.*)" { |
| 220 | value = "(.*)" |
| 221 | } |
| 222 | for = "..." |
| 223 | } |
| 224 | match { ... } |
| 225 | match { ... } |
| 226 | ignore { |
| 227 | path = "(.+)" |
| 228 | name = "(.+)" |
| 229 | kind = "alerting|recording" |
| 230 | command = "ci|lint|watch" |
| 231 | annotation "(.*)" { |
| 232 | value = "(.*)" |
| 233 | } |
| 234 | label "(.*)" { |
| 235 | value = "(.*)" |
| 236 | } |
| 237 | for = "..." |
| 238 | } |
| 239 | ignore { ... } |
| 240 | ignore { ... } |
| 241 | |
| 242 | [ check definition ] |
| 243 | ... |
| 244 | [ check definition ] |
| 245 | } |
| 246 | ``` |
| 247 | |
| 248 | - `match:path` - only files matching this pattern will be checked by this rule |
| 249 | - `match:name` - only rules with names (`record` for recording rules and `alert` for alerting |
| 250 | rules) matching this pattern will be checked rule |
| 251 | - `match:kind` - optional rule type filter, only rule of this type will be checked |
| 252 | - `match:command` - optional command type filter, this allows to include or ignore rules |
| 253 | based on the command pint is run with `pint ci`, `pint lint` or `pint watch`. |
| 254 | - `match:annotation` - optional annotation filter, only alert rules with at least one |
| 255 | annotation matching this pattern will be checked by this rule. |
| 256 | - `match:label` - optional annotation filter, only rules with at least one label |
| 257 | matching this pattern will be checked by this rule. For recording rules only static |
| 258 | labels set on the recording rule are considered. |
| 259 | - `match:for` - optional alerting rule `for` filter. If set only alerting rules with `for` |
| 260 | field present and matching provided value will be checked by this rule. Recording rules |
| 261 | will never match it as they don't have `for` field. |
| 262 | Syntax is `OP DURATION` where `OP` can be any of `=`, `!=`, `>`, `>=`, `<`, `<=`. |
| 263 | - `ignore` - works exactly like `match` but does the opposite - any alerting or recording rule |
| 264 | matching all conditions defined on `ignore` will not be checked by this `rule` block. |
| 265 | |
| 266 | Note: both `match` and `ignore` require all defined filters to be satisfied to work. |
| 267 | If multiple `match` and/or `ignore` rules are present any of them needs to match for the rule to |
| 268 | be matched / ignored. |
| 269 | |
| 270 | Examples: |
| 271 | |
| 272 | ```js |
| 273 | rule { |
| 274 | match { |
| 275 | path = "rules/.*" |
| 276 | kind = "alerting" |
| 277 | label "severity" { |
| 278 | value = "(warning|critical)" |
| 279 | } |
| 280 | } |
| 281 | ignore { |
| 282 | command = "watch" |
| 283 | } |
| 284 | [ check applied only to severity="critical" and severity="warning" alerts in "ci" or "lint" command is run ] |
| 285 | } |
| 286 | ``` |
| 287 | |
| 288 | ```js |
| 289 | rule { |
| 290 | ignore { |
| 291 | command = "watch" |
| 292 | } |
| 293 | ignore { |
| 294 | command = "lint" |
| 295 | } |
| 296 | [ check applied unless "watch" or "lint" command is run ] |
| 297 | } |
| 298 | ``` |
| 299 | |
| 300 | ```js |
| 301 | rule { |
| 302 | match { |
| 303 | for = ">= 5m" |
| 304 | } |
| 305 | [ check applied only to alerting rules with "for" field value that is >= 5m ] |
| 306 | } |
| 307 | ``` |
| 308 | |