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.40.0

Branches

Tags

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

Clone

HTTPS

Download ZIP

pint/docs

docs/configuration.md

380lines · 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## Environment variables
17
18Environment variables can be expanded inside pint configuration file as `ENV_*` HCL
19variables. To use a variable named `FOO` reference it as `${ENV_FOO}`.
20
21Examples:
22
23If you have `AUTH_KEY` environment variable set that you want to use a header
24for Prometheus requests then use this:
25
26```js
27prometheus "..." {
28 uri = "..."
29 headers = {
30 X-Auth = "${ENV_AUTH_KEY}"
31 }
32}
33```
34
35## Regexp matchers
36
37All regexp patterns use [Go regexp](https://pkg.go.dev/regexp) module and are fully anchored.
38This means that when you pass `.*` regexp expression internally it will be represented as
39`^.*$`, where `^` indicates beginning of a string and `$` is the end of string.
40This follows [PromQL behavior](https://prometheus.io/docs/prometheus/latest/querying/basics/)
41for consistency with Prometheus.
42If you have a string `alice bob john` and you want to match a substring `bob`, then be sure to use
43`.*bob.*`.
44
45When using regexp matcher in checks configuration you can reference alerting and recording rule
46fields in the regexp using [Go text/template](https://pkg.go.dev/text/template) syntax.
47Rule fields are exposed as:
48
49- `$alert` - rule `alert` field
50- `$record` - rule `record` field
51- `$expr` - rule `expr` field
52- `$for` - rule `for` field
53- `$labels` - rule `labels` map, individual labels can be accessed as `$labels.foo`
54- `$annotations` - rule `annotations` map, individual annotations can be accessed as `$annotations.foo`
55
56Accessing a field that's not present in the rule will return an empty string.
57
58## Parser
59
60Configure how pint parses Prometheus rule files.
61
62Syntax:
63
64```js
65parser {
66 relaxed = [ "(.*)", ... ]
67}
68```
69
70- `relaxed` - by default pint will now parse all files in strict mode, where
71 all rule files must have the exact syntax Prometheus expects:
72
73 ```yaml
74 groups:
75 - name: example
76 rules:
77 - record: ...
78 expr: ...
79 ```
80
81 If you're using pint to lint rules that are embedded inside a different structure
82 you can set this option to allow fuzzy parsing, which will try to find rule
83 definitions anywhere in the file, without requiring `groups -> rules -> rule`
84 structure to be present.
85 This option takes a list of file patterns, all files matching those regexp rules
86 will be parsed in relaxed mode.
87
88## CI
89
90Configure continuous integration environments.
91
92Syntax:
93
94```js
95ci {
96 include = [ "(.*)", ... ]
97 maxCommits = 20
98 baseBranch = "master"
99}
100```
101
102- `include` - list of file patterns to check when running checks. Only files
103 matching those regexp rules will be checked, other modified files will be ignored.
104- `maxCommits` - by default pint will try to find all commits on the current branch,
105 this requires full git history to be present, if we have a shallow clone this
106 might fail to find only current branch commits and give us a huge list.
107 If the number of commits returned by branch discovery is more than `maxCommits`
108 then pint will fail to run.
109- `baseBranch` - base branch to compare `HEAD` commit with when calculating the list
110 of commits to check.
111
112## Repository
113
114Configure supported code hosting repository, used for reporting PR checks from CI
115back to the repository, to be displayed in the PR UI.
116Currently it only supports [BitBucket](https://bitbucket.org/) and [GitHub](https://github.com/).
117
118**NOTE**: BitBucket integration requires `BITBUCKET_AUTH_TOKEN` environment variable
119to be set. It should contain a personal access token used to authenticate with the API.
120
121**NOTE**: GitHub integration requires `GITHUB_AUTH_TOKEN` environment variable
122to be set to a personal access key that can access your repository.
123
124**NOTE** Pull request number must be known to pint so it can add comments if it detects any problems.
125If pint is run as part of GitHub actions workflow then this number will be detected from `GITHUB_REF`
126environment variable. For other use cases `GITHUB_PULL_REQUEST_NUMBER` environment variable must be set
127with the pull request number.
128
129Syntax:
130
131```js
132repository {
133 bitbucket {
134 uri = "https://..."
135 timeout = "1m"
136 project = "..."
137 repository = "..."
138 }
139}
140```
141
142- `bitbucket:uri` - base URI of this repository, will be used for HTTP
143 requests to the BitBucket API.
144- `bitbucket:timeout` - timeout to be used for API requests, defaults to 1 minute.
145- `bitbucket:project` - name of the BitBucket project for this repository.
146- `bitbucket:repository` - name of the BitBucket repository.
147
148```js
149repository {
150 github {
151 baseuri = "https://..."
152 uploaduri = "https://..."
153 timeout = "1m"
154 owner = "..."
155 repo = "..."
156 }
157}
158```
159
160- `github:baseuri` - base URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API.
161 If not set `pint` will try to use `GITHUB_API_URL` environment variable instead (if set).
162- `github:uploaduri` - upload URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API.
163 If not set `pint` will try to use `GITHUB_API_URL` environment variable instead (if set).
164
165If `github:baseuri` _or_ `github:uploaduri` are not specified then [GitHub](https://github.com) will be used.
166
167- `github:timeout` - timeout to be used for API requests, defaults to 1 minute.
168- `github:owner` - name of the GitHub owner i.e. the first part that comes before the repository's name in the URI.
169 If not set `pint` will try to use `GITHUB_REPOSITORY` environment variable instead (if set).
170- `github:repo` - name of the GitHub repository (e.g. `monitoring`).
171 If not set `pint` will try to use `GITHUB_REPOSITORY` environment variable instead (if set).
172
173Most GitHub settings can be detected from environment variables that are set inside GitHub Actions
174environment. The only exception is `GITHUB_AUTH_TOKEN` environment variable that must be set
175manually.
176
177## Prometheus servers
178
179Some checks work by querying a running Prometheus instance to verify if
180metrics used in rules are present. If you want to use those checks then you
181first need to define one or more Prometheus servers.
182
183Syntax:
184
185```js
186prometheus "$name" {
187 uri = "https://..."
188 failover = ["https://...", ...]
189 tags = ["...", ...]
190 headers = { "...": "..." }
191 timeout = "2m"
192 concurrency = 16
193 rateLimit = 100
194 required = true|false
195 include = ["...", ...]
196 exclude = ["...", ...]
197}
198```
199
200- `$name` - each defined server should have a unique name that can be used in check
201 definitions.
202- `uri` - base URI of this Prometheus server, used for API requests and queries.
203- `failover` - list of URIs to try (in order they are specified) if `uri` doesn't respond
204 to requests or returns an error. This allows to configure failover Prometheus servers
205 to avoid CI failures in case main Prometheus server is unreachable.
206 Failover URIs are not used if Prometheus returns an error caused by the query, like
207 `many-to-many matching not allowed`.
208 It's highly recommended that all URIs point to Prometheus servers with identical
209 configuration, otherwise pint checks might return unreliable results and potential
210 false positives.
211- `tags` - a list of strings that can be used to group Prometheus servers together.
212 Tags cannot contain spaces.
213 Tags can be later used when disabling checks via comments, see [ignoring](ignoring.md).
214- `headers` - a list of HTTP headers that will be set on all requests for this Prometheus
215 server.
216- `timeout` - timeout to be used for API requests. Defaults to 2 minutes.
217- `concurrency` - how many concurrent requests can pint send to this Prometheus server.
218 Optional, defaults to 16.
219- `rateLimit` - per second rate limit for all API requests send to this Prometheus server.
220 Setting it to `1000` would allow for up to 1000 requests per each wall clock second.
221 Optional, default to 100 requests per second.
222- `uptime` - metric selector used to detect gaps in Prometheus uptime.
223 Since some checks are sending queries to validate if given metric always present in Prometheus
224 they might find gaps when Prometheus itself was down. Pint tries to detect that by querying
225 metrics that are always guarnateed to be present when Prometheus is running.
226 By default metric used for this is `up`, which is generated by Prometheus itself, see
227 [Prometheus docs](https://prometheus.io/docs/concepts/jobs_instances/#automatically-generated-labels-and-time-series)
228 for details.
229 Uptime gap detection works by running a range query `count(up)` and checking for any gaps
230 in the response.
231 Since `up` metric can have a lot of time series `count(up)` might be slow and expensive.
232 An alternative is to use one of metrics exposed by Prometheus itself, like `prometheus_build_info`, but
233 those metrics are only present if Prometheus is configured to scrape itself, so `up` is used by default
234 since it's guaranteed to work in every setup.
235 If your Prometheus has a lot of time series and it's configured to scrape itself then
236 it is recommeded to set `uptime` field to `prometheus_build_info`.
237- `required` - decides how pint will report errors if it's unable to get a valid response
238 from this Prometheus server. If `required` is `true` and all API calls to this Prometheus
239 fail pint will report those as `bug` level problem. If it's set to `false` pint will
240 report those with `warning` level.
241 Default value for `required` is `false`. Set it to `true` if you want to hard fail
242 in case of remote Prometheus issues. Note that setting it to `true` might block
243 PRs when running `pint ci` until pint is able to talk to Prometheus again.
244- `include` - optional path filter, if specified only paths matching one of listed regexp
245 patterns will use this Prometheus server for checks.
246- `exclude` - optional path filter, if specified any path matching one of listed regexp
247 patterns will never use this Prometheus server for checks.
248 `exclude` takes precedence over `include.
249
250Example:
251
252```js
253prometheus "prod" {
254 uri = "https://prometheus-prod.example.com"
255 tags = ["prod"]
256 headers = {
257 "X-Auth": "secret"
258 }
259 concurrency = 40
260}
261
262prometheus "staging" {
263 uri = "https://prometheus-staging.example.com"
264 uptime = "prometheus_build_info"
265}
266
267prometheus "dev" {
268 uri = "https://prometheus-dev.example.com"
269 timeout = "30s"
270 include = [ "alerts/test/.*" ]
271 exclude = [ "alerts/test/docs/.*" ]
272}
273```
274
275## Matching rules to checks
276
277Most checks, except basic syntax verification, requires some configuration to decide
278which checks to run against which files and rules.
279
280Syntax:
281
282```js
283rule {
284 match {
285 path = "(.+)"
286 name = "(.+)"
287 kind = "alerting|recording"
288 command = "ci|lint|watch"
289 annotation "(.*)" {
290 value = "(.*)"
291 }
292 label "(.*)" {
293 value = "(.*)"
294 }
295 for = "..."
296 }
297 match { ... }
298 match { ... }
299 ignore {
300 path = "(.+)"
301 name = "(.+)"
302 kind = "alerting|recording"
303 command = "ci|lint|watch"
304 annotation "(.*)" {
305 value = "(.*)"
306 }
307 label "(.*)" {
308 value = "(.*)"
309 }
310 for = "..."
311 }
312 ignore { ... }
313 ignore { ... }
314
315 [ check definition ]
316 ...
317 [ check definition ]
318}
319```
320
321- `match:path` - only files matching this pattern will be checked by this rule
322- `match:name` - only rules with names (`record` for recording rules and `alert` for alerting
323 rules) matching this pattern will be checked rule
324- `match:kind` - optional rule type filter, only rule of this type will be checked
325- `match:command` - optional command type filter, this allows to include or ignore rules
326 based on the command pint is run with `pint ci`, `pint lint` or `pint watch`.
327- `match:annotation` - optional annotation filter, only alert rules with at least one
328 annotation matching this pattern will be checked by this rule.
329- `match:label` - optional annotation filter, only rules with at least one label
330 matching this pattern will be checked by this rule. For recording rules only static
331 labels set on the recording rule are considered.
332- `match:for` - optional alerting rule `for` filter. If set only alerting rules with `for`
333 field present and matching provided value will be checked by this rule. Recording rules
334 will never match it as they don't have `for` field.
335 Syntax is `OP DURATION` where `OP` can be any of `=`, `!=`, `>`, `>=`, `<`, `<=`.
336- `ignore` - works exactly like `match` but does the opposite - any alerting or recording rule
337 matching all conditions defined on `ignore` will not be checked by this `rule` block.
338
339Note: both `match` and `ignore` require all defined filters to be satisfied to work.
340If multiple `match` and/or `ignore` rules are present any of them needs to match for the rule to
341be matched / ignored.
342
343Examples:
344
345```js
346rule {
347 match {
348 path = "rules/.*"
349 kind = "alerting"
350 label "severity" {
351 value = "(warning|critical)"
352 }
353 }
354 ignore {
355 command = "watch"
356 }
357 [ check applied only to severity="critical" and severity="warning" alerts in "ci" or "lint" command is run ]
358}
359```
360
361```js
362rule {
363 ignore {
364 command = "watch"
365 }
366 ignore {
367 command = "lint"
368 }
369 [ check applied unless "watch" or "lint" command is run ]
370}
371```
372
373```js
374rule {
375 match {
376 for = ">= 5m"
377 }
378 [ check applied only to alerting rules with "for" field value that is >= 5m ]
379}
380```