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

Branches

Tags

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

Clone

HTTPS

Download ZIP

pint/docs

docs/configuration.md

356lines · 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 headers = { "...": "..." }
171 timeout = "2m"
172 concurrency = 16
173 rateLimit = 100
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- `headers` - a list of HTTP headers that will be set on all requests for this Prometheus
192 server.
193- `timeout` - timeout to be used for API requests. Defaults to 2 minutes.
194- `concurrency` - how many concurrent requests can pint send to this Prometheus server.
195 Optional, defaults to 16.
196- `rateLimit` - per second rate limit for all API requests send to this Prometheus server.
197 Setting it to `1000` would allow for up to 1000 requests per each wall clock second.
198 Optional, default to 100 requests per second.
199- `uptime` - metric selector used to detect gaps in Prometheus uptime.
200 Since some checks are sending queries to validate if given metric always present in Prometheus
201 they might find gaps when Prometheus itself was down. Pint tries to detect that by querying
202 metrics that are always guarnateed to be present when Prometheus is running.
203 By default metric used for this is `up`, which is generated by Prometheus itself, see
204 [Prometheus docs](https://prometheus.io/docs/concepts/jobs_instances/#automatically-generated-labels-and-time-series)
205 for details.
206 Uptime gap detection works by running a range query `count(up)` and checking for any gaps
207 in the response.
208 Since `up` metric can have a lot of time series `count(up)` might be slow and expensive.
209 An alternative is to use one of metrics exposed by Prometheus itself, like `prometheus_build_info`, but
210 those metrics are only present if Prometheus is configured to scrape itself, so `up` is used by default
211 since it's guaranteed to work in every setup.
212 If your Prometheus has a lot of time series and it's configured to scrape itself then
213 it is recommeded to set `uptime` field to `prometheus_build_info`.
214- `required` - decides how pint will report errors if it's unable to get a valid response
215 from this Prometheus server. If `required` is `true` and all API calls to this Prometheus
216 fail pint will report those as `bug` level problem. If it's set to `false` pint will
217 report those with `warning` level.
218 Default value for `required` is `false`. Set it to `true` if you want to hard fail
219 in case of remote Prometheus issues. Note that setting it to `true` might block
220 PRs when running `pint ci` until pint is able to talk to Prometheus again.
221- `include` - optional path filter, if specified only paths matching one of listed regexp
222 patterns will use this Prometheus server for checks.
223- `exclude` - optional path filter, if specified any path matching one of listed regexp
224 patterns will never use this Prometheus server for checks.
225 `exclude` takes precedence over `include.
226
227Example:
228
229```js
230prometheus "prod" {
231 uri = "https://prometheus-prod.example.com"
232 headers = {
233 "X-Auth": "secret"
234 }
235 concurrency = 40
236}
237
238prometheus "staging" {
239 uri = "https://prometheus-staging.example.com"
240 uptime = "prometheus_build_info"
241}
242
243prometheus "dev" {
244 uri = "https://prometheus-dev.example.com"
245 timeout = "30s"
246 include = [ "alerts/test/.*" ]
247 exclude = [ "alerts/test/docs/.*" ]
248}
249```
250
251## Matching rules to checks
252
253Most checks, except basic syntax verification, requires some configuration to decide
254which checks to run against which files and rules.
255
256Syntax:
257
258```js
259rule {
260 match {
261 path = "(.+)"
262 name = "(.+)"
263 kind = "alerting|recording"
264 command = "ci|lint|watch"
265 annotation "(.*)" {
266 value = "(.*)"
267 }
268 label "(.*)" {
269 value = "(.*)"
270 }
271 for = "..."
272 }
273 match { ... }
274 match { ... }
275 ignore {
276 path = "(.+)"
277 name = "(.+)"
278 kind = "alerting|recording"
279 command = "ci|lint|watch"
280 annotation "(.*)" {
281 value = "(.*)"
282 }
283 label "(.*)" {
284 value = "(.*)"
285 }
286 for = "..."
287 }
288 ignore { ... }
289 ignore { ... }
290
291 [ check definition ]
292 ...
293 [ check definition ]
294}
295```
296
297- `match:path` - only files matching this pattern will be checked by this rule
298- `match:name` - only rules with names (`record` for recording rules and `alert` for alerting
299 rules) matching this pattern will be checked rule
300- `match:kind` - optional rule type filter, only rule of this type will be checked
301- `match:command` - optional command type filter, this allows to include or ignore rules
302 based on the command pint is run with `pint ci`, `pint lint` or `pint watch`.
303- `match:annotation` - optional annotation filter, only alert rules with at least one
304 annotation matching this pattern will be checked by this rule.
305- `match:label` - optional annotation filter, only rules with at least one label
306 matching this pattern will be checked by this rule. For recording rules only static
307 labels set on the recording rule are considered.
308- `match:for` - optional alerting rule `for` filter. If set only alerting rules with `for`
309 field present and matching provided value will be checked by this rule. Recording rules
310 will never match it as they don't have `for` field.
311 Syntax is `OP DURATION` where `OP` can be any of `=`, `!=`, `>`, `>=`, `<`, `<=`.
312- `ignore` - works exactly like `match` but does the opposite - any alerting or recording rule
313 matching all conditions defined on `ignore` will not be checked by this `rule` block.
314
315Note: both `match` and `ignore` require all defined filters to be satisfied to work.
316If multiple `match` and/or `ignore` rules are present any of them needs to match for the rule to
317be matched / ignored.
318
319Examples:
320
321```js
322rule {
323 match {
324 path = "rules/.*"
325 kind = "alerting"
326 label "severity" {
327 value = "(warning|critical)"
328 }
329 }
330 ignore {
331 command = "watch"
332 }
333 [ check applied only to severity="critical" and severity="warning" alerts in "ci" or "lint" command is run ]
334}
335```
336
337```js
338rule {
339 ignore {
340 command = "watch"
341 }
342 ignore {
343 command = "lint"
344 }
345 [ check applied unless "watch" or "lint" command is run ]
346}
347```
348
349```js
350rule {
351 match {
352 for = ">= 5m"
353 }
354 [ check applied only to alerting rules with "for" field value that is >= 5m ]
355}
356```
357