texastribune/prometheus-nginxlog-exporter

NGINX-to-Prometheus日志文件导出器

!GitHub Workflow Status !Docker Repository on Quay !https://goreportcard.com/badge/github.com/martin-helmich/prometheus-nginxlog-exporter !GitHub !Donate

辅助工具，用于持续读取NGINX日志文件（或任何类似日志文件）并将指标导出到Prometheus。

目录

• 使用方法
• 安装
• 收集的指标
• 配置文件
• 高级功能
• 实验性功能
• 常见问题
• credits

使用方法

您可以使用简单的命令行标志配置，或创建包含更高级配置的配置文件。

使用命令行

$ ./prometheus-nginxlog-exporter \
  -format="<格式>" \
  -listen-port=4040 \
  -namespace=nginx \
  [日志文件路径...]

使用配置文件

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

安装

有多种安装此导出器的方法。

Docker

此导出器的Docker镜像可在quay.io和pkg.github.com registry获取：

• quay.io/martinhelmich/prometheus-nginxlog-exporter:v1
• docker.pkg.github.com/martin-helmich/prometheus-nginxlog-exporter/exporter:v1

查看https://github.com/martin-helmich/prometheus-nginxlog-exporter/releases%E4%BA%86%E8%A7%A3%E5%8F%AF%E7%94%A8%E7%89%88%E6%9C%AC%E5%8F%8A%E6%8B%89%E5%8F%96%E9%95%9C%E5%83%8F%E7%9A%84%E6%96%B9%E6%B3%95%E3%80%82%E9%80%9A%E5%B8%B8%E5%BB%BA%E8%AE%AE%E4%BD%BF%E7%94%A8%60v1%60%E6%A0%87%E7%AD%BE%E8%80%8C%E9%9D%9E%60latest%60%E3%80%82

按如下方式运行导出器（根据需要调整/path/to/logs和/path/to/config等路径）：

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

命令行标志和参数可直接附加到docker run命令，例如使用配置文件：

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

DEB和RPM包

1.5.1及更新版本的每个https://github.com/martin-helmich/prometheus-nginxlog-exporter/releases%E5%9D%87%E6%8F%90%E4%BE%9BDEB%E5%92%8CRPM%E5%8C%85%E3%80%82

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

包依赖于systemd，并配置为自动运行：

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

包会在/etc/prometheus-nginxlog-exporter.hcl生成配置文件，您可根据需要调整。

使用systemd手动安装

如果不想使用预构建包，可下载二进制文件并手动配置systemd启动。可在https://github.com/martin-helmich/prometheus-nginxlog-exporter/blob/master/res/package/prometheus-nginxlog-exporter.service%E6%89%BE%E5%88%B0%E6%9C%8D%E5%8A%A1%E7%9A%84%E7%A4%BA%E4%BE%8B%E5%8D%95%E5%85%83%E6%96%87%E4%BB%B6%E3%80%82%E5%8F%AA%E9%9C%80%E5%B0%86%E5%8D%95%E5%85%83%E6%96%87%E4%BB%B6%E5%A4%8D%E5%88%B6%E5%88%B0%60/etc/systemd/system%60%EF%BC%9A

$ 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
$ systemctl enable prometheus-nginxlog-exporter
$ systemctl start prometheus-nginxlog-exporter

附带的单元文件期望二进制文件位于/usr/sbin/prometheus-nginxlog-exporter（如果不使用包管理器而手动安装，可能需要放在/usr/local），配置文件位于/etc/prometheus-nginxlog-exporter.hcl。根据需要调整。

Kubernetes

如果在Kubernetes中运行生成日志文件的服务（无论是NGINX还是任何生成类似访问日志的服务），可将导出器作为sidecar与"主"容器在同一pod中运行。

以下示例展示如何将导出器部署为sidecar，通过syslog接收主容器的日志：

yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx-example
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "4040"
spec:
  containers:
    - name: web
      image: nginx
      # ...
    - name: exporter
      image: docker.pkg.github.com/martin-helmich/prometheus-nginxlog-exporter/exporter:v1
      args: ["-config-file", "/etc/prometheus-nginxlog-exporter/config.hcl"]
      volumeMounts:
      - name: exporter-config
        mountPath: /etc/prometheus-nginxlog-exporter
  volumes:
    - name: exporter-config
      configMap:
        name: exporter-config

在此示例中，配置文件通过exporter-config ConfigMap传递。ConfigMap可能如下所示：

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: exporter-config
data:
  config.hcl: |
    listen {
      port = 4040
    }

    namespace "nginx" {
      source = {
        syslog {
          listen_address = "udp://127.0.0.1:5531"
          format = "rfc3164"
        }
      }

      format = "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" \"$http_x_forwarded_for\""

      labels {
        app = "default"
      }
    }

配置文件指示导出器通过syslog接受日志输入。要将日志转发到导出器，只需指示主容器通过syslog将访问日志发送到127.0.0.1:5531（由于主容器和sidecar共享网络命名空间，这是可行的）。

从源码构建

要从源码构建导出器，只需使用go get：

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

或者，克隆此仓库并运行go build：

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

收集的指标

此导出器收集以下指标。收集器可同时监听多个日志文件，并在不同命名空间中发布指标。每个指标使用标签method（包含HTTP请求方法）和status（包含HTTP状态码）。

重要：请注意，其中一些指标需要访问日志格式中存在特定值（例如，http_upstream_time_seconds指标需要访问日志包含变量$upstream_response_time）。

指标在/metrics路径导出。

导出的指标如下：

可在配置文件中配置其他标签（见下文）。

<namespace>可省略或覆盖 - 详见命名空间作为标签。

配置文件

可在启动时指定要读取的配置文件。配置文件预期为https://github.com/hashicorp/hcl%E6%88%96YAML%E6%A0%BC%E5%BC%8F%E3%80%82%E4%BB%A5%E4%B8%8B%E6%98%AF%E7%A4%BA%E4%BE%8B%E6%96%87%E4%BB%B6%EF%BC%9A

HCL格式示例

hcl
listen {
  port = 4040
  address = "10.1.2.3"
  metrics_endpoint = "/metrics"
}

consul {
  enable = true
  address = "localhost:8500"
  datacenter = "dc1"
  scheme = "http"
  token = ""
  service {
    id = "nginx-exporter"
    name = "nginx-exporter"
    address = "192.168.3.1"
    tags = ["foo", "bar"]
  }
}

namespace "app1" {
  format = "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" \"$http_x_forwarded_for\""
  source {
    files = [
      "/var/log/nginx/app1/access.log"
    ]
  }

  # metrics_override = { prefix = "myprefix" }
  # namespace_label = "vhost"

  labels {
    app = "application-one"
    environment = "production"
    foo = "bar"
  }

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

namespace "app2" {
  format = "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" \"$http_x_forwarded_for\" $upstream_response_time"
  source {
    files = [
      "/var/log/nginx/app2/access.log"
    ]
  }
}

YAML格式示例

yaml
listen:
  port: 4040
  address: "10.1.2.3"
  metrics_endpoint: "/metrics"

consul:
  enable: true
  address: "localhost:8500"
  datacenter: dc1
  scheme: http
  token: ""
  service:
    id: "nginx-exporter"
    name: "nginx-exporter"
    address: "192.168.3.1"
    tags: ["foo", "bar"]

namespaces:
  - name: app1
    format: "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" \"$http_x_forwarded_for\""
    source:
      files:
        - /var/log/nginx/app1/access.log
    # metrics_override:
    #   prefix: "myprefix"
    # namespace_label: "vhost"
    labels:
      app: "application-one"
      environment: "production"
      foo: "bar"
    histogram_buckets: [.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10]
  - name: app2
    format: "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" \"$http_x_forwarded_for\" $upstream_response_time"
    source:
      files:
        - /var/log/nginx/app2/access.log

高级功能

命名空间作为标签

出于历史原因，此导出器为不同命名空间导出单独的指标（因为命名空间是指标名称的一部分）。然而，在许多（大多数）情况下，跨不同命名空间使用相同的指标名称（具有不同的日志格式和名称）更为方便。

这可通过两个步骤实现：

1. 将Prometheus指标命名空间覆盖为某个公共前缀（metrics_override）
2. 为nginxlog-exporter的配置命名空间设置标签名称（namespace_label）

hcl
namespace "app1" {
  ...
  metrics_override = { prefix = "myprefix" }
  namespace_label = "vhost"
  ...
}

namespace "app2" {
  ...
  metrics_override = { prefix = "myprefix" }
  namespace_label = "vhost"
  ...
}

导出的指标将具有以下格式：

myprefix_http_response_count_total{vhost="app1", ...}
myprefix_http_response_count_total{vhost="app2", ...}
...

• prefix可设置为""，生成类似http_response_count_total{...}的指标
• namespace_label可省略 - 因此您可完全控制指标格式

有关详细信息和历史，可查看https://github.com/martin-helmich/prometheus-nginxlog-exporter/issues/13%E3%80%82

自定义标签传递

动态重标签的部分情况：

hcl
namespace "app1" {
  format = "$remote_addr - $remote_user [$time_local] ... \"$geoip_country_code\" $upstream_addr"
  ...
  relabel "upstream_addr" { from = "upstream_addr" }
  relabel "country" { from = "geoip_country_code" }
  ...
}

导出的指标将具有upstream_addr和country标签。

日志源

目前，导出器支持从以下来源读取日志数据：

1. 文件
2. syslog

所有日志源可在每个命名空间的基础上使用source属性配置。

从文件读取

从文件读取时，只需配置files属性：

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

从syslog读取

导出器还可打开并监听syslog端口并从中读取日志。配置如下：

hcl
namespace "test" {
  source {
    syslog {
      listen_address = "udp://127.0.0.1:8514" <1>
      format = "rfc3164" <2>
      tags = ["nginx"]
    }

    // ...
  }
}

<1> listen_address可以是TCP或UDP地址。尚不支持UNIX套接字（欢迎提交PR） <2> format可以是rfc3164、rfc5424、rfc6587或auto。如果省略，默认为auto。

查看NGINX文档的相应部分了解如何设置NGINX以记录到syslog。

实验性功能

导出器包含当前处于实验阶段的功能，可能会在不提前通知的情况下更改。要使用这些功能，可设置-enable-experimental标志，或在配置文件中添加enable_experimental选项（在配置文件文档的根级别，如YAML中的enable_experimental: true或HCL中的enable_experimental = true）。

动态重标签

重标签允许您将解析的日志行中的任意字段作为标签添加到指标中。要添加动态标签，在配置文件中添加relabel语句：

hcl
namespace "app-1" {
  // ...

  relabel "host" {
    from = "server_name"
    whitelist = [ <1>
      "host-a.com",