diff --git a/docs/configuration.md b/docs/configuration.md index 5aaa5668..034b50dc 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -16,8 +16,8 @@ nav_order: 2 ## Environment variables -Environment variables can be expanded inside pint configuration file as `ENV_*` HCL -variables. To use a variable named `FOO` reference it as `${ENV_FOO}`. +Environment variables can be expanded inside the pint configuration file as `ENV_*` HCL +variables. To use a variable named `FOO`, reference it as `${ENV_FOO}`. Examples: @@ -68,7 +68,7 @@ parser { } ``` -- `relaxed` - by default pint will now parse all files in strict mode, where +- `relaxed` - by default, pint will now parse all files in strict mode, where all rule files must have the exact syntax Prometheus expects: ```yaml @@ -103,7 +103,7 @@ owners { ``` - `allowed` - list of allowed owner names, this option accepts regexp rules. - When set all owners set via comments must much at least one entry on this list. + When set, all owners set via comments must match at least one entry on this list. If there's no `owners:allowed` configuration block, or if it's empty, then any owner name is accepted. @@ -127,11 +127,11 @@ ci { matching those regexp rules will be checked, other modified files will be ignored. - `exclude` - list of file patterns to ignore when running checks. This option takes precedence over `include`, so if a file path matches both - `include` & `exclude` patterns it will be excluded. -- `maxCommits` - by default pint will try to find all commits on the current branch, + `include` & `exclude` patterns, it will be excluded. +- `maxCommits` - by default, pint will try to find all commits on the current branch, this requires full git history to be present, if we have a shallow clone this might fail to find only current branch commits and give us a huge list. - If the number of commits returned by branch discovery is more than `maxCommits` + If the number of commits returned by branch discovery is more than `maxCommits`, then pint will fail to run. - `baseBranch` - base branch to compare `HEAD` commit with when calculating the list of commits to check. @@ -148,9 +148,9 @@ to be set. It should contain a personal access token used to authenticate with t **NOTE**: GitHub integration requires `GITHUB_AUTH_TOKEN` environment variable to be set to a personal access key that can access your repository. -**NOTE** Pull request number must be known to pint so it can add comments if it detects any problems. -If pint is run as part of GitHub actions workflow then this number will be detected from `GITHUB_REF` -environment variable. For other use cases `GITHUB_PULL_REQUEST_NUMBER` environment variable must be set +**NOTE** The pull request number must be known to pint so it can add comments if it detects any problems. +If pint is run as part of GitHub actions workflow, then this number will be detected from `GITHUB_REF` +environment variable. For other use cases, the `GITHUB_PULL_REQUEST_NUMBER` environment variable must be set with the pull request number. Syntax: @@ -185,17 +185,17 @@ repository { ``` - `github:baseuri` - base URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API. - If not set `pint` will try to use `GITHUB_API_URL` environment variable instead (if set). + If not set, `pint` will try to use the `GITHUB_API_URL` environment variable instead (if set). - `github:uploaduri` - upload URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API. - If not set `pint` will try to use `GITHUB_API_URL` environment variable instead (if set). + If not set, `pint` will try to use the `GITHUB_API_URL` environment variable instead (if set). -If `github:baseuri` _or_ `github:uploaduri` are not specified then [GitHub](https://github.com) will be used. +If `github:baseuri` _or_ `github:uploaduri` are not specified, then [GitHub](https://github.com) will be used. - `github:timeout` - timeout to be used for API requests, defaults to 1 minute. - `github:owner` - name of the GitHub owner i.e. the first part that comes before the repository's name in the URI. - If not set `pint` will try to use `GITHUB_REPOSITORY` environment variable instead (if set). + If not set, `pint` will try to use the `GITHUB_REPOSITORY` environment variable instead (if set). - `github:repo` - name of the GitHub repository (e.g. `monitoring`). - If not set `pint` will try to use `GITHUB_REPOSITORY` environment variable instead (if set). + If not set, `pint` will try to use the `GITHUB_REPOSITORY` environment variable instead (if set). Most GitHub settings can be detected from environment variables that are set inside GitHub Actions environment. The only exception is `GITHUB_AUTH_TOKEN` environment variable that must be set @@ -204,7 +204,7 @@ manually. ## Prometheus servers Some checks work by querying a running Prometheus instance to verify if -metrics used in rules are present. If you want to use those checks then you +metrics used in rules are present. If you want to use those checks, then you first need to define one or more Prometheus servers. Syntax: @@ -237,11 +237,11 @@ prometheus "$name" { - `uri` - base URI of this Prometheus server, used for API requests and queries. - `publicURI` - optional URI to use instead of `uri` in problems reported to users. Set it if Prometheus links used by pint in comments submitted to BitBucket or GitHub - should use different URIs then the one used by pint when querying Prometheus. - If not set `uri` will be used instead. + should use different URIs than the one used by pint when querying Prometheus. + If not set, `uri` will be used instead. - `failover` - list of URIs to try (in order they are specified) if `uri` doesn't respond - to requests or returns an error. This allows to configure fail-over Prometheus servers - to avoid CI failures in case main Prometheus server is unreachable. + to requests or returns an error. This allows one to configure fail-over Prometheus servers + to avoid CI failures in case the main Prometheus server is unreachable. Fail over URIs are not used if Prometheus returns an error caused by the query, like `many-to-many matching not allowed`. It's highly recommended that all URIs point to Prometheus servers with identical @@ -253,9 +253,9 @@ prometheus "$name" { - `headers` - a list of HTTP headers that will be set on all requests for this Prometheus server. - `timeout` - timeout to be used for API requests. Defaults to 2 minutes. -- `concurrency` - how many concurrent requests can pint send to this Prometheus server. +- `concurrency` - how many concurrent requests pint can send to this Prometheus server. Optional, defaults to 16. -- `rateLimit` - per second rate limit for all API requests send to this Prometheus server. +- `rateLimit` - per second rate limit for all API requests sent to this Prometheus server. Setting it to `1000` would allow for up to 1000 requests per each wall clock second. Optional, default to 100 requests per second. - `uptime` - metric selector used to detect gaps in Prometheus uptime. @@ -267,16 +267,16 @@ prometheus "$name" { for details. Uptime gap detection works by running a range query `count(up)` and checking for any gaps in the response. - Since `up` metric can have a lot of time series `count(up)` might be slow and expensive. + Since the `up` metric can have a lot of time series, `count(up)` might be slow and expensive. An alternative is to use one of metrics exposed by Prometheus itself, like `prometheus_build_info`, but those metrics are only present if Prometheus is configured to scrape itself, so `up` is used by default since it's guaranteed to work in every setup. - If your Prometheus has a lot of time series and it's configured to scrape itself then - it is recommended to set `uptime` field to `prometheus_build_info`. + If your Prometheus has a lot of time series and it's configured to scrape itself, then + it is recommended to set the `uptime` field to `prometheus_build_info`. - `required` - decides how pint will report errors if it's unable to get a valid response from this Prometheus server. If `required` is `true` and all API calls to this Prometheus - fail pint will report those as `bug` level problem. If it's set to `false` pint will - report those with `warning` level. + fail, pint will report those as `bug` level problems. If it's set to `false`, pint will + report those with the `warning` level. Default value for `required` is `false`. Set it to `true` if you want to hard fail in case of remote Prometheus issues. Note that setting it to `true` might block PRs when running `pint ci` until pint is able to talk to Prometheus again. @@ -289,11 +289,11 @@ prometheus "$name" { - `tls:serverName` - server name (SNI) for TLS handshakes. Optional, default is unset. - `tls:caCert` - path for CA certificate to use. Optional, default is unset. - `tls:clientCert` - path for client certificate to use. Optional, default is unset. - If set `clientKey` must also be set. + If set, `clientKey` must also be set. - `tls:clientKey` - path for client key file to use. Optional, default is unset. - If set `clientCert` must also be set. + If set, `clientCert` must also be set. - `tls:skipVerify` - if `true` all TLS certificate checks will be skipped. - Enabling this option can be a security risk, use only for testing. + Enabling this option can be a security risk; use only for testing. Optional, default is false. Example: @@ -341,7 +341,7 @@ instances is needed. This can be configured using `discovery` config blocks. ### File path discovery File path discovery allows to generate Prometheus server definitions used by pint -based on path patters on disk. +based on path patterns on disk. Syntax: ```js @@ -356,7 +356,7 @@ filepath { - `directory` - the base directory to scan for paths. - `match` - a regexp expression to match. Any named capture group defined here - will be accessible when rendering Prometheus template. + will be accessible when rendering Prometheus the template. - `ignore` - a list of regexp rules, any path matching any of these rules will be ignored. - `template` - a template for generating Prometheus server definitions. @@ -381,7 +381,7 @@ prometheusQuery { } ``` -- `uri` - Prometheus server base URI. This is when discovery query will be send. +- `uri` - Prometheus server base URI. This is where the discovery query will be sent. - `headers` - optional list of headers to set on Prometheus query requests. - `timeout` - Prometheus request timeout. Defaults to 2 minutes. - `tls` - optional TLS configuration for Prometheus requests, see `prometheus` block @@ -391,12 +391,12 @@ prometheusQuery { `template` definition. You can set multiple `template` blocks for each discovery block, each returned time series will generate a single Prometheus server for each `template` block. You can use labels on returned time series as [Go text/template](https://pkg.go.dev/text/template) - variables named `$name`. Example: `instance` label will be available as `$instance` variable. + variables named `$name`. Example: `instance` label will be available as the `$instance` variable. ### Prometheus template -`template` block is nearly identical to `prometheus` configuration block, except that -the `name` is explicit field inside the block. +The `template` block is nearly identical to the `prometheus` configuration block, except that +`name` is an explicit field inside the block. You can use [Go text/template](https://pkg.go.dev/text/template) to render some of the fields using variables from either regexp capture groups (when using `filepath` discovery) @@ -443,7 +443,7 @@ Servers must have identical `name`, `tags`, `include` and `exclude` fields to be ### Examples Each Prometheus server has a sub-directory inside `/etc/prometheus/clusters` -folder. This directory is named after Prometheus cluster it's part of. +folder. This directory is named after the Prometheus cluster it's part of. All rules are stored in `/etc/prometheus/clusters//.*.yaml` or `/etc/prometheus/clusters//.*.yml` files. Each Prometheus cluster is accessible under `https://.prometheus.example.com` URI. @@ -521,9 +521,9 @@ rule { - `match:label` - optional annotation filter, only rules with at least one label matching this pattern will be checked by this rule. For recording rules only static labels set on the recording rule are considered. -- `match:for` - optional alerting rule `for` filter. If set only alerting rules with `for` - field present and matching provided value will be checked by this rule. Recording rules - will never match it as they don't have `for` field. +- `match:for` - optional alerting rule `for` filter. If set, only alerting rules with the `for` + field present and matching the provided value will be checked by this rule. Recording rules + will never match it as they don't have the `for` field. Syntax is `OP DURATION` where `OP` can be any of `=`, `!=`, `>`, `>=`, `<`, `<=`. - `match:keep_firing_for` - optional alerting rule `keep_firing_for` filter. Works the same way as `for` match filter. diff --git a/docs/index.md b/docs/index.md index dbd7bb5b..2813bb80 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,7 +30,7 @@ Checks might use various Prometheus extra information, for example Prometheus configuration or metrics metadata. If you run pint against a different service, like [Thanos](https://thanos.io/) some checks might return problems due to API call errors, since not all Prometheus HTTP APIs are supported by it. -In that case you might want to disable failing checks in pint configuration file. +In that case, you might want to disable failing checks in the pint configuration file. ## Usage @@ -171,12 +171,12 @@ Available metrics: - `pint_problem` - exported for every problem detected by pint. To avoid exposing too many metrics at once pass `--max-problems` flag to watch command. - When this flag is set pint will expose only up to `--max-problems` value number of + When this flag is set, pint will expose only up to `--max-problems` value number of `pint_problem` metrics. - `pint_problems` - this metric is the total number of all problems detected by pint, including those not exported due to the `--max-problems` flag. -`pint problem` metric can include `owner` label for each rule. This is useful +The `pint problem` metric can include the `owner` label for each rule. This is useful to route alerts based on metrics to the right team. To set a rule owner add a `# pint file/owner $owner` comment in a file, to set an owner for all rules in that file. You can also set an owner per rule, by adding @@ -222,7 +222,7 @@ There is a number of comments you can add to your rule files in order to change pint behaviour, some of them allow you to exclude selected files or line, see [docs here](./ignoring.md) for details. -There are a few requirement for any comment to be recognized by pint: +There are a few requirements for any comment to be recognized by pint: - All comments must have a `pint` prefix. - All comments must have at least one space between `#` symbol and `pint` prefix. @@ -272,7 +272,7 @@ Steps: ./pint lint /etc/prometheus/*.rules.yml ``` -3. Configuration file is optional, but without it pint will only run very basic +3. Configuration file is optional, but without it, pint will only run very basic syntax checks. See [configuration](configuration.md) for details on config syntax. By default pint will try to load configuration from `.pint.hcl`, you can