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

Branches

Tags

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

Clone

HTTPS

Download ZIP

pint/docs

docs/configuration.md

338lines · 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 cache = 10000
175 required = true|false
176 include = ["...", ...]
177 exclude = ["...", ...]
178}
179```
180
181- `$name` - each defined server should have a unique name that can be used in check
182 definitions.
183- `uri` - base URI of this Prometheus server, used for API requests and queries.
184- `failover` - list of URIs to try (in order they are specified) if `uri` doesn't respond
185 to requests or returns an error. This allows to configure failover Prometheus servers
186 to avoid CI failures in case main Prometheus server is unreachable.
187 Failover URIs are not used if Prometheus returns an error caused by the query, like
188 `many-to-many matching not allowed`.
189 It's highly recommended that all URIs point to Prometheus servers with identical
190 configuration, otherwise pint checks might return unreliable results and potential
191 false positives.
192- `headers` - a list of HTTP headers that will be set on all requests for this Prometheus
193 server.
194- `timeout` - timeout to be used for API requests. Defaults to 2 minutes.
195- `concurrency` - how many concurrent requests can pint send to this Prometheus server.
196 Optional, defaults to 16.
197- `rateLimit` - per second rate limit for all API requests send to this Prometheus server.
198 Setting it to `1000` would allow for up to 1000 requests per each wall clock second.
199 Optional, default to 100 requests per second.
200- `cache` - size of the query cache, defaults to 10000.
201- `required` - decides how pint will report errors if it's unable to get a valid response
202 from this Prometheus server. If `required` is `true` and all API calls to this Prometheus
203 fail pint will report those as `bug` level problem. If it's set to `false` pint will
204 report those with `warning` level.
205 Default value for `required` is `false`. Set it to `true` if you want to hard fail
206 in case of remote Prometheus issues. Note that setting it to `true` might block
207 PRs when running `pint ci` until pint is able to talk to Prometheus again.
208- `include` - optional path filter, if specified only paths matching one of listed regexp
209 patterns will use this Prometheus server for checks.
210- `exclude` - optional path filter, if specified any path matching one of listed regexp
211 patterns will never use this Prometheus server for checks.
212 `exclude` takes precedence over `include.
213
214Example:
215
216```js
217prometheus "prod" {
218 uri = "https://prometheus-prod.example.com"
219 headers = {
220 "X-Auth": "secret"
221 }
222 concurrency = 40
223}
224
225prometheus "dev" {
226 uri = "https://prometheus-dev.example.com"
227 timeout = "30s"
228 include = [ "alerts/test/.*" ]
229 exclude = [ "alerts/test/docs/.*" ]
230}
231```
232
233## Matching rules to checks
234
235Most checks, except basic syntax verification, requires some configuration to decide
236which checks to run against which files and rules.
237
238Syntax:
239
240```js
241rule {
242 match {
243 path = "(.+)"
244 name = "(.+)"
245 kind = "alerting|recording"
246 command = "ci|lint|watch"
247 annotation "(.*)" {
248 value = "(.*)"
249 }
250 label "(.*)" {
251 value = "(.*)"
252 }
253 for = "..."
254 }
255 match { ... }
256 match { ... }
257 ignore {
258 path = "(.+)"
259 name = "(.+)"
260 kind = "alerting|recording"
261 command = "ci|lint|watch"
262 annotation "(.*)" {
263 value = "(.*)"
264 }
265 label "(.*)" {
266 value = "(.*)"
267 }
268 for = "..."
269 }
270 ignore { ... }
271 ignore { ... }
272
273 [ check definition ]
274 ...
275 [ check definition ]
276}
277```
278
279- `match:path` - only files matching this pattern will be checked by this rule
280- `match:name` - only rules with names (`record` for recording rules and `alert` for alerting
281 rules) matching this pattern will be checked rule
282- `match:kind` - optional rule type filter, only rule of this type will be checked
283- `match:command` - optional command type filter, this allows to include or ignore rules
284 based on the command pint is run with `pint ci`, `pint lint` or `pint watch`.
285- `match:annotation` - optional annotation filter, only alert rules with at least one
286 annotation matching this pattern will be checked by this rule.
287- `match:label` - optional annotation filter, only rules with at least one label
288 matching this pattern will be checked by this rule. For recording rules only static
289 labels set on the recording rule are considered.
290- `match:for` - optional alerting rule `for` filter. If set only alerting rules with `for`
291 field present and matching provided value will be checked by this rule. Recording rules
292 will never match it as they don't have `for` field.
293 Syntax is `OP DURATION` where `OP` can be any of `=`, `!=`, `>`, `>=`, `<`, `<=`.
294- `ignore` - works exactly like `match` but does the opposite - any alerting or recording rule
295 matching all conditions defined on `ignore` will not be checked by this `rule` block.
296
297Note: both `match` and `ignore` require all defined filters to be satisfied to work.
298If multiple `match` and/or `ignore` rules are present any of them needs to match for the rule to
299be matched / ignored.
300
301Examples:
302
303```js
304rule {
305 match {
306 path = "rules/.*"
307 kind = "alerting"
308 label "severity" {
309 value = "(warning|critical)"
310 }
311 }
312 ignore {
313 command = "watch"
314 }
315 [ check applied only to severity="critical" and severity="warning" alerts in "ci" or "lint" command is run ]
316}
317```
318
319```js
320rule {
321 ignore {
322 command = "watch"
323 }
324 ignore {
325 command = "lint"
326 }
327 [ check applied unless "watch" or "lint" command is run ]
328}
329```
330
331```js
332rule {
333 match {
334 for = ">= 5m"
335 }
336 [ check applied only to alerting rules with "for" field value that is >= 5m ]
337}
338```
339