{ "componentChunkName": "component---src-templates-issues-tsx", "path": "/issues/456", "result": {"data":{"issuesJson":{"id":"aaf54623-f7dd-595b-9be8-6fd68d83275d","title":"martin-helmich/prometheus-nginxlog-exporter: 解析 Nginx 日志，暴露成指标","number":456,"bodyHTML":"
\n



\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Reposmartin-helmich/prometheus-nginxlog-exporter
Views\"views\"
Stars\"stars\"
Forks\"forks\"
License\"license\"
UpdatedAt\"last-commit\"
CreatedAt\"create-at\"
\n\n

\"\"

\n\n
\n

= NGINX-to-Prometheus log file exporter
\n:tip-caption: 💡
\n:note-caption: ℹ️
\n:important-caption: ❗
\n:caution-caption: 🔥
\n:warning-caption: ⚠️
\n:toc:
\n:toc-placement!:
\n:toc-title:

\n

image:https://img.shields.io/github/workflow/status/martin-helmich/prometheus-nginxlog-exporter/Compile%20&%20Test[GitHub Workflow Status]
\nimage:https://quay.io/repository/martinhelmich/prometheus-nginxlog-exporter/status[link=\"https://quay.io/repository/martinhelmich/prometheus-nginxlog-exporter\",Docker Repository on Quay]
\nimage:https://goreportcard.com/badge/github.com/martin-helmich/prometheus-nginxlog-exporter[link=\"https://goreportcard.com/report/github.com/martin-helmich/prometheus-nginxlog-exporter\", Go Report Card]
\nimage:https://img.shields.io/github/license/martin-helmich/prometheus-nginxlog-exporter[GitHub]
\nimage:https://img.shields.io/badge/donate-PayPal-yellow[link=\"https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=SEARYHPVS9U5N&source=url\", Donate]

\n

Helper tool that continuously reads an NGINX log file (or any kind of similar log file) and exports metrics to https://prometheus.io/[Prometheus].

\n

[discrete]
\n== Contents

\n

toc::[]

\n

== Usage

\n

You can either use a simple configuration, using command-line flags, or create
\na configuration file with a more advanced configuration.

\n

Use the command-line:

\n

[source]

\n

$ ./prometheus-nginxlog-exporter
\n-format=\"\"
\n-listen-port=4040
\n-namespace=nginx
\n[PATHS-TO-LOGFILES...]

\n

Use the configuration file:

\n

[source]

\n

$ ./prometheus-nginxlog-exporter -config-file /path/to/config.hcl

\n

You can verify your config file before deployment, which will exit with shell status indicating success:

\n

[source]

\n

$ ./prometheus-nginxlog-exporter -config-file /path/to/config.hcl -verify-config

\n

Installation

\n

There are multiple ways to install this exporter.

\n

=== Docker

\n

Docker images for this exporter are available at the quay.io and pkg.github.com
\nregistries:

\n\n

Have a look at the https://github.com/martin-helmich/prometheus-nginxlog-exporter/releases[releases page]
\nto see the available versions and how to pull their images. In general, I would
\nrecommend using the v1 tag instead of latest.

\n

Run the exporter as follows (adjust paths like /path/to/logs and
\n/path/to/config to your own needs):

\n

[source]

\n

$ docker run
\n--name nginx-exporter
\n-v /path/to/logs:/mnt/nginxlogs
\n-p 4040:4040
\nquay.io/martinhelmich/prometheus-nginxlog-exporter
\nmnt/nginxlogs/access.log

\n

Command-line flags and arguments can simply be appended to the docker run command, for example to use a
\nconfiguration file:

\n

[source]

\n

$ docker run
\n--name nginx-exporter
\n-p 4040:4040
\n-v /path/to/logs:/mnt/nginxlogs
\n-v /path/to/config.hcl:/etc/prometheus-nginxlog-exporter.hcl
\nquay.io/martinhelmich/prometheus-nginxlog-exporter
\n-config-file /etc/prometheus-nginxlog-exporter.hcl

\n

=== DEB and RPM packages

\n

Each https://github.com/martin-helmich/prometheus-nginxlog-exporter/releases[release]
\nfrom 1.5.1 or newer provides both DEB and RPM packages.

\n

DEB:

\n
$ wget https://github.com/martin-helmich/prometheus-nginxlog-exporter/releases/download/v1.9.2/prometheus-nginxlog-exporter_1.9.2_linux_amd64.deb\n$ apt install ./prometheus-nginxlog-exporter_1.9.2_linux_amd64.deb\n
\n

RPM:

\n
$ wget https://github.com/martin-helmich/prometheus-nginxlog-exporter/releases/download/v1.9.2/prometheus-nginxlog-exporter_1.9.2_linux_amd64.rpm\n$ yum localinstall prometheus-nginxlog-exporter_1.9.2_linux_amd64.rpm\n
\n

The package come with a dependency on systemd and configure the exporter to be
\nrunning automatically:

\n
$ systemctl status prometheus-nginxlog-exporter\n$ # systemctl disable prometheus-nginxlog-exporter\n$ # systemctl enable prometheus-nginxlog-exporter\n
\n

The packages drop a configuration file to /etc/prometheus-nginxlog-exporter.hcl
\nwhich you can adjust to your own needs.

\n

Manual installation, with systemd

\n

If you do not want to use one of the pre-built packages, you can download the
\nbinary itself and manually configure systemd to start it. You can find an
\nexample unit file for this service
\nhttps://github.com/martin-helmich/prometheus-nginxlog-exporter/blob/master/res/package/prometheus-nginxlog-exporter.service[in this repository].
\nSimply copy the unit file to /etc/systemd/system:

\n
$ wget -O /etc/systemd/system/prometheus-nginxlog-exporter.service https://raw.githubusercontent.com/martin-helmich/prometheus-nginxlog-exporter/master/res/package/prometheus-nginxlog-exporter.service\n$ systemctl enable prometheus-nginxlog-exporter\n$ systemctl start prometheus-nginxlog-exporter\n
\n

The shipped unit file expects the binary to be located in
\n/usr/sbin/prometheus-nginxlog-exporter (if you sideload the exporter without
\nusing your package manager, you might want to put it to /usr/local, instead)
\nand the configuration file in /etc/prometheus-nginxlog-exporter.hcl. Adjust
\nto your own needs.

\n

Kubernetes

\n

If you run a logfile-generating service (be it NGINX, or anything that generates
\nsimilar access log files) in Kubernetes, you can run the exporter as a sidecar
\nalong your \"main\" container within the same pod.

\n

The following example shows you how to deploy the exporter as a sidecar,
\naccepting logs from the main container via syslog:

\n

[source,yaml]

\n

apiVersion: v1
\nkind: Pod
\nmetadata:
\nname: nginx-example
\nannotations:
\nprometheus.io/scrape: \"true\"
\nprometheus.io/port: \"4040\"
\nspec:
\ncontainers:
\n- name: web
\nimage: nginx
\n# ...
\n- name: exporter
\nimage: docker.pkg.github.com/martin-helmich/prometheus-nginxlog-exporter/exporter:v1
\nargs: [\"-config-file\", \"/etc/prometheus-nginxlog-exporter/config.hcl\"]
\nvolumeMounts:
\n- name: exporter-config
\nmountPath: /etc/prometheus-nginxlog-exporter
\nvolumes:
\n- name: exporter-config
\nconfigMap:
\nname: exporter-config

\n

In this example, the configuration file is passed via the exporter-config
\nConfigMap. This might look like follows:

\n

[source,yaml]

\n

apiVersion: v1
\nkind: ConfigMap
\nmetadata:
\nname: exporter-config
\ndata:
\nconfig.hcl: |
\nlisten {
\nport = 4040
\n}

\n
namespace \"nginx\" {\n  source = {\n    syslog {\n      listen_address = \"udp://127.0.0.1:5531\"\n      format = \"rfc3164\"\n    }\n  }\n\n  format = \"$remote_addr - $remote_user [$time_local] \\\"$request\\\" $status $body_bytes_sent \\\"$http_referer\\\" \\\"$http_user_agent\\\" \\\"$http_x_forwarded_for\\\"\"\n\n  labels {\n    app = \"default\"\n  }\n}\n
\n
\n

The config file instructs the exporter to accept log input via syslog. To
\nforward logs to the exporter, just instruct your main container to send its
\naccess logs via syslog to 127.0.0.1:5531 (which works, since the main
\ncontainer and the sidecar share their network namespace).

\n

Build from source

\n

To build the exporter from source, simply build it with go get:

\n
$ go get github.com/martin-helmich/prometheus-nginxlog-exporter\n
\n

Alternatively, clone this repository and just run go build:

\n
$ git clone https://github.com/martin-helmich/prometheus-nginxlog-exporter.git\n$ cd prometheus-nginxlog-exporter\n$ go build\n
\n

== Collected metrics

\n

This exporter collects the following metrics. This collector can listen on
\nmultiple log files at once and publish metrics in different namespaces. Each
\nmetric uses the labels method (containing the HTTP request method) and
\nstatus (containing the HTTP status code).

\n

[IMPORTANT]

\n

Keep in mind that some of these metrics will require certain values to be present
\nin your access log format (for example, the http_upstream_time_seconds metric
\nwill require your access to contain the variable $upstream_response_time.

\n

Metrics are exported at the /metrics path.

\n

These metrics are exported:

\n

|===
\n| <namespace>_http_response_count_total | The total amount of processed HTTP requests/responses.
\n| <namespace>_http_response_size_bytes | The total amount of transferred content in bytes.
\n| <namespace>_http_request_size_bytes | The total amount of received traffic in bytes. This metrics requires the $request_length variable in the log format.
\n| <namespace>_http_upstream_time_seconds | A summary vector of the upstream response times in seconds. Logging these needs to be specifically enabled in NGINX using the $upstream_response_time variable in the log format.
\n| <namespace>_http_upstream_time_seconds_hist | Same as <namespace>_http_upstream_time_seconds, but as a histogram vector. Also requires the $upstream_response_time variable in the log format.
\n| <namespace>_http_response_time_seconds | A summary vector of the total response times in seconds. Logging these needs to be specifically enabled in NGINX using the $request_time variable in the log format.
\n| <namespace>_http_response_time_seconds_hist | Same as <namespace>_http_response_time_seconds, but as a histogram vector. Also requires the $request_time variable in the log format.
\n|===

\n

Additional labels can be configured in the configuration file (see below).

\n

<namespace> can be omitted or overridden - see <> for
\nmore information.

\n

== Configuration file

\n

You can specify a configuration file to read at startup. The configuration file
\nis expected to be either in https://github.com/hashicorp/hcl[HCL] or YAML format. Here's an example file:

\n

[source,hcl]

\n

listen {
\nport = 4040
\naddress = \"10.1.2.3\"
\nmetrics_endpoint = \"/metrics\"
\n}

\n

consul {
\nenable = true
\naddress = \"localhost:8500\"
\ndatacenter = \"dc1\"
\nscheme = \"http\"
\ntoken = \"\"
\nservice {
\nid = \"nginx-exporter\"
\nname = \"nginx-exporter\"
\naddress = \"192.168.3.1\"
\ntags = [\"foo\", \"bar\"]
\n}
\n}

\n

namespace \"app1\" {
\nformat = \"$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" \"$http_x_forwarded_for\"\"
\nsource {
\nfiles = [
\n\"/var/log/nginx/app1/access.log\"
\n]
\n}

\n

log can be printed to std out, e.g. for debugging purposes (disabled by default)

\n

print_log = false

\n

metrics_override = { prefix = \"myprefix\" }

\n

namespace_label = \"vhost\"

\n

labels {
\napp = \"application-one\"
\nenvironment = \"production\"
\nfoo = \"bar\"
\n}

\n

histogram_buckets = [.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10]
\n}

\n

namespace \"app2\" {
\nformat = \"$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" \"$http_x_forwarded_for\" $upstream_response_time\"
\nsource {
\nfiles = [
\n\"/var/log/nginx/app2/access.log\"
\n]
\n}
\n}

\n

The same file as YAML file:

\n

[source,yaml]

\n

listen:
\nport: 4040
\naddress: \"10.1.2.3\"
\nmetrics_endpoint: \"/metrics\"

\n

consul:
\nenable: true
\naddress: \"localhost:8500\"
\ndatacenter: dc1
\nscheme: http
\ntoken: \"\"
\nservice:
\nid: \"nginx-exporter\"
\nname: \"nginx-exporter\"
\naddress = \"192.168.3.1\"
\ntags: [\"foo\", \"bar\"]

\n

namespaces:

\n\n
\n

Advanced features

\n

Namespace as labels

\n

For historic reasons, this exporter exports separate metrics for different
\nnamespaces (because the namespace is part of the metric name). However, in many
\n(most) cases, it's more convenient to have the same metric name across different
\nnamespaces (with different log formats and names).

\n

This can be done in two steps:

\n
    \n
  1. Override Prometheus metrics namespace to some common prefix (metrics_override)
    2. \n
  2. Set label name for nginxlog-exporter's config namespace (namespace_label)
    3. \n
\n

[source,hcl]

\n

namespace \"app1\" {
\n...
\nmetrics_override = { prefix = \"myprefix\" }
\nnamespace_label = \"vhost\"
\n...
\n}

\n

namespace \"app2\" {
\n...
\nmetrics_override = { prefix = \"myprefix\" }
\nnamespace_label = \"vhost\"
\n...
\n}

\n

Exported metrics will have the following format:
\n[source]

\n

myprefix_http_response_count_total{vhost=\"app1\", ...}
\nmyprefix_http_response_count_total{vhost=\"app2\", ...}
\n...

\n\n

Some details and history on this can be found in https://github.com/martin-helmich/prometheus-nginxlog-exporter/issues/13[issue #13].

\n

Custom labels pass-through

\n

Partial case of <>:

\n

[source,hcl]

\n

namespace \"app1\" {
\nformat = \"$remote_addr - $remote_user [$time_local] ... \"$geoip_country_code\" $upstream_addr\"
\n...
\nrelabel \"upstream_addr\" { from = \"upstream_addr\" }
\nrelabel \"country\" { from = \"geoip_country_code\" }
\n...
\n}

\n

Exported metrics will have upstream_addr and country labels.

\n

Log sources

\n

Currently, the exporter supports reading log data from

\n
    \n
  1. files
    2. \n
  2. syslog
    3. \n
\n

All log sources can be configured on a per-namespace basis using the source property.

\n

Reading from files

\n

When reading from log files, all that is needed is a files property:

\n
namespace \"test\" {\n  source {\n    files = [\"/var/log/nginx/access.log\"]\n    // ...\n  }\n}
\n

Reading from syslog

\n

The exporter can also open and listen on a Syslog port and read logs from there. Configuration works as follows:

\n

[source,hcl]

\n

namespace \"test\" {
\nsource {
\nsyslog {
\nlisten_address = \"udp://127.0.0.1:8514\" <1>
\nformat = \"rfc3164\" <2>
\ntags = [\"nginx\"] <3>
\n}

\n
// ...\n
\n

}
\n}

\n

<1> The listen_address might be either a TCP or UDP address. UNIX sockets are not supported (yet -- pull requests are welcome)
\n<2> The format may be one of rfc3164, rfc5424, rfc6587 or auto. If omitted, it will default to auto
\n<3> The tags must be specified.

\n

Have a look at http://nginx.org/en/docs/syslog.html[the respective section of the NGINX documentation] on how to set up NGINX to log into syslog.

\n

Dynamic re-labeling

\n

Re-labeling lets you add arbitrary fields from the parsed log line as labels to your metrics.
\nTo add a dynamic label, add a relabel statement to your configuration file:

\n

[source,hcl]

\n

namespace \"app-1\" {
\n// ...

\n

relabel \"host\" {
\nfrom = \"server_name\"
\nwhitelist = [ <1>
\n\"host-a.com\",
\n\"host-b.de\"
\n]
\n}
\n}

\n

<1> The whitelist property is optional; if set, only the supplied values will be added as label.
\nAll other values will be subsumed under the \"other\" label value. See #16 for a more detailed
\ndiscussion around the reasoning.

\n

Dynamic relabeling also allows you to aggregate your metrics by request path (which replaces
\nthe experimental feature originally introduced in #23). The following example splits the content of
\nthe request variable at every space (using split) and return the second element (index 1) of the
\nresulting list which is the base for the regex):

\n

[source,hcl]

\n

namespace \"app1\" {
\n// ...

\n

relabel \"request_uri\" {
\nfrom = \"request\"
\nsplit = 2
\nseparator = \" \" // <1>

\n
// if enabled, only include label in response count metric (default is false)\nonly_counter = false\n\nmatch \"^/users/[0-9]+\" {\n  replacement = \"/users/:id\"\n}\n\nmatch \"^/profile\" {\n  replacement = \"/profile\"\n}\n
\n

}
\n}

\n

<1> The separator property is optional; if omitted, the space character (\" \") will be assumed as separator.

\n

If a match is found, the replacement replaces each occurrence of the corresponding match in the original value. Otherwise the processing continues to check the following match statements.

\n

The YAML configuration for relabelings works similar to the HCL configuration:

\n

[source,yaml]

\n

namespaces:

\n\n
\n

If your regular expression contains groups, you can also use the matched values of those in the replacement value:

\n

[source,hcl]

\n

relabel \"request_uri\" {
\nfrom = \"request\"
\nsplit = 2

\n

match \"^/(users|profiles)/[0-9]+\" {
\nreplacement = \"/$1/:id\"
\n}
\n}

\n

File Globs

\n

You can specify one or more wildcards in the source file names, in which case the wildcards will be resolved to the corresponding list of files at startup of the exporter.

\n

Be aware that the list of matches is only evaluated at the start of the program. If a new file is added with a match of one glob filter, you'll have to restart the program for it to be monitored.

\n

Given a config like this:

\n

[source,hcl]

\n

namespace \"test\" {
\nsource {
\nfiles = [\"/var/log/nginx/*_access.log\"]
\n// ...
\n}
\n}

\n

And a folder containing these files:

\n
# /var/log/nginx\nmain_access.log\nmain_error.log\nvirtualhost1_access.log\nvirtualhost1_error.log
\n

The list of files monitored by this namespace will be /var/log/nginx/main_access.log,/var/log/nginx/virtualhost1_access.log.

\n

JSON log_format

\n

You can use the JSON parser by setting the --parser command line flag or parser config file property to json.

\n

== Frequently Asked Questions

\n
\n

I have started the exporter, but it is not exporting any application-specific metrics!

\n
\n

This may have several issues:

\n
    \n
  1. Make sure that the access log files that your exporter is listening on are present. The exporter will exit with an error code if a file is present but cannot be opened (for example, due to bad permissions), but will wait for a file if it does not yet exist.
    2. \n
  2. Make sure that the exporter can parse the lines from your access log files. Pay attention to the <namespace>_parse_errors_total metric, which will indicate how many log lines could not be parsed.
    3. \n
\n
\n

The exporter exports the <namespace>_http_response_count_total metric, but not [other metric that is mentioned in the README]!

\n
\n

Most metrics require certain values to be present in the access log files that are not present in the NGINX default configuration. Especially, make sure that the access log contains the http://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_response_time[`$upstream_response_time`], http://nginx.org/en/docs/http/ngx_http_log_module.html#var_request_time[`$request_time`] and/or http://nginx.org/en/docs/http/ngx_http_core_module.html#variables[`$body_bytes_sent`] variables. These need to be enabled in the NGINX configuration (more precisely, the log_format setting) and then added to the format specified for the exporter.

\n
\n

How can I configure NGINX to export these variables?

\n
\n

Have a look at NGINX's https://www.nginx.com/resources/admin-guide/logging-and-monitoring/[Logging and Monitoring] guide. It contains some good examples that contain the $request_time and $upstream_response_time:

\n
log_format upstream_time '$remote_addr - $remote_user [$time_local] '\n                         '\"$request\" $status $body_bytes_sent '\n                         '\"$http_referer\" \"$http_user_agent\"'\n                         'rt=$request_time uct=\"$upstream_connect_time\" uht=\"$upstream_header_time\" urt=\"$upstream_response_time\"';\n
\n

Credits

\n","updatedAt":"2025-05-21T16:17:05Z","upvoteCount":null,"author":{"login":"eryajf","avatarUrl":"https://avatars.githubusercontent.com/u/33259379?u=e4a4090a38ac2473aaed4ef9945233636776c6c3&v=4","url":"https://github.com/eryajf"},"category":null,"labels":{"edges":[{"node":{"name":"更多","color":"25B472"}},{"node":{"name":"Prometheus-Exporter","color":"367acb"}},{"node":{"name":"martin-helmich","color":"1f6fd7"}}]},"comments":{"edges":[]}}},"pageContext":{"number":456,"previous":{"title":"feiyu563/PrometheusAlert: 开源的运维告警中心消息转发系统，支持主流的监控系统 Prometheus, Zabbix, 日志系统 Graylog 和数据可视化系统 Grafana 发出的预警消息，支持钉钉，微信，华为云短信，腾讯云短信，腾讯云电话，阿里云短信，阿里云电话等 ","number":455},"next":{"title":"prometheus/prometheus: Prometheus 是一个监控系统和时序数据库，在被广泛应用于云原生的监控","number":457}}}, "staticQueryHashes": ["151096407","2861350382"]}