prometheus/nginx_exporter
1
0
Fork 0
mirror of https://github.com/nginxinc/nginx-prometheus-exporter.git synced 2025-04-18 12:45:02 +03:00
Code

Add linting for markdown files (#465)

Browse Source
This commit is contained in:
Luca Comellini 2023-07-25 17:31:34 -07:00 committed by GitHub
parent 603d18dd33
commit 069c9d190c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 410 additions and 207 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@ -9,6 +9,7 @@ A clear and concise description of what the bug is.
**To reproduce**
Steps to reproduce the behavior:
1. Deploy using 'some_command'
2. View logs '....'
3. See error
@ -17,10 +18,11 @@ Steps to reproduce the behavior:
A clear and concise description of what you expected to happen.
**Your environment**
* Version of the Prometheus exporter - release version or a specific commit
* Version of Docker/Kubernetes
* [if applicable] Kubernetes platform (e.g. Mini-kube or GCP)
* Using NGINX or NGINX Plus
- Version of the Prometheus exporter - release version or a specific commit
- Version of Docker/Kubernetes
- [if applicable] Kubernetes platform (e.g. Mini-kube or GCP)
- Using NGINX or NGINX Plus
**Additional context**
Add any other context about the problem here. Any log files you want to share.

8
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@ -1,10 +1,14 @@
### Proposed changes
Describe the use case and detail of the change. If this PR addresses an issue on GitHub, make sure to include a link to that issue here in this description (not in the title of the PR).
Describe the use case and detail of the change. If this PR addresses an issue on GitHub, make sure to include a link to
that issue here in this description (not in the title of the PR).
### Checklist
Before creating a PR, run through this checklist and mark each as complete.
- [ ] I have read the [CONTRIBUTING](https://github.com/nginxinc/nginx-prometheus-exporter/blob/main/CONTRIBUTING.md) guide
- [ ] I have read the [CONTRIBUTING](https://github.com/nginxinc/nginx-prometheus-exporter/blob/main/CONTRIBUTING.md)
guide
- [ ] I have proven my fix is effective or that my feature works
- [ ] I have checked that all unit tests pass after adding my changes
- [ ] I have ensured the README is up to date

18
.markdownlint-cli2.yaml Normal file
View File

@ -0,0 +1,18 @@
# Rule configuration.
# For rule descriptions and how to fix: https://github.com/DavidAnson/markdownlint/tree/main#rules--aliases
config:
ul-style:
style: dash
no-duplicate-heading:
siblings_only: true
line-length:
line_length: 120
code_blocks: false
tables: false
# Define glob expressions to ignore
ignores:
- ".github/"
# Fix any fixable errors
fix: true

8
.pre-commit-config.yaml
View File

@ -24,6 +24,7 @@ repos:
- id: no-commit-to-branch
- id: requirements-txt-fixer
- id: fix-byte-order-marker
- repo: local
hooks:
- id: golang-diff
@ -32,15 +33,22 @@ repos:
language: system
types: [go]
pass_filenames: false
- repo: https://github.com/golangci/golangci-lint
rev: v1.53.3
hooks:
- id: golangci-lint
args: [--new-from-patch=/tmp/diff.patch]
- repo: https://github.com/gitleaks/gitleaks
rev: v8.17.0
hooks:
- id: gitleaks
- repo: https://github.com/DavidAnson/markdownlint-cli2
rev: v0.8.1
hooks:
- id: markdownlint-cli2
ci:
skip: [golang-diff, golangci-lint]

198
CHANGELOG.md
View File

@ -1,156 +1,202 @@
# Changelog
### 0.11.0
## 0.11.0
A list of changes can be found on Github at: [Release v0.11.0](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.11.0)
### 0.10.0
## 0.10.0
A list of changes can be found on Github at: [Release v0.10.0](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.10.0)
### 0.9.0
## 0.9.0
A list of changes can be found on Github at: [Release v0.9.0](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.9.0)
### 0.8.0
## 0.8.0
CHANGES:
* [103](https://github.com/nginxinc/nginx-prometheus-exporter/pull/103): Switch to `gcr.io/distroless/static` image. Use a non-root user to run the exporter process by default. Thanks to [Alex SZAKALY](https://github.com/alex1989hu).
* Update Go version to 1.14
BUGFIXES:
* [99](https://github.com/nginxinc/nginx-prometheus-exporter/pull/99): Fix link to metrics path. Thanks to [Yoan Blanc](https://github.com/greut).
* [101](https://github.com/nginxinc/nginx-prometheus-exporter/pull/101): docs: fix dockerfile link. Thanks to [Eric Carboni](https://github.com/eric-hc).
- [103](https://github.com/nginxinc/nginx-prometheus-exporter/pull/103): Switch to `gcr.io/distroless/static` image. Use
a non-root user to run the exporter process by default. Thanks to [Alex SZAKALY](https://github.com/alex1989hu).
- Update Go version to 1.14
FIXES:
- [99](https://github.com/nginxinc/nginx-prometheus-exporter/pull/99): Fix link to metrics path. Thanks to [Yoan Blanc](https://github.com/greut).
- [101](https://github.com/nginxinc/nginx-prometheus-exporter/pull/101): docs: fix dockerfile link. Thanks to [Eric Carboni](https://github.com/eric-hc).
UPGRADE:
* Use the 0.8.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.8.0`
* Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.8.0).
- Use the 0.8.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.8.0`
- Download the latest binaries from [GitHub releases
page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.8.0).
COMPATIBILITY:
* NGINX 0.1.18 or newer.
* NGINX Plus R19 or newer.
### 0.7.0
- NGINX 0.1.18 or newer.
- NGINX Plus R19 or newer.
## 0.7.0
FEATURES:
* [86](https://github.com/nginxinc/nginx-prometheus-exporter/pull/86): Implemented TLS client certificate authentication. Thanks to [Fabian Lüpke](https://github.com/Fluepke).
BUGFIXES:
* [96](https://github.com/nginxinc/nginx-prometheus-exporter/pull/96): Add const labels to upMetric. Thanks to [Robert Toth](https://github.com/robert-toth).
- [86](https://github.com/nginxinc/nginx-prometheus-exporter/pull/86): Implemented TLS client certificate
authentication. Thanks to [Fabian Lüpke](https://github.com/Fluepke).
FIXES:
- [96](https://github.com/nginxinc/nginx-prometheus-exporter/pull/96): Add const labels to upMetric. Thanks to [Robert
Toth](https://github.com/robert-toth).
UPGRADE:
* Use the 0.7.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.7.0`
* Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.7.0).
- Use the 0.7.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.7.0`
- Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.7.0).
COMPATIBILITY:
* NGINX 0.1.18 or newer.
* NGINX Plus R19 or newer.
### 0.6.0
- NGINX 0.1.18 or newer.
- NGINX Plus R19 or newer.
## 0.6.0
FEATURES:
* [77](https://github.com/nginxinc/nginx-prometheus-exporter/pull/77): Add constLabels support via cli arg/env variable.
- [77](https://github.com/nginxinc/nginx-prometheus-exporter/pull/77): Add constLabels support via cli arg/env variable.
CHANGES:
* Update alpine image.
- Update alpine image.
UPGRADE:
* Use the 0.6.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.6.0`
* Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.6.0).
- Use the 0.6.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.6.0`
- Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.6.0).
COMPATIBILITY:
* NGINX 0.1.18 or newer.
* NGINX Plus R19 or newer.
### 0.5.0
- NGINX 0.1.18 or newer.
- NGINX Plus R19 or newer.
## 0.5.0
FEATURES:
* [70](https://github.com/nginxinc/nginx-prometheus-exporter/pull/70): Set user agent on scrape requests to nginx.
* [68](https://github.com/nginxinc/nginx-prometheus-exporter/pull/68): Add ability to scrape and listen on unix domain sockets.
* [64](https://github.com/nginxinc/nginx-prometheus-exporter/pull/64): Add location zone and resolver metric support.
BUGFIXES:
* [73](https://github.com/nginxinc/nginx-prometheus-exporter/pull/73): Fix typo in stream_zone_sync_status_nodes_online metric description.
* [71](https://github.com/nginxinc/nginx-prometheus-exporter/pull/71): Do not assume default datasource in Grafana panels.
* [62](https://github.com/nginxinc/nginx-prometheus-exporter/pull/62): Set correct nginx_up query and instance variable expression.
- [70](https://github.com/nginxinc/nginx-prometheus-exporter/pull/70): Set user agent on scrape requests to nginx.
- [68](https://github.com/nginxinc/nginx-prometheus-exporter/pull/68): Add ability to scrape and listen on unix domain
sockets.
- [64](https://github.com/nginxinc/nginx-prometheus-exporter/pull/64): Add location zone and resolver metric support.
FIXES:
- [73](https://github.com/nginxinc/nginx-prometheus-exporter/pull/73): Fix typo in stream_zone_sync_status_nodes_online
metric description.
- [71](https://github.com/nginxinc/nginx-prometheus-exporter/pull/71): Do not assume default datasource in Grafana
panels.
- [62](https://github.com/nginxinc/nginx-prometheus-exporter/pull/62): Set correct nginx_up query and instance variable
expression.
UPGRADE:
* Use the 0.5.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.5.0`
* Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.5.0).
- Use the 0.5.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.5.0`
- Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.5.0).
COMPATIBILITY:
* NGINX 0.1.18 or newer.
* NGINX Plus R19 or newer.
### 0.4.2
- NGINX 0.1.18 or newer.
- NGINX Plus R19 or newer.
BUGFIXES:
* [60](https://github.com/nginxinc/nginx-prometheus-exporter/pull/60): *Fix session metrics for stream server zones*. Session metrics with a status of `4xx` or `5xx` are now correctly reported. Previously they were always reported as `0`.
## 0.4.2
FIXES:
- [60](https://github.com/nginxinc/nginx-prometheus-exporter/pull/60): *Fix session metrics for stream server zones*.
Session metrics with a status of `4xx` or `5xx` are now correctly reported. Previously they were always reported as
`0`.
UPGRADE:
* Use the 0.4.2 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.4.2`
* Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.4.2).
- Use the 0.4.2 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.4.2`
- Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.4.2).
COMPATIBILITY:
* NGINX 0.1.18 or newer.
* NGINX Plus R18 or newer.
### 0.4.1
- NGINX 0.1.18 or newer.
- NGINX Plus R18 or newer.
BUGFIXES:
* [55](https://github.com/nginxinc/nginx-prometheus-exporter/pull/55): Do not export zone sync metrics if they are not reported by NGINX Plus. Previously, in such case, the metrics were exported with zero values.
## 0.4.1
FIXES:
- [55](https://github.com/nginxinc/nginx-prometheus-exporter/pull/55): Do not export zone sync metrics if they are not
reported by NGINX Plus. Previously, in such case, the metrics were exported with zero values.
UPGRADE:
* Use the 0.4.1 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.4.1`
* Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.4.1).
- Use the 0.4.1 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.4.1`
- Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.4.1).
COMPATIBILITY:
* NGINX 0.1.18 or newer.
* NGINX Plus R18 or newer.
### 0.4.0
- NGINX 0.1.18 or newer.
- NGINX Plus R18 or newer.
## 0.4.0
FEATURES:
* [50](https://github.com/nginxinc/nginx-prometheus-exporter/pull/50): Add zone sync metrics support.
* [37](https://github.com/nginxinc/nginx-prometheus-exporter/pull/37): Implement a way to retry connection to NGINX if it is unreachable. Add -nginx.retries for setting the number of retries and -nginx.retry-interval for setting the interval between retries, both as cli-arguments.
- [50](https://github.com/nginxinc/nginx-prometheus-exporter/pull/50): Add zone sync metrics support.
- [37](https://github.com/nginxinc/nginx-prometheus-exporter/pull/37): Implement a way to retry connection to NGINX if
it is unreachable. Add -nginx.retries for setting the number of retries and -nginx.retry-interval for setting the
interval between retries, both as cli-arguments.
UPGRADE:
* Use the 0.4.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.4.0`
* Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.4.0).
- Use the 0.4.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.4.0`
- Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.4.0).
COMPATIBILITY:
* NGINX 0.1.18 or newer.
* NGINX Plus R18 or newer.
### 0.3.0
- NGINX 0.1.18 or newer.
- NGINX Plus R18 or newer.
## 0.3.0
FEATURES:
* [32](https://github.com/nginxinc/nginx-prometheus-exporter/pull/32): Add nginxexporter_build_info metric.
* [31](https://github.com/nginxinc/nginx-prometheus-exporter/pull/31): Implement nginx_up and nginxplus_up metrics. Add -nginx.timeout cli argument for setting a timeout for scrapping metrics from NGINX or NGINX Plus.
- [32](https://github.com/nginxinc/nginx-prometheus-exporter/pull/32): Add nginxexporter_build_info metric.
- [31](https://github.com/nginxinc/nginx-prometheus-exporter/pull/31): Implement nginx_up and nginxplus_up metrics. Add
-nginx.timeout cli argument for setting a timeout for scrapping metrics from NGINX or NGINX Plus.
UPGRADE:
* Use the 0.3.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.3.0`
* Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.3.0).
- Use the 0.3.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.3.0`
- Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.3.0).
COMPATIBILITY:
* NGINX 0.1.18 or newer.
* NGINX Plus R14 or newer.
- NGINX 0.1.18 or newer.
- NGINX Plus R14 or newer.
## 0.2.0
FEATURES:
* [16](https://github.com/nginxinc/nginx-prometheus-exporter/pull/16): Add stream metrics support.
* [13](https://github.com/nginxinc/nginx-prometheus-exporter/pull/13): Add a flag for controlling SSL verification of NGINX stub_status/API endpoint. Thanks to [Raza Jhaveri](https://github.com/razaj92).
* [3](https://github.com/nginxinc/nginx-prometheus-exporter/pull/3): Support for environment variables.
- [16](https://github.com/nginxinc/nginx-prometheus-exporter/pull/16): Add stream metrics support.
- [13](https://github.com/nginxinc/nginx-prometheus-exporter/pull/13): Add a flag for controlling SSL verification of
NGINX stub_status/API endpoint. Thanks to [Raza Jhaveri](https://github.com/razaj92).
- [3](https://github.com/nginxinc/nginx-prometheus-exporter/pull/3): Support for environment variables.
UPGRADE:
* Use the 0.2.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.2.0`
* Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.2.0).
- Use the 0.2.0 image from our DockerHub: `nginx/nginx-prometheus-exporter:0.2.0`
- Download the latest binaries from [GitHub releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases/tag/v0.2.0).
COMPATIBILITY:
* NGINX 0.1.18 or newer.
* NGINX Plus R14 or newer.
- NGINX 0.1.18 or newer.
- NGINX Plus R14 or newer.
## 0.1.0
* Initial release.
- Initial release.

24
CODE_OF_CONDUCT.md
View File

@ -16,21 +16,21 @@ appearance, race, religion, or sexual identity and orientation.
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or
- The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
- Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
- Other conduct which could reasonably be considered inappropriate in a
professional setting
## Our Responsibilities
@ -57,7 +57,7 @@ further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at integrations@nginx.com. All
reported by contacting the project team at <integrations@nginx.com>. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
@ -70,6 +70,6 @@ members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
[homepage]: https://www.contributor-covenant.org

58
CONTRIBUTING.md
View File

@ -1,8 +1,9 @@
# Contributing Guidelines
The following is a set of guidelines for contributing to the NGINX Prometheus Exporter. We really appreciate that you are considering contributing!
The following is a set of guidelines for contributing to the NGINX Prometheus Exporter. We really appreciate that you
are considering contributing!
#### Table Of Contents
## Table Of Contents
[Ask a Question](#ask-a-question)
@ -11,8 +12,9 @@ The following is a set of guidelines for contributing to the NGINX Prometheus Ex
[Contributing](#contributing)
[Style Guides](#style-guides)
* [Git Style Guide](#git-style-guide)
* [Go Style Guide](#go-style-guide)
- [Git Style Guide](#git-style-guide)
- [Go Style Guide](#go-style-guide)
[Code of Conduct](CODE_OF_CONDUCT.md)
@ -30,47 +32,57 @@ Follow our [Getting Started Guide](README.md#getting-started) to get the NGINX P
### Project Structure
* This Prometheus Exporter is written in Go and supports both the open source NGINX software and NGINX Plus.
* We use [Go modules](https://github.com/golang/go/wiki/Modules) for managing dependencies.
- This Prometheus Exporter is written in Go and supports both the open source NGINX software and NGINX Plus.
- We use [Go modules](https://github.com/golang/go/wiki/Modules) for managing dependencies.
## Contributing
### Report a Bug
To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please ensure the issue has not already been reported.
To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please
ensure the issue has not already been reported.
### Suggest an Enhancement
To suggest an enhancement, please create an issue on GitHub with the label `enhancement` using the available feature issue template.
To suggest an enhancement, please create an issue on GitHub with the label `enhancement` using the available feature
issue template.
### Open a Pull Request
* Fork the repo, create a branch, submit a PR when your changes are tested and ready for review
* Fill in [our pull request template](.github/PULL_REQUEST_TEMPLATE.md)
- Fork the repo, create a branch, submit a PR when your changes are tested and ready for review
- Fill in [our pull request template](.github/PULL_REQUEST_TEMPLATE.md)
> **Note**
>
> If you’d like to implement a new feature, please consider creating a feature request issue first to start a discussion about the feature.
> If you’d like to implement a new feature, please consider creating a feature request issue first to start a discussion
> about the feature.
### Issue lifecycle
* When an issue or PR is created, it will be triaged by the core development team and assigned a label to indicate the type of issue it is (bug, feature request, etc) and to determine the milestone. Please see the [Issue Lifecycle](ISSUE_LIFECYCLE.md) document for more information.
- When an issue or PR is created, it will be triaged by the core development team and assigned a label to indicate the
type of issue it is (bug, feature request, etc) and to determine the milestone. Please see the [Issue
Lifecycle](ISSUE_LIFECYCLE.md) document for more information.
## Style Guides
### Git Style Guide
* Keep a clean, concise and meaningful git commit history on your branch, rebasing locally and squashing before submitting a PR
* Follow the guidelines of writing a good commit message as described here https://chris.beams.io/posts/git-commit/ and summarized in the next few points
* In the subject line, use the present tense ("Add feature" not "Added feature")
* In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
* Limit the subject line to 72 characters or less
* Reference issues and pull requests liberally after the subject line
* Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in your text editor to write a good message instead of `git commit -am`)
- Keep a clean, concise and meaningful git commit history on your branch, rebasing locally and squashing before
submitting a PR
- Follow the guidelines of writing a good commit message as described here <https://chris.beams.io/posts/git-commit/>
and summarized in the next few points
- In the subject line, use the present tense ("Add feature" not "Added feature")
- In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- Limit the subject line to 72 characters or less
- Reference issues and pull requests liberally after the subject line
- Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in
your text editor to write a good message instead of `git commit -am`)
### Go Style Guide
* Run `gofmt` over your code to automatically resolve a lot of style issues. Most editors support this running automatically when saving a code file.
* Run `go lint` and `go vet` on your code too to catch any other issues.
* Follow this guide on some good practice and idioms for Go - https://github.com/golang/go/wiki/CodeReviewComments
* To check for extra issues, install [golangci-lint](https://github.com/golangci/golangci-lint) and run `make lint` or `golangci-lint run`
- Run `gofmt` over your code to automatically resolve a lot of style issues. Most editors support this running
automatically when saving a code file.
- Run `go lint` and `go vet` on your code too to catch any other issues.
- Follow this guide on some good practice and idioms for Go - <https://github.com/golang/go/wiki/CodeReviewComments>
- To check for extra issues, install [golangci-lint](https://github.com/golangci/golangci-lint) and run `make lint` or
`golangci-lint run`

46
ISSUE_LIFECYCLE.md
View File

@ -1,36 +1,52 @@
# Issue Lifecycle
To ensure a balance between work carried out by the NGINX engineering team while encouraging community involvement on this project, we use the following issue lifecycle. (Note: The issue *creator* refers to the community member that created the issue. The issue *owner* refers to the NGINX team member that is responsible for managing the issue lifecycle.)
To ensure a balance between work carried out by the NGINX engineering team while encouraging community involvement on
this project, we use the following issue lifecycle. (Note: The issue *creator* refers to the community member that
created the issue. The issue *owner* refers to the NGINX team member that is responsible for managing the issue
lifecycle.)
1. New issue created by community member.
2. Assign issue owner: All new issues are assigned an owner on the NGINX engineering team. This owner shepherds the
issue through the subsequent stages in the issue lifecycle.
2. Assign issue owner: All new issues are assigned an owner on the NGINX engineering team. This owner shepherds the issue through the subsequent stages in the issue lifecycle.
3. Determine issue type: This is done with automation where possible, and manually by the owner where necessary. The
associated label is applied to the issue.
Possible Issue Types:
3. Determine issue type: This is done with automation where possible, and manually by the owner where necessary. The associated label is applied to the issue.
#### Possible Issue Types
`needs more info`: The owner should use the issue to request information from the creator. If we don't receive the needed information within 7 days, automation closes the issue.
- `needs more info`: The owner should use the issue to request information from the creator. If we don't receive the
needed information within 7 days, automation closes the issue.
`bug`: The implementation of a feature is not correct.
- `bug`: The implementation of a feature is not correct.
`proposal`: Request for a change. This can be a new feature, tackling technical debt, documentation changes, or improving existing features.
- `proposal`: Request for a change. This can be a new feature, tackling technical debt, documentation changes, or
improving existing features.
`question`: The owner converts the issue to a github discussion and engages the creator.
- `question`: The owner converts the issue to a github discussion and engages the creator.
4. Determine milestone: The owner, in collaboration with the wider team (PM & engineering), determines what milestone to
attach to an issue. Generally, milestones correspond to product releases - however there are two 'magic' milestones
with special meanings (not tied to a specific release):
4. Determine milestone: The owner, in collaboration with the wider team (PM & engineering), determines what milestone to attach to an issue. Generally, milestones correspond to product releases - however there are two 'magic' milestones with special meanings (not tied to a specific release):
- Issues assigned to backlog: Our team is in favour of implementing the feature request/fixing the issue, however the
implementation is not yet assigned to a concrete release. If and when a `backlog` issue aligns well with our
roadmap, it will be scheduled for a concrete iteration. We review and update our roadmap at least once every
quarter. The `backlog` list helps us shape our roadmap, but it is not the only source of input. Therefore, some
`backlog` items may eventually be closed as `out of scope`, or relabelled as `backlog candidate` once it becomes
clear that they do not align with our evolving roadmap.
- Issues assigned to backlog: Our team is in favour of implementing the feature request/fixing the issue, however the implementation is not yet assigned to a concrete release. If and when a `backlog` issue aligns well with our roadmap, it will be scheduled for a concrete iteration. We review and update our roadmap at least once every quarter. The `backlog` list helps us shape our roadmap, but it is not the only source of input. Therefore, some `backlog` items may eventually be closed as `out of scope`, or relabelled as `backlog candidate` once it becomes clear that they do not align with our evolving roadmap.
- Issues assigned to `backlog candidate`: Our team does not intend to implement the feature/fix request described in the issue and wants the community to weigh in before we make our final decision.
- Issues assigned to `backlog candidate`: Our team does not intend to implement the feature/fix request described in
the issue and wants the community to weigh in before we make our final decision.
`backlog` issues can be labeled by the owner as `help wanted` and/or `good first issue` as appropriate.
5. Promotion of `backlog candidate` issue to `backlog` issue: If an issue labelled `backlog candidate` receives more
than 30 upvotes within 60 days, we promote the issue by applying the `backlog` label. While issues promoted in this
manner have not been committed to a particular release, we welcome PRs from the community on them.
5. Promotion of `backlog candidate` issue to `backlog` issue: If an issue labelled `backlog candidate` receives more than 30 upvotes within 60 days, we promote the issue by applying the `backlog` label. While issues promoted in this manner have not been committed to a particular release, we welcome PRs from the community on them.
If an issue does not make our roadmap and has not been moved to a discussion, it is closed with the label `out of scope`. The goal is to get every issue in the issues list to one of the following end states:
If an issue does not make our roadmap and has not been moved to a discussion, it is closed with the label `out of
scope`. The goal is to get every issue in the issues list to one of the following end states:
- An assigned release.
- The `backlog` label.

201
README.md
View File

@ -1,4 +1,15 @@
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/nginxinc/nginx-prometheus-exporter/badge)](https://api.securityscorecards.dev/projects/github.com/nginxinc/nginx-prometheus-exporter) [![CI](https://github.com/nginxinc/nginx-prometheus-exporter/workflows/Continuous%20Integration/badge.svg)](https://github.com/nginxinc/nginx-prometheus-exporter/actions?query=workflow%3A%22Continuous+Integration%22) [![FOSSA Status](https://app.fossa.com/api/projects/custom%2B5618%2Fgithub.com%2Fnginxinc%2Fnginx-prometheus-exporter.svg?type=shield)](https://app.fossa.com/projects/custom%2B5618%2Fgithub.com%2Fnginxinc%2Fnginx-prometheus-exporter?ref=badge_shield) [![Go Report Card](https://goreportcard.com/badge/github.com/nginxinc/nginx-prometheus-exporter)](https://goreportcard.com/report/github.com/nginxinc/nginx-prometheus-exporter) ![GitHub all releases](https://img.shields.io/github/downloads/nginxinc/nginx-prometheus-exporter/total?logo=github) ![GitHub release (latest by SemVer)](https://img.shields.io/github/downloads/nginxinc/nginx-prometheus-exporter/latest/total?sort=semver&logo=github) [![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/nginxinc/nginx-prometheus-exporter?logo=github&sort=semver)](https://github.com/nginxinc/nginx-prometheus-exporter/releases/latest) ![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/nginxinc/nginx-prometheus-exporter?logo=go) [![Docker Pulls](https://img.shields.io/docker/pulls/nginx/nginx-prometheus-exporter?logo=docker&logoColor=white)](https://hub.docker.com/r/nginx/nginx-prometheus-exporter) ![Docker Image Size (latest semver)](https://img.shields.io/docker/image-size/nginx/nginx-prometheus-exporter?logo=docker&logoColor=white&sort=semver) [![Slack](https://img.shields.io/badge/slack-%23nginx--prometheus--exporter-green?logo=slack)](https://nginxcommunity.slack.com/channels/nginx-prometheus-exporter)
<!-- markdownlint-disable-next-line first-line-h1 -->
[![OpenSSFScorecard](https://api.securityscorecards.dev/projects/github.com/nginxinc/nginx-prometheus-exporter/badge)](https://api.securityscorecards.dev/projects/github.com/nginxinc/nginx-prometheus-exporter)
[![CI](https://github.com/nginxinc/nginx-prometheus-exporter/workflows/Continuous%20Integration/badge.svg)](https://github.com/nginxinc/nginx-prometheus-exporter/actions?query=workflow%3A%22Continuous+Integration%22)
[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B5618%2Fgithub.com%2Fnginxinc%2Fnginx-prometheus-exporter.svg?type=shield)](https://app.fossa.com/projects/custom%2B5618%2Fgithub.com%2Fnginxinc%2Fnginx-prometheus-exporter?ref=badge_shield)
[![Go Report Card](https://goreportcard.com/badge/github.com/nginxinc/nginx-prometheus-exporter)](https://goreportcard.com/report/github.com/nginxinc/nginx-prometheus-exporter)
![GitHub all releases](https://img.shields.io/github/downloads/nginxinc/nginx-prometheus-exporter/total?logo=github)
![GitHub release (latest by SemVer)](https://img.shields.io/github/downloads/nginxinc/nginx-prometheus-exporter/latest/total?sort=semver&logo=github)
[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/nginxinc/nginx-prometheus-exporter?logo=github&sort=semver)](https://github.com/nginxinc/nginx-prometheus-exporter/releases/latest)
![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/nginxinc/nginx-prometheus-exporter?logo=go)
[![Docker Pulls](https://img.shields.io/docker/pulls/nginx/nginx-prometheus-exporter?logo=docker&logoColor=white)](https://hub.docker.com/r/nginx/nginx-prometheus-exporter)
![Docker Image Size (latest semver)](https://img.shields.io/docker/image-size/nginx/nginx-prometheus-exporter?logo=docker&logoColor=white&sort=semver)
[![Slack](https://img.shields.io/badge/slack-%23nginx--prometheus--exporter-green?logo=slack)](https://nginxcommunity.slack.com/channels/nginx-prometheus-exporter)
# NGINX Prometheus Exporter
@ -6,7 +17,13 @@ NGINX Prometheus exporter makes it possible to monitor NGINX or NGINX Plus using
## Overview
[NGINX](https://nginx.org) exposes a handful of metrics via the [stub_status page](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html#stub_status). [NGINX Plus](https://www.nginx.com/products/nginx/) provides a richer set of metrics via the [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) and the [monitoring dashboard](https://www.nginx.com/products/nginx/live-activity-monitoring/). NGINX Prometheus exporter fetches the metrics from a single NGINX or NGINX Plus, converts the metrics into appropriate Prometheus metrics types and finally exposes them via an HTTP server to be collected by [Prometheus](https://prometheus.io/).
[NGINX](https://nginx.org) exposes a handful of metrics via the [stub_status
page](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html#stub_status). [NGINX
Plus](https://www.nginx.com/products/nginx/) provides a richer set of metrics via the
[API](https://nginx.org/en/docs/http/ngx_http_api_module.html) and the [monitoring
dashboard](https://www.nginx.com/products/nginx/live-activity-monitoring/). NGINX Prometheus exporter fetches the
metrics from a single NGINX or NGINX Plus, converts the metrics into appropriate Prometheus metrics types and finally
exposes them via an HTTP server to be collected by [Prometheus](https://prometheus.io/).
## Getting Started
@ -14,59 +31,78 @@ In this section, we show how to quickly run NGINX Prometheus Exporter for NGINX
### A Note about NGINX Ingress Controller
If you’d like to use the NGINX Prometheus Exporter with [NGINX Ingress Controller](https://github.com/nginxinc/kubernetes-ingress/) for Kubernetes, see [this doc](https://docs.nginx.com/nginx-ingress-controller/logging-and-monitoring/prometheus/) for the installation instructions.
If you’d like to use the NGINX Prometheus Exporter with [NGINX Ingress
Controller](https://github.com/nginxinc/kubernetes-ingress/) for Kubernetes, see [this
doc](https://docs.nginx.com/nginx-ingress-controller/logging-and-monitoring/prometheus/) for the installation
instructions.
### Prerequisites
We assume that you have already installed Prometheus and NGINX or NGINX Plus. Additionally, you need to:
* Expose the built-in metrics in NGINX/NGINX Plus:
* For NGINX, expose the [stub_status page](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html#stub_status) at `/stub_status` on port `8080`.
* For NGINX Plus, expose the [API](https://nginx.org/en/docs/http/ngx_http_api_module.html#api) at `/api` on port `8080`.
* Configure Prometheus to scrape metrics from the server with the exporter. Note that the default scrape port of the exporter is `9113` and the default metrics path -- `/metrics`.
- Expose the built-in metrics in NGINX/NGINX Plus:
- For NGINX, expose the [stub_status
page](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html#stub_status) at `/stub_status` on port `8080`.
- For NGINX Plus, expose the [API](https://nginx.org/en/docs/http/ngx_http_api_module.html#api) at `/api` on port
`8080`.
- Configure Prometheus to scrape metrics from the server with the exporter. Note that the default scrape port of the
exporter is `9113` and the default metrics path -- `/metrics`.
### Running the Exporter in a Docker Container
To start the exporter we use the [docker run](https://docs.docker.com/engine/reference/run/) command.
* To export NGINX metrics, run:
```
$ docker run -p 9113:9113 nginx/nginx-prometheus-exporter:0.10.0 -nginx.scrape-uri=http://<nginx>:8080/stub_status
- To export NGINX metrics, run:
```console
docker run -p 9113:9113 nginx/nginx-prometheus-exporter:0.10.0 -nginx.scrape-uri=http://<nginx>:8080/stub_status
```
where `<nginx>` is the IP address/DNS name, through which NGINX is available.
* To export NGINX Plus metrics, run:
```
$ docker run -p 9113:9113 nginx/nginx-prometheus-exporter:0.10.0 -nginx.plus -nginx.scrape-uri=http://<nginx-plus>:8080/api
- To export NGINX Plus metrics, run:
```console
docker run -p 9113:9113 nginx/nginx-prometheus-exporter:0.10.0 -nginx.plus -nginx.scrape-uri=http://<nginx-plus>:8080/api
```
where `<nginx-plus>` is the IP address/DNS name, through which NGINX Plus is available.
### Running the Exporter Binary
* To export NGINX metrics, run:
```
$ nginx-prometheus-exporter -nginx.scrape-uri=http://<nginx>:8080/stub_status
- To export NGINX metrics, run:
```console
nginx-prometheus-exporter -nginx.scrape-uri=http://<nginx>:8080/stub_status
```
where `<nginx>` is the IP address/DNS name, through which NGINX is available.
* To export NGINX Plus metrics:
```
$ nginx-prometheus-exporter -nginx.plus -nginx.scrape-uri=http://<nginx-plus>:8080/api
- To export NGINX Plus metrics:
```console
nginx-prometheus-exporter -nginx.plus -nginx.scrape-uri=http://<nginx-plus>:8080/api
```
where `<nginx-plus>` is the IP address/DNS name, through which NGINX Plus is available.
* To export and scrape NGINX metrics with unix domain sockets, run:
```
$ nginx-prometheus-exporter -nginx.scrape-uri=unix:<nginx>:/stub_status -web.listen-address=unix:/path/to/socket.sock
- To export and scrape NGINX metrics with unix domain sockets, run:
```console
nginx-prometheus-exporter -nginx.scrape-uri=unix:<nginx>:/stub_status -web.listen-address=unix:/path/to/socket.sock
```
where `<nginx>` is the path to unix domain socket, through which NGINX stub status is available.
**Note**. The `nginx-prometheus-exporter` is not a daemon. To run the exporter as a system service (daemon), configure the init system of your Linux server (such as systemd or Upstart) accordingly. Alternatively, you can run the exporter in a Docker container.
**Note**. The `nginx-prometheus-exporter` is not a daemon. To run the exporter as a system service (daemon), configure
the init system of your Linux server (such as systemd or Upstart) accordingly. Alternatively, you can run the exporter
in a Docker container.
## Usage
### Command-line Arguments
```
```console
Usage of ./nginx-prometheus-exporter:
-nginx.plus
Start the exporter for NGINX Plus. By default, the exporter is started for NGINX. The default value can be overwritten by NGINX_PLUS environment variable.
@ -105,14 +141,17 @@ Usage of ./nginx-prometheus-exporter:
## Exported Metrics
### Common metrics:
### Common metrics
Name | Type | Description | Labels
----|----|----|----|
`nginxexporter_build_info` | Gauge | Shows the exporter build information. | `gitCommit`, `version` |
`nginx_up` | Gauge | Shows the status of the last metric scrape: `1` for a successful scrape and `0` for a failed one | [] |
### Metrics for NGINX OSS:
### Metrics for NGINX OSS
#### [Stub status metrics](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html)
Name | Type | Description | Labels
----|----|----|----|
`nginx_connections_accepted` | Counter | Accepted client connections. | [] |
@ -123,8 +162,10 @@ Name | Type | Description | Labels
`nginx_connections_writing` | Gauge | Connections where NGINX is writing the response back to the client. | [] |
`nginx_http_requests_total` | Counter | Total http requests. | [] |
### Metrics for NGINX Plus:
### Metrics for NGINX Plus
#### [Connections](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_connections)
Name | Type | Description | Labels
----|----|----|----|
`nginxplus_connections_accepted` | Counter | Accepted client connections | [] |
@ -133,12 +174,14 @@ Name | Type | Description | Labels
`nginxplus_connections_idle` | Gauge | Idle client connections | [] |
#### [HTTP](https://nginx.org/en/docs/http/ngx_http_api_module.html#http_)
Name | Type | Description | Labels
----|----|----|----|
`nginxplus_http_requests_total` | Counter | Total http requests | [] |
`nginxplus_http_requests_current` | Gauge | Current http requests | [] |
#### [SSL](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_ssl_object)
Name | Type | Description | Labels
----|----|----|----|
`nginxplus_ssl_handshakes` | Counter | Successful SSL handshakes | [] |
@ -146,6 +189,7 @@ Name | Type | Description | Labels
`nginxplus_ssl_session_reuses` | Counter | Session reuses during SSL handshake | [] |
#### [HTTP Server Zones](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_server_zone)
Name | Type | Description | Labels
----|----|----|----|
`nginxplus_server_zone_processing` | Gauge | Client requests that are currently being processed | `server_zone` |
@ -160,6 +204,7 @@ Name | Type | Description | Labels
`nginxplus_server_ssl_session_reuses` | Counter | Session reuses during SSL handshake | `server_zone` |
#### [Stream Server Zones](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_server_zone)
Name | Type | Description | Labels
----|----|----|----|
`nginxplus_stream_server_zone_processing` | Gauge | Client connections that are currently being processed | `server_zone` |
@ -174,7 +219,8 @@ Name | Type | Description | Labels
#### [HTTP Upstreams](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_upstream)
> Note: for the `state` metric, the string values are converted to float64 using the following rule: `"up"` -> `1.0`, `"draining"` -> `2.0`, `"down"` -> `3.0`, `"unavail"` –> `4.0`, `"checking"` –> `5.0`, `"unhealthy"` -> `6.0`.
> Note: for the `state` metric, the string values are converted to float64 using the following rule: `"up"` -> `1.0`,
> `"draining"` -> `2.0`, `"down"` -> `3.0`, `"unavail"` –> `4.0`, `"checking"` –> `5.0`, `"unhealthy"` -> `6.0`.
Name | Type | Description | Labels
----|----|----|----|
@ -201,7 +247,8 @@ Name | Type | Description | Labels
#### [Stream Upstreams](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_upstream)
> Note: for the `state` metric, the string values are converted to float64 using the following rule: `"up"` -> `1.0`, `"down"` -> `3.0`, `"unavail"` –> `4.0`, `"checking"` –> `5.0`, `"unhealthy"` -> `6.0`.
> Note: for the `state` metric, the string values are converted to float64 using the following rule: `"up"` -> `1.0`,
> `"down"` -> `3.0`, `"unavail"` –> `4.0`, `"checking"` –> `5.0`, `"unhealthy"` -> `6.0`.
Name | Type | Description | Labels
----|----|----|----|
@ -225,6 +272,7 @@ Name | Type | Description | Labels
`nginxplus_stream_upstream_zombies` | Gauge | Servers removed from the group but still processing active client connections | `upstream`|
#### [Stream Zone Sync](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_zone_sync)
Name | Type | Description | Labels
----|----|----|----|
`nginxplus_stream_zone_sync_zone_records_pending` | Gauge | The number of records that need to be sent to the cluster | `zone` |
@ -236,6 +284,7 @@ Name | Type | Description | Labels
`nginxplus_stream_zone_sync_zone_nodes_online` | Gauge | Number of peers this node is connected to | [] |
#### [Location Zones](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_location_zone)
Name | Type | Description | Labels
----|----|----|----|
`nginxplus_location_zone_requests` | Counter | Total client requests | `location_zone` |
@ -246,6 +295,7 @@ Name | Type | Description | Labels
`nginxplus_location_zone_sent` | Counter | Bytes sent to clients | `location_zone` |
#### [Resolver](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_resolver_zone)
Name | Type | Description | Labels
----|----|----|----|
`nginxplus_resolver_name` | Counter | Total requests to resolve names to addresses | `resolver` |
@ -261,6 +311,7 @@ Name | Type | Description | Labels
`nginxplus_resolver_unknown` | Counter | Total requests completed with an unknown error | `resolver`|
#### [HTTP Requests Rate Limiting](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_limit_req_zone)
Name | Type | Description | Labels
----|----|----|----|
`nginxplus_limit_request_passed` | Counter | Total number of requests that were neither limited nor accounted as limited | `zone` |
@ -270,59 +321,79 @@ Name | Type | Description | Labels
`nginxplus_limit_request_delayed_dry_run` | Counter | Total number of requests accounted as delayed in the dry run mode | `zone` |
#### [HTTP Connections Limiting](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_http_limit_conn_zone)
Name | Type | Description | Labels
----|----|----|----|
`nginxplus_limit_connection_passed` | Counter | Total number of connections that were neither limited nor accounted as limited | `zone` |
`nginxplus_limit_connection_rejected` | Counter | Total number of connections that were rejected | `zone` |
`nginxplus_limit_connection_rejected_dry_run` | Counter | Total number of connections accounted as rejected in the dry run mode | `zone` |
#### [Stream Connections Limiting](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_stream_limit_conn_zone)
Name | Type | Description | Labels
----|----|----|----|
`nginxplus_stream_limit_connection_passed` | Counter | Total number of connections that were neither limited nor accounted as limited | `zone` |
`nginxplus_stream_limit_connection_rejected` | Counter | Total number of connections that were rejected | `zone` |
`nginxplus_stream_limit_connection_rejected_dry_run` | Counter | Total number of connections accounted as rejected in the dry run mode | `zone` |
Connect to the `/metrics` page of the running exporter to see the complete list of metrics along with their descriptions. Note: to see server zones related metrics you must configure [status zones](https://nginx.org/en/docs/http/ngx_http_status_module.html#status_zone) and to see upstream related metrics you must configure upstreams with a [shared memory zone](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone).
Connect to the `/metrics` page of the running exporter to see the complete list of metrics along with their
descriptions. Note: to see server zones related metrics you must configure [status
zones](https://nginx.org/en/docs/http/ngx_http_status_module.html#status_zone) and to see upstream related metrics you
must configure upstreams with a [shared memory zone](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone).
## Troubleshooting
The exporter logs errors to the standard output. When using Docker, if the exporter doesn’t work as expected, check its logs using [docker logs](https://docs.docker.com/engine/reference/commandline/logs/) command.
The exporter logs errors to the standard output. When using Docker, if the exporter doesn’t work as expected, check its
logs using [docker logs](https://docs.docker.com/engine/reference/commandline/logs/) command.
## Releases
### Docker images
We publish the Docker image on [DockerHub](https://hub.docker.com/r/nginx/nginx-prometheus-exporter/), [GitHub Container](https://github.com/nginxinc/nginx-prometheus-exporter/pkgs/container/nginx-prometheus-exporter), [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-prometheus-exporter) and [Quay.io](https://quay.io/repository/nginx/nginx-prometheus-exporter).
As an alternative, you can choose the *edge* version built from the [latest commit](https://github.com/nginxinc/nginx-prometheus-exporter/commits/main) from the main branch. The edge version is useful for experimenting with new features that are not yet published in a stable release.
We publish the Docker image on [DockerHub](https://hub.docker.com/r/nginx/nginx-prometheus-exporter/), [GitHub
Container](https://github.com/nginxinc/nginx-prometheus-exporter/pkgs/container/nginx-prometheus-exporter), [Amazon ECR
Public Gallery](https://gallery.ecr.aws/nginx/nginx-prometheus-exporter) and
[Quay.io](https://quay.io/repository/nginx/nginx-prometheus-exporter).
As an alternative, you can choose the *edge* version built from the [latest
commit](https://github.com/nginxinc/nginx-prometheus-exporter/commits/main) from the main branch. The edge version is
useful for experimenting with new features that are not yet published in a stable release.
### Binaries
We publish the binaries for multiple Operating Systems and architectures on the GitHub [releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases).
We publish the binaries for multiple Operating Systems and architectures on the GitHub [releases
page](https://github.com/nginxinc/nginx-prometheus-exporter/releases).
### Homebrew
You can add the NGINX homebrew tap with
```console
brew tap nginxinc/tap
```
$ brew tap nginxinc/tap
```
and then install the formula with
```
$ brew install nginx-prometheus-exporter
```console
brew install nginx-prometheus-exporter
```
## Building the Exporter
You can build the exporter using the provided Makefile. Before building the exporter, make sure the following software is installed on your machine:
* make
* git
* Docker for building the container image
* Go for building the binary
You can build the exporter using the provided Makefile. Before building the exporter, make sure the following software
is installed on your machine:
- make
- git
- Docker for building the container image
- Go for building the binary
### Building the Docker Image
To build the Docker image with the exporter, run:
```
$ make container
```console
make container
```
Note: go is not required, as the exporter binary is built in a Docker container. See the [Dockerfile](build/Dockerfile).
@ -330,16 +401,20 @@ Note: go is not required, as the exporter binary is built in a Docker container.
### Building the Binary
To build the binary, run:
```
$ make
```console
make
```
Note: the binary is built for the OS/arch of your machine. To build binaries for other platforms, see the [Makefile](Makefile).
Note: the binary is built for the OS/arch of your machine. To build binaries for other platforms, see the
[Makefile](Makefile).
The binary is built with the name `nginx-prometheus-exporter`.
## Grafana Dashboard
The official Grafana dashboard is provided with the exporter for NGINX. Check the [Grafana Dashboard](./grafana/README.md) documentation for more information.
The official Grafana dashboard is provided with the exporter for NGINX. Check the [Grafana
Dashboard](./grafana/README.md) documentation for more information.
## SBOM (Software Bill of Materials)
@ -347,21 +422,30 @@ We generate SBOMs for the binaries and the Docker image.
### Binaries
The SBOMs for the binaries are available in the releases page. The SBOMs are generated using [syft](https://github.com/anchore/syft) and are available in SPDX format.
The SBOMs for the binaries are available in the releases page. The SBOMs are generated using
[syft](https://github.com/anchore/syft) and are available in SPDX format.
### Docker Image
The SBOM for the Docker image is available in the [DockerHub](https://hub.docker.com/r/nginx/nginx-prometheus-exporter), [GitHub Container registry](https://github.com/nginxinc/nginx-prometheus-exporter/pkgs/container/nginx-prometheus-exporter), [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-prometheus-exporter) and [Quay.io](https://quay.io/repository/nginx/nginx-prometheus-exporter) repositories. The SBOMs are generated using [syft](https://github.com/anchore/syft) and stored as an attestation in the image manifest.
The SBOM for the Docker image is available in the [DockerHub](https://hub.docker.com/r/nginx/nginx-prometheus-exporter),
[GitHub Container registry](https://github.com/nginxinc/nginx-prometheus-exporter/pkgs/container/nginx-prometheus-exporter),
[Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-prometheus-exporter) and
[Quay.io](https://quay.io/repository/nginx/nginx-prometheus-exporter) repositories. The SBOMs are generated using
[syft](https://github.com/anchore/syft) and stored as an attestation in the image manifest.
For example to retrieve the SBOM for `linux/amd64` from Docker Hub and analyze it using [grype](https://github.com/anchore/grype) you can run the following command:
```
$ docker buildx imagetools inspect nginx/nginx-prometheus-exporter:edge --format '{{ json (index .SBOM "linux/amd64").SPDX }}' | grype
For example to retrieve the SBOM for `linux/amd64` from Docker Hub and analyze it using
[grype](https://github.com/anchore/grype) you can run the following command:
```console
docker buildx imagetools inspect nginx/nginx-prometheus-exporter:edge --format '{{ json (index .SBOM "linux/amd64").SPDX }}' | grype
```
## Contacts
We’d like to hear your feedback! If you have any suggestions or experience issues with the NGINX Prometheus Exporter, please create an issue or send a pull request on GitHub.
You can contact us directly via integrations@nginx.com or on the [NGINX Community Slack](https://nginxcommunity.slack.com/channels/nginx-prometheus-exporter) in the `#nginx-prometheus-exporter` channel.
We’d like to hear your feedback! If you have any suggestions or experience issues with the NGINX Prometheus Exporter,
please create an issue or send a pull request on GitHub. You can contact us directly via <integrations@nginx.com> or on
the [NGINX Community Slack](https://nginxcommunity.slack.com/channels/nginx-prometheus-exporter) in the
`#nginx-prometheus-exporter` channel.
## Contributing
@ -369,7 +453,8 @@ If you'd like to contribute to the project, please read our [Contributing guide]
## Support
The commercial support is available for NGINX Plus customers when the NGINX Prometheus Exporter is used with NGINX Ingress Controller.
The commercial support is available for NGINX Plus customers when the NGINX Prometheus Exporter is used with NGINX
Ingress Controller.
## License

14
SECURITY.md
View File

@ -2,13 +2,17 @@
## Supported Versions
We advise users to use the most recent release of the NGINX Prometheus Exporter. The commercial support is available for NGINX Plus customers when the NGINX Prometheus Exporter is used with NGINX Ingress Controller.
We advise users to use the most recent release of the NGINX Prometheus Exporter. The commercial support is available for
NGINX Plus customers when the NGINX Prometheus Exporter is used with NGINX Ingress Controller.
## Reporting a Vulnerability
The F5 Security Incident Response Team (F5 SIRT) has an email alias that makes it easy to report potential security vulnerabilities.
The F5 Security Incident Response Team (F5 SIRT) has an email alias that makes it easy to report potential security
vulnerabilities.
- If you’re an F5 customer with an active support contract, please contact [F5 Technical Support](https://www.f5.com/services/support).
- If you aren’t an F5 customer, please report any potential or current instances of security vulnerabilities with any F5 product to the F5 Security Incident Response Team at F5SIRT@f5.com
- If you’re an F5 customer with an active support contract, please contact [F5 Technical
Support](https://www.f5.com/services/support).
- If you aren’t an F5 customer, please report any potential or current instances of security vulnerabilities with any F5
product to the F5 Security Incident Response Team at <F5SIRT@f5.com>
For more information visit https://www.f5.com/services/support/report-a-vulnerability
For more information visit <https://www.f5.com/services/support/report-a-vulnerability>

32
grafana/README.md
View File

@ -1,15 +1,18 @@
# Grafana Dashboard
We provide the official Grafana dashboard that visualizes the NGINX metrics exposed by the exporter. The dashboard allows you to filter metrics per instance or see the metrics from all instances.
We provide the official Grafana dashboard that visualizes the NGINX metrics exposed by the exporter. The dashboard
allows you to filter metrics per instance or see the metrics from all instances.
## Prerequisites
The dashboard has been tested with the following software versions:
* NGINX Prometheus Exporter >= 0.4.1
* Grafana >= v5.0.0
* Prometheus >= v2.0.0
- NGINX Prometheus Exporter >= 0.4.1
- Grafana >= v5.0.0
- Prometheus >= v2.0.0
A Prometheus data source needs to be [added](https://prometheus.io/docs/visualization/grafana/#using) before installing the dashboard.
A Prometheus data source needs to be [added](https://prometheus.io/docs/visualization/grafana/#using) before installing
the dashboard.
## Installing the Dashboard
@ -18,7 +21,8 @@ In the Grafana UI complete the following steps:
1. Use the *New Dashboard* button and click *Import*.
2. Upload `dashboard.json` or copy and paste the contents of the file in the textbox and click *Load*.
3. Set the Prometheus data source and click *Import*.
4. The dashboard will appear. Note how you can filter the instance label just below the dashboard title (top left corner). This allows you to filter metrics per instance. By default, all instances are selected.
4. The dashboard will appear. Note how you can filter the instance label just below the dashboard title (top left
corner). This allows you to filter metrics per instance. By default, all instances are selected.
![dashboard](./dashboard.png)
@ -26,9 +30,13 @@ In the Grafana UI complete the following steps:
The dashboard comes with 2 rows with the following graphs for NGINX metrics:
* Status
* Up/Down graph per instance. It shows the `nginx_up` metric.
* Metrics
* Processed connections (`nginx_connections_accepted` and `nginx_connections_handled` metrics). This graph shows an [irate](https://prometheus.io/docs/prometheus/latest/querying/functions/#irate) in a range of 5 minutes. Useful for seeing the variation of the processed connections in time.
* Active connections (`nginx_connections_active`, `nginx_connections_reading`, `nginx_connections_waiting` and `nginx_connections_writing`). Useful for checking what is happening right now.
* Total Requests with an irate (5 minutes range too) of the total number of client requests (`nginx_http_requests_total`) over time.
- Status
- Up/Down graph per instance. It shows the `nginx_up` metric.
- Metrics
- Processed connections (`nginx_connections_accepted` and `nginx_connections_handled` metrics). This graph shows an
[irate](https://prometheus.io/docs/prometheus/latest/querying/functions/#irate) in a range of 5 minutes. Useful for
seeing the variation of the processed connections in time.
- Active connections (`nginx_connections_active`, `nginx_connections_reading`, `nginx_connections_waiting` and
`nginx_connections_writing`). Useful for checking what is happening right now.
- Total Requests with an irate (5 minutes range too) of the total number of client requests
(`nginx_http_requests_total`) over time.