problem using a unix socket for the nginx stub_status #1261

Happy86 · 2026-03-02T11:41:38Z

Happy86
Mar 2, 2026

Hi,

I am not sure how to specify localhost/stub_status within --nginx.scrape-uri= when exposing the stub_status from nginx through a unix socket.

Because port 8080/TCP is already in use I set the following nginx server block similar to PR #68 as

server {
  server_name _;
  listen unix:/var/run/nginx_exporter.sock;

  location /stub_status {
    access_log off;
    stub_status on;
  }
}

The documentation tells me:

      --nginx.scrape-uri=http://127.0.0.1:8080/stub_status ...
                                 A URI or unix domain socket path for scraping NGINX or NGINX

Unfortunately it does not tell me how to format the value for a unix socket.

I tried ARGS="--nginx.scrape-uri=unix:///var/run/nginx_exporter.sock" in my /etc/default/prometheus-nginx-exporter.

I can in fact use curl to see that the stub_status does in fact work:

$ curl -X GET --unix-socket /var/run/nginx_exporter.sock localhost/stub_status
Active connections: 6
server accepts handled requests
 31041 31041 53016
Reading: 0 Writing: 4 Waiting: 2

However the Exporter tells me:

$ curl localhost:9113/metrics -s|grep nginx_up
# HELP nginx_up Status of the last metric scrape
# TYPE nginx_up gauge
nginx_up 0

Also journalctl -f -u prometheus-nginx-exporter.service tells me:

Mär 02 12:13:49 hostname prometheus-nginx-exporter[47350]: time=2026-03-02T11:13:49.050Z level=ERROR source=nginx.go:57 msg="error getting stats" error="failed to parse response body \"<!DOCTYPE html>\\n<html>\\n<head>\\n<title>Welcome to nginx!</title>\\n<style>\\nhtml { color-scheme: light dark; }\\nbody { width: 35em; margin: 0 auto;\\nfont-family: Tahoma, Verdana, Arial, sans-serif; }\\n</style>\\n</head>\\n<body>\\n<h1>Welcome to nginx!</h1>\\n<p>If you see this page, the nginx web server is successfully installed and\\nworking. Further configuration is required.</p>\\n\\n<p>For online documentation and support please refer to\\n<a href=\\\"http://nginx.org/\\\">nginx.org</a>.<br/>\\nCommercial support is available at\\n<a href=\\\"http://nginx.com/\\\">nginx.com</a>.</p>\\n\\n<p><em>Thank you for using nginx.</em></p>\\n</body>\\n</html>\\n\": failed to scan template metrics: input does not match format"

If I add /stub_status to the scrape-uri like ARGS="--nginx.scrape-uri=unix:///var/run/nginx_exporter.sock/stub_status" the exporter is not able to connect to nginx:

Mär 02 12:36:08 hostname prometheus-nginx-exporter[47475]: time=2026-03-02T11:36:08.609Z level=ERROR source=nginx.go:57 msg="error getting stats" error="failed to get http://unix: Get \"http://unix\": round trip failed: dial unix ///var/run/nginx_exporter.sock/stub_status: connect: not a directory

I'm on Debian 13/Trixie with prometheus-nginx-exporter version 1.4.1-1+b5 (released January 2025) but as PR #68 has been merged in November 2019 I hope the feature is present even though I'm using the older version packaged by Debian and not Version 1.5.1 from October 2025.

(Also looking at the changelogs between 1.4.1 and 1.5.1 I haven't seen anything regarding the stub_status through a socket.)

Would be nice to also give an example in the documentation (/usr/bin/prometheus-nginx-exporter --help)

Thank you.

Best regards,
Andreas

Answered by Happy86

Mar 2, 2026

Through trial and error I found the answer myself. 🙂

ARGS="--nginx.scrape-uri=unix:///var/run/nginx_exporter.sock:localhost/nginx_status"

So --nginx.scrape-uri=unix://${PATH_TO_SOCKET}:localhost/stub_status.

View full answer

Happy86 · 2026-03-02T12:06:57Z

Happy86
Mar 2, 2026
Author

Through trial and error I found the answer myself. 🙂

ARGS="--nginx.scrape-uri=unix:///var/run/nginx_exporter.sock:localhost/nginx_status"

So --nginx.scrape-uri=unix://${PATH_TO_SOCKET}:localhost/stub_status.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

problem using a unix socket for the nginx stub_status #1261

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

problem using a unix socket for the nginx stub_status #1261

Uh oh!

Uh oh!

Happy86 Mar 2, 2026

Replies: 1 comment

Uh oh!

Happy86 Mar 2, 2026 Author

Happy86
Mar 2, 2026

Happy86
Mar 2, 2026
Author