From 4318c4c96d8d49d64a1fb937e6b86c02b57c664d Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Wed, 6 Dec 2023 11:11:22 -0800 Subject: [PATCH] Release 1.0.0 (#506) --- .github/workflows/ci.yml | 6 ++- CHANGELOG.md | 12 +---- Makefile | 2 +- README.md | 106 +++++++++++++++++++-------------------- exporter.go | 2 +- 5 files changed, 61 insertions(+), 67 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6a18adab..93fc5750 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -60,6 +60,7 @@ jobs: id: go run: | echo "go_path=$(go env GOPATH)" >> $GITHUB_OUTPUT + - name: Setup QEMU uses: docker/setup-qemu-action@68827325e0b33c7199eb31dd4e31fbe9023e06e3 # v3.0.0 with: @@ -68,6 +69,9 @@ jobs: - name: Docker Buildx uses: docker/setup-buildx-action@f95db51fddba0c2d1ec667646a06c2ce06100226 # v3.0.0 + with: + version: latest + - name: DockerHub Login uses: docker/login-action@343f7c4344506bcbf9b4de18042ae17996df046d # v3.0.0 with: @@ -188,7 +192,7 @@ jobs: platforms: ${{ github.event_name != 'pull_request' && env.DOCKER_PLATFORMS || '' }} tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} - annotations: ${{ steps.meta.outputs.annotations }} + annotations: ${{ github.event_name != 'pull_request' && steps.meta.outputs.annotations || '' }} load: ${{ github.event_name == 'pull_request' }} push: ${{ github.event_name != 'pull_request' }} cache-from: type=gha diff --git a/CHANGELOG.md b/CHANGELOG.md index 50412338..d9518461 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,16 +1,6 @@ # Changelog -## 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 - -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 - -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) +Starting with version 0.9.0 an automatically generated list of changes can be found on the [GitHub Releases page](https://github.com/nginxinc/nginx-prometheus-exporter/releases). ## 0.8.0 diff --git a/Makefile b/Makefile index e3b55d99..60b04486 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -VERSION = 0.11.0 +VERSION = 1.0.0 TAG = $(VERSION) PREFIX = nginx/nginx-prometheus-exporter diff --git a/README.md b/README.md index d958120e..727f73f1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [![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) +[![CI](https://github.com/nginxinc/nginx-prometheus-exporter/actions/workflows/ci.yml/badge.svg)](https://github.com/nginxinc/nginx-prometheus-exporter/actions/workflows/ci.yml) [![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) @@ -11,6 +11,7 @@ [![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) +[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) # NGINX Prometheus Exporter @@ -56,7 +57,7 @@ To start the exporter we use the [docker run](https://docs.docker.com/engine/ref - To export NGINX metrics, run: ```console - docker run -p 9113:9113 nginx/nginx-prometheus-exporter:0.10.0 -nginx.scrape-uri=http://:8080/stub_status + docker run -p 9113:9113 nginx/nginx-prometheus-exporter:1.0.0 --nginx.scrape-uri=http://:8080/stub_status ``` where `` is the IP address/DNS name, through which NGINX is available. @@ -64,7 +65,7 @@ To start the exporter we use the [docker run](https://docs.docker.com/engine/ref - 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://:8080/api + docker run -p 9113:9113 nginx/nginx-prometheus-exporter:1.0.0 --nginx.plus --nginx.scrape-uri=http://:8080/api ``` where `` is the IP address/DNS name, through which NGINX Plus is available. @@ -74,7 +75,7 @@ To start the exporter we use the [docker run](https://docs.docker.com/engine/ref - To export NGINX metrics, run: ```console - nginx-prometheus-exporter -nginx.scrape-uri=http://:8080/stub_status + nginx-prometheus-exporter --nginx.scrape-uri=http://:8080/stub_status ``` where `` is the IP address/DNS name, through which NGINX is available. @@ -82,21 +83,21 @@ To start the exporter we use the [docker run](https://docs.docker.com/engine/ref - To export NGINX Plus metrics: ```console - nginx-prometheus-exporter -nginx.plus -nginx.scrape-uri=http://:8080/api + nginx-prometheus-exporter --nginx.plus --nginx.scrape-uri=http://:8080/api ``` where `` is the IP address/DNS name, through which NGINX Plus is available. -- To export and scrape NGINX metrics with unix domain sockets, run: +- To scrape NGINX metrics with unix domain sockets, run: ```console - nginx-prometheus-exporter -nginx.scrape-uri=unix::/stub_status -web.listen-address=unix:/path/to/socket.sock + nginx-prometheus-exporter --nginx.scrape-uri=unix::/stub_status ``` where `` 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 +**Note**. The `nginx-prometheus-exporter` is not a daemon. To run the exporter as a system service (daemon), you can +follow the example in [examples/systemd](./examples/systemd/README.md). Alternatively, you can run the exporter in a Docker container. ## Usage @@ -104,41 +105,30 @@ in a Docker container. ### 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. - -nginx.retries int - A number of retries the exporter will make on start to connect to the NGINX stub_status page/NGINX Plus API before exiting with an error. The default value can be overwritten by NGINX_RETRIES environment variable. - -nginx.retry-interval duration - An interval between retries to connect to the NGINX stub_status page/NGINX Plus API on start. The default value can be overwritten by NGINX_RETRY_INTERVAL environment variable. (default 5s) - -nginx.scrape-uri string - A URI or unix domain socket path for scraping NGINX or NGINX Plus metrics. - For NGINX, the stub_status page must be available through the URI. For NGINX Plus -- the API. The default value can be overwritten by SCRAPE_URI environment variable. (default "http://127.0.0.1:8080/stub_status") - Configure this option with the URI for every nginx instance to scrape. - -nginx.ssl-ca-cert string - Path to the PEM encoded CA certificate file used to validate the servers SSL certificate. The default value can be overwritten by SSL_CA_CERT environment variable. - -nginx.ssl-client-cert string - Path to the PEM encoded client certificate file to use when connecting to the server. The default value can be overwritten by SSL_CLIENT_CERT environment variable. - -nginx.ssl-client-key string - Path to the PEM encoded client certificate key file to use when connecting to the server. The default value can be overwritten by SSL_CLIENT_KEY environment variable. - -nginx.ssl-verify - Perform SSL certificate verification. The default value can be overwritten by SSL_VERIFY environment variable. (default true) - -nginx.timeout duration - A timeout for scraping metrics from NGINX or NGINX Plus. The default value can be overwritten by TIMEOUT environment variable. (default 5s) - -prometheus.const-labels value - A comma separated list of constant labels that will be used in every metric. Format is label1=value1,label2=value2... The default value can be overwritten by CONST_LABELS environment variable. - -web.listen-address string - An address or unix domain socket path to listen on for web interface and telemetry. The default value can be overwritten by LISTEN_ADDRESS environment variable. (default ":9113") - -web.telemetry-path string - A path under which to expose metrics. The default value can be overwritten by TELEMETRY_PATH environment variable. (default "/metrics") - -web.secured-metrics - Expose metrics using https. The default value can be overwritten by SECURED_METRICS variable. (default false) - -web.ssl-server-cert string - Path to the PEM encoded certificate for the nginx-exporter metrics server(when web.secured-metrics=true). The default value can be overwritten by SSL_SERVER_CERT variable. - -web.ssl-server-key string - Path to the PEM encoded key for the nginx-exporter metrics server (when web.secured-metrics=true). The default value can be overwritten by SSL_SERVER_KEY variable. - -version - Display the NGINX exporter version. (default false) +usage: nginx-prometheus-exporter [] + + +Flags: + -h, --[no-]help Show context-sensitive help (also try --help-long and --help-man). + --web.listen-address=:9113 ... + Addresses on which to expose metrics and web interface. Repeatable for multiple addresses. + --web.config.file="" [EXPERIMENTAL] Path to configuration file that can enable TLS or authentication. See: https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md + --web.telemetry-path="/metrics" + Path under which to expose metrics. ($TELEMETRY_PATH) + --[no-]nginx.plus Start the exporter for NGINX Plus. By default, the exporter is started for NGINX. ($NGINX_PLUS) + --nginx.scrape-uri=http://127.0.0.1:8080/stub_status ... + A URI or unix domain socket path for scraping NGINX or NGINX Plus metrics. For NGINX, the stub_status page must be available through the URI. For NGINX Plus -- the API. Repeatable for multiple URIs. + --[no-]nginx.ssl-verify Perform SSL certificate verification. ($SSL_VERIFY) + --nginx.ssl-ca-cert="" Path to the PEM encoded CA certificate file used to validate the servers SSL certificate. ($SSL_CA_CERT) + --nginx.ssl-client-cert="" + Path to the PEM encoded client certificate file to use when connecting to the server. ($SSL_CLIENT_CERT) + --nginx.ssl-client-key="" Path to the PEM encoded client certificate key file to use when connecting to the server. ($SSL_CLIENT_KEY) + --nginx.timeout=5s A timeout for scraping metrics from NGINX or NGINX Plus. ($TIMEOUT) + --prometheus.const-label=PROMETHEUS.CONST-LABEL ... + Label that will be used in every metric. Format is label=value. It can be repeated multiple times. ($CONST_LABELS) + --log.level=info Only log messages with the given severity or above. One of: [debug, info, warn, error] + --log.format=logfmt Output format of log messages. One of: [logfmt, json] + --[no-]version Show application version. ``` ## Exported Metrics @@ -147,11 +137,17 @@ Usage of ./nginx-prometheus-exporter: 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 | [] | +`nginx_exporter_build_info` | Gauge | Shows the exporter build information. | `branch`, `goarch`, `goos`, `goversion`, `revision`, `tags` and `version` | +`promhttp_metric_handler_requests_total` | Counter | Total number of scrapes by HTTP status code. | `code` (the HTTP status code) | +`promhttp_metric_handler_requests_in_flight` | Gauge | Current number of scrapes being served. | [] | +`go_*` | Multiple | Go runtime metrics. | [] | ### Metrics for NGINX OSS +Name | Type | Description | Labels +----|----|----|----| +`nginx_up` | Gauge | Shows the status of the last metric scrape: `1` for a successful scrape and `0` for a failed one | [] | + #### [Stub status metrics](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html) Name | Type | Description | Labels @@ -166,6 +162,10 @@ Name | Type | Description | Labels ### Metrics for NGINX Plus +Name | Type | Description | Labels +----|----|----|----| +`nginxplus_up` | Gauge | Shows the status of the last metric scrape: `1` for a successful scrape and `0` for a failed one | [] | + #### [Connections](https://nginx.org/en/docs/http/ngx_http_api_module.html#def_nginx_connections) Name | Type | Description | Labels @@ -377,7 +377,7 @@ Name | Type | Description | Labels 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 +zones](https://nginx.org/en/docs/http/ngx_http_api_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 @@ -389,14 +389,14 @@ logs using [docker logs](https://docs.docker.com/engine/reference/commandline/lo ### 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 +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. +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 diff --git a/exporter.go b/exporter.go index 1f1bd512..e6297655 100644 --- a/exporter.go +++ b/exporter.go @@ -85,7 +85,7 @@ var ( webConfig = kingpinflag.AddFlags(kingpin.CommandLine, ":9113") metricsPath = kingpin.Flag("web.telemetry-path", "Path under which to expose metrics.").Default("/metrics").Envar("TELEMETRY_PATH").String() nginxPlus = kingpin.Flag("nginx.plus", "Start the exporter for NGINX Plus. By default, the exporter is started for NGINX.").Default("false").Envar("NGINX_PLUS").Bool() - scrapeURIs = kingpin.Flag("nginx.scrape-uri", "A URI or unix domain socket path for scraping NGINX or NGINX Plus metrics. For NGINX, the stub_status page must be available through the URI. For NGINX Plus -- the API.").Default("http://127.0.0.1:8080/stub_status").Strings() + scrapeURIs = kingpin.Flag("nginx.scrape-uri", "A URI or unix domain socket path for scraping NGINX or NGINX Plus metrics. For NGINX, the stub_status page must be available through the URI. For NGINX Plus -- the API. Repeatable for multiple URIs.").Default("http://127.0.0.1:8080/stub_status").Strings() sslVerify = kingpin.Flag("nginx.ssl-verify", "Perform SSL certificate verification.").Default("false").Envar("SSL_VERIFY").Bool() sslCaCert = kingpin.Flag("nginx.ssl-ca-cert", "Path to the PEM encoded CA certificate file used to validate the servers SSL certificate.").Default("").Envar("SSL_CA_CERT").String() sslClientCert = kingpin.Flag("nginx.ssl-client-cert", "Path to the PEM encoded client certificate file to use when connecting to the server.").Default("").Envar("SSL_CLIENT_CERT").String()