A collectd plugin to collect NGINX Plus stats and metrics. Uses collectd's Python plugin.

1. Checkout this repository somewhere on your system accessible by collectd. The suggested location is /usr/share/collectd/.
2. Install the Python requirements with sudo pip install -r install_requirements.txt
3. Configure the plugin (see below)
4. Restart collectd

Within the plugin's Module block plugin-specific configuration options can be given. The available configuration options are detailed below.

Example addition to the collectd configuration:

LoadPlugin python

<Plugin python>
  ModulePath "/usr/share/collectd/collectd-nginx-plus/plugin"
  Import nginx_plus_collectd

  <Module nginx_plus_collectd>
    StatusHost "localhost"
    StatusPort "8080"
    DebugLogLevel true
    Username "user_1"
    Password "my_password"
    Dimension "extra_dimension_name_1" "extra_dimension_value_1"
    Dimension "extra_dimension_name_2" "extra_dimension_value_2"
  </Module>
</Plugin>

By default only a subset of the available metrics are published by default. The remaining metrics can be enabled by opting-in to additional metric groups. The metrics in each group are listed below, along with the dimensions added to each group. By default all metrics are decorated with the nginx.version dimension.

These metrics are published by default.

All server zone metrics are decorated with dimension server.zone.name . To include these metrics, add ServerZone true to the plugin configuration, e.g.

  <Module nginx_plus_collectd>
    StatusHost "localhost"
    StatusPort "8080"
    ServerZone true
  </Module>

• server.zone.processing
• server.zone.discarded

All memory zone metrics are decorated with dimension memory.zone.name . To include these metrics, add MemoryZone true to the plugin configuration, e.g.

  <Module nginx_plus_collectd>
    StatusHost "localhost"
    StatusPort "8080"
    MemoryZone true
  </Module>

• zone.pages.used
• zone.pages.free

All upstream metrics are decorated with dimensions upstream.name and upstream.peer.name . To include these metrics, add Upstream true to the plugin configuration, e.g.

  <Module nginx_plus_collectd>
    StatusHost "localhost"
    StatusPort "8080"
    Upstream true
  </Module>

• upstreams.active
• upstreams.fails
• upstreams.unavailable
• upstreams.health.checks.checks
• upstreams.health.checks.fails
• upstreams.health.checks.unhealthy
• upstreams.header.time
• upstreams.keepalive
• upstreams.zombies

All cache metrics are decorated with dimension cache.name . To include these metrics, add Cache true to the plugin configuration, e.g.

  <Module nginx_plus_collectd>
    StatusHost "localhost"
    StatusPort "8080"
    Cache true
  </Module>

• caches.hit.responses
• caches.miss.responses
• caches.stale.responses
• caches.updating.responses
• caches.revalidated.responses
• caches.expired.responses
• caches.bypass.responses
• caches.hit.bytes
• caches.miss.bytes
• caches.stale.bytes
• caches.updating.bytes
• caches.revalidated.bytes
• caches.expired.bytes
• caches.bypass.bytes
• caches.miss.responses.written
• caches.expired.responses.written
• caches.bypass.responses.written
• caches.miss.bytes.written
• caches.expired.bytes.written
• caches.bypass.bytes.written

All stream server zone metrics are decorated with dimension stream.server.zone.name . To include these metrics, add StreamServerZone true to the plugin configuration, e.g.

  <Module nginx_plus_collectd>
    StatusHost "localhost"
    StatusPort "8080"
    StreamServerZone true
  </Module>

• stream.server.zone.connections
• stream.server.zone.processing
• stream.server.zone.sessions.2xx
• stream.server.zone.sessions.4xx
• stream.server.zone.sessions.5xx
• stream.server.zone.received
• stream.server.zone.sent
• stream.server.zone.discarded

All stream upstream metrics are decorated with dimensions stream.upstream.name and stream.upstream.peer.name. To include these metrics, add StreamUpstream true to the plugin configuration, e.g.

  <Module nginx_plus_collectd>
    StatusHost "localhost"
    StatusPort "8080"
    StreamUpstream true
  </Module>

• stream.upstreams.connections
• stream.upstreams.active
• stream.upstreams.connections.max
• stream.upstreams.bytes.sent
• stream.upstreams.bytes.received
• stream.upstreams.fails
• stream.upstreams.unavailable
• stream.upstreams.health.checks.checks
• stream.upstreams.health.checks.fails
• stream.upstreams.health.checks.unhealthy
• stream.upstreams.response.time
• stream.upstreams.downtime
• stream.upstreams.bytes.received
• stream.upstreams.bytes.sent
• stream.upstreams.zombies

Process metrics only include the default dimensions. To include these metrics, add Processes true to the plugin configuration, e.g.

  <Module nginx_plus_collectd>
    StatusHost "localhost"
    StatusPort "8080"
    Processes true
  </Module>

• processes.respawned

Before making changes to the plugin, it is highly recommended first create a virtual Python environment. This can be done with virtualenv. This helps avoid dependency conflicts, preserves your global site-packages and helps catch missing dependencies in the pip requirements.txts.

The dependencies needed for local development (running unit tests, etc.) are contained in dev_requirements.txt and can be installed via pip: pip install -r dev_requirements.txt.

A quick way to run the plugin locally and consume from a rich data source is to configure it to read from the NGINX+ demo: ./nginx_plus_collectd.py 'demo.nginx.com' 80

Running the unit tests is done via a recipe in the makefile, the command: make test. The unit tests are run with nose inside a virtual environment managed by tox. The test_requirements.txt contains all the testing dependencies and is used to pip install everything needed by the tests in the tox environments (tox installs these dependencies).

The make check command will run pylint with standards defined in pylintrc. Having a slight drop in code rating is not a blocker for changes, but a significant drop should be addressed. This is a measurable way to enforce style and standards.

Run make clean to remove artifacts leftover by tox and pylint.