GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

cloudflare/pint

Public

mirrored from https://github.com/cloudflare/pintAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
v0.28.0

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

pint/docs

docs/configuration.md

332lines · modecode

RawDownload
Latest commit unavailable.
1---
2layout: default
3title: Configuration
4parent: Documentation
5nav_order: 2
6---
7
8# Configuration syntax
9
10## Table of contents
11{: .no_toc .text-delta }
12
131. TOC
14{:toc}
15
16## Regexp matchers
17
18All regexp patterns use [Go regexp](https://pkg.go.dev/regexp) module and are fully anchored.
19This 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.
21This follows [PromQL behavior](https://prometheus.io/docs/prometheus/latest/querying/basics/)
22for consistency with Prometheus.
23If you have a string `alice bob john` and you want to match a substring `bob`, then be sure to use
24`.*bob.*`.
25
26When using regexp matcher in checks configuration you can reference alerting and recording rule
27fields in the regexp using [Go text/template](https://pkg.go.dev/text/template) syntax.
28Rule 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
37Accessing a field that's not present in the rule will return an empty string.
38
39## Parser
40
41Configure how pint parses Prometheus rule files.
42
43Syntax:
44
45```js
46parser {
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
71Configure continuous integration environments.
72
73Syntax:
74
75```js
76ci {
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
95Configure supported code hosting repository, used for reporting PR checks from CI
96back to the repository, to be displayed in the PR UI.
97Currently it only supports [BitBucket](https://bitbucket.org/) and [GitHub](https://github.com/).
98
99**NOTE**: BitBucket integration requires `BITBUCKET_AUTH_TOKEN` environment variable
100to 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
103to be set to a personal access key that can access your repository.
104
105**NOTE** Pull request number must be known to pint so it can add comments if it detects any problems.
106If pint is run as part of GitHub actions workflow then this number will be detected from `GITHUB_REF`
107environment variable. For other use cases `GITHUB_PULL_REQUEST_NUMBER` environment variable must be set
108with the pull request number.
109
110Syntax:
111
112```js
113repository {
114 bitbucket {
115 uri = "https://..."
116 timeout = "1m"
117 project = "..."
118 repository = "..."
119 }
120}
121```
122
123- `bitbucket:uri` - base URI of this repository, will be used for HTTP
124 requests to the BitBucket API.
125- `bitbucket:timeout` - timeout to be used for API requests, defaults to 1 minute.
126- `bitbucket:project` - name of the BitBucket project for this repository.
127- `bitbucket:repository` - name of the BitBucket repository.
128
129```js
130repository {
131 github {
132 baseuri = "https://..."
133 uploaduri = "https://..."
134 timeout = "1m"
135 owner = "..."
136 repo = "..."
137 }
138}
139```
140
141- `github:baseuri` - base URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API.
142 If not set `pint` will try to use `GITHUB_API_URL` environment variable instead (if set).
143- `github:uploaduri` - upload URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API.
144 If not set `pint` will try to use `GITHUB_API_URL` environment variable instead (if set).
145
146If `github:baseuri` _or_ `github:uploaduri` are not specified then [GitHub](https://github.com) will be used.
147
148- `github:timeout` - timeout to be used for API requests, defaults to 1 minute.
149- `github:owner` - name of the GitHub owner i.e. the first part that comes before the repository's name in the URI.
150 If not set `pint` will try to use `GITHUB_REPOSITORY` environment variable instead (if set).
151- `github:repo` - name of the GitHub repository (e.g. `monitoring`).
152 If not set `pint` will try to use `GITHUB_REPOSITORY` environment variable instead (if set).
153
154Most GitHub settings can be detected from environment variables that are set inside GitHub Actions
155environment. The only exception is `GITHUB_AUTH_TOKEN` environment variable that must be set
156manually.
157
158## Prometheus servers
159
160Some checks work by querying a running Prometheus instance to verify if
161metrics used in rules are present. If you want to use those checks then you
162first need to define one or more Prometheus servers.
163
164Syntax:
165
166```js
167prometheus "$name" {
168 uri = "https://..."
169 failover = ["https://...", ...]
170 timeout = "2m"
171 concurrency = 16
172 rateLimit = 100
173 cache = 10000
174 required = true|false
175 include = ["...", ...]
176 exclude = ["...", ...]
177}
178```
179
180- `$name` - each defined server should have a unique name that can be used in check
181 definitions.
182- `uri` - base URI of this Prometheus server, used for API requests and queries.
183- `failover` - list of URIs to try (in order they are specified) if `uri` doesn't respond
184 to requests or returns an error. This allows to configure failover Prometheus servers
185 to avoid CI failures in case main Prometheus server is unreachable.
186 Failover URIs are not used if Prometheus returns an error caused by the query, like
187 `many-to-many matching not allowed`.
188 It's highly recommended that all URIs point to Prometheus servers with identical
189 configuration, otherwise pint checks might return unreliable results and potential
190 false positives.
191- `timeout` - timeout to be used for API requests. Defaults to 2 minutes.
192- `concurrency` - how many concurrent requests can pint send to this Prometheus server.
193 Optional, defaults to 16.
194- `rateLimit` - per second rate limit for all API requests send to this Prometheus server.
195 Setting it to `1000` would allow for up to 1000 requests per each wall clock second.
196 Optional, default to 100 requests per second.
197- `cache` - size of the query cache, defaults to 10000.
198- `required` - decides how pint will report errors if it's unable to get a valid response
199 from this Prometheus server. If `required` is `true` and all API calls to this Prometheus
200 fail pint will report those as `bug` level problem. If it's set to `false` pint will
201 report those with `warning` level.
202 Default value for `required` is `false`. Set it to `true` if you want to hard fail
203 in case of remote Prometheus issues. Note that setting it to `true` might block
204 PRs when running `pint ci` until pint is able to talk to Prometheus again.
205- `include` - optional path filter, if specified only paths matching one of listed regexp
206 patterns will use this Prometheus server for checks.
207- `exclude` - optional path filter, if specified any path matching one of listed regexp
208 patterns will never use this Prometheus server for checks.
209 `exclude` takes precedence over `include.
210
211Example:
212
213```js
214prometheus "prod" {
215 uri = "https://prometheus-prod.example.com"
216 concurrency = 40
217}
218
219prometheus "dev" {
220 uri = "https://prometheus-dev.example.com"
221 timeout = "30s"
222 include = [ "alerts/test/.*" ]
223 exclude = [ "alerts/test/docs/.*" ]
224}
225```
226
227## Matching rules to checks
228
229Most checks, except basic syntax verification, requires some configuration to decide
230which checks to run against which files and rules.
231
232Syntax:
233
234```js
235rule {
236 match {
237 path = "(.+)"
238 name = "(.+)"
239 kind = "alerting|recording"
240 command = "ci|lint|watch"
241 annotation "(.*)" {
242 value = "(.*)"
243 }
244 label "(.*)" {
245 value = "(.*)"
246 }
247 for = "..."
248 }
249 match { ... }
250 match { ... }
251 ignore {
252 path = "(.+)"
253 name = "(.+)"
254 kind = "alerting|recording"
255 command = "ci|lint|watch"
256 annotation "(.*)" {
257 value = "(.*)"
258 }
259 label "(.*)" {
260 value = "(.*)"
261 }
262 for = "..."
263 }
264 ignore { ... }
265 ignore { ... }
266
267 [ check definition ]
268 ...
269 [ check definition ]
270}
271```
272
273- `match:path` - only files matching this pattern will be checked by this rule
274- `match:name` - only rules with names (`record` for recording rules and `alert` for alerting
275 rules) matching this pattern will be checked rule
276- `match:kind` - optional rule type filter, only rule of this type will be checked
277- `match:command` - optional command type filter, this allows to include or ignore rules
278 based on the command pint is run with `pint ci`, `pint lint` or `pint watch`.
279- `match:annotation` - optional annotation filter, only alert rules with at least one
280 annotation matching this pattern will be checked by this rule.
281- `match:label` - optional annotation filter, only rules with at least one label
282 matching this pattern will be checked by this rule. For recording rules only static
283 labels set on the recording rule are considered.
284- `match:for` - optional alerting rule `for` filter. If set only alerting rules with `for`
285 field present and matching provided value will be checked by this rule. Recording rules
286 will never match it as they don't have `for` field.
287 Syntax is `OP DURATION` where `OP` can be any of `=`, `!=`, `>`, `>=`, `<`, `<=`.
288- `ignore` - works exactly like `match` but does the opposite - any alerting or recording rule
289 matching all conditions defined on `ignore` will not be checked by this `rule` block.
290
291Note: both `match` and `ignore` require all defined filters to be satisfied to work.
292If multiple `match` and/or `ignore` rules are present any of them needs to match for the rule to
293be matched / ignored.
294
295Examples:
296
297```js
298rule {
299 match {
300 path = "rules/.*"
301 kind = "alerting"
302 label "severity" {
303 value = "(warning|critical)"
304 }
305 }
306 ignore {
307 command = "watch"
308 }
309 [ check applied only to severity="critical" and severity="warning" alerts in "ci" or "lint" command is run ]
310}
311```
312
313```js
314rule {
315 ignore {
316 command = "watch"
317 }
318 ignore {
319 command = "lint"
320 }
321 [ check applied unless "watch" or "lint" command is run ]
322}
323```
324
325```js
326rule {
327 match {
328 for = ">= 5m"
329 }
330 [ check applied only to alerting rules with "for" field value that is >= 5m ]
331}
332```
333