Release 1.0.0 (#506)

nginxinc · Dec 6, 2023 · 4318c4c · 4318c4c
1 parent 44a1e7c
commit 4318c4c
Show file tree

Hide file tree

Showing 5 changed files with 61 additions and 67 deletions.
diff --git 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
@@ -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
@@ -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
@@ -1,6 +1,6 @@
 <!-- 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)
+[![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,15 +57,15 @@ 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://<nginx>:8080/stub_status
+    docker run -p 9113:9113 nginx/nginx-prometheus-exporter:1.0.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:
 
     ```console
-    docker run -p 9113:9113 nginx/nginx-prometheus-exporter:0.10.0 -nginx.plus -nginx.scrape-uri=http://<nginx-plus>:8080/api
+    docker run -p 9113:9113 nginx/nginx-prometheus-exporter:1.0.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.
@@ -74,71 +75,60 @@ 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://<nginx>:8080/stub_status
+    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:
 
     ```console
-    nginx-prometheus-exporter -nginx.plus -nginx.scrape-uri=http://<nginx-plus>:8080/api
+    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:
+- To 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
+    nginx-prometheus-exporter --nginx.scrape-uri=unix:<nginx>:/stub_status
     ```
 
     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
+**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
 
 ### 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>]
+
+
+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
@@ -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()