Documentation forAppOptics

NGINX PLUS API

Overview

NGINX Plus is a paid version of open source NGINX web server with a strong focus on high concurrency, performance and low memory usage. It's one of the most popular web servers on the internet, and can also act as a reverse proxy, a load balancer, or as an HTTP cache.

The SolarWinds Snap Agent allows you to easily monitor the health of your NGINX Plus service(s) over ngx_http_api_module.

This integration is currently available for Windows and Linux platforms.

Setup

The nginx monitoring is accomplished by bridge plugin which is included with the SolarWinds Snap Agent by default. Please follow the directions below to enable it for a agent instance. The bridge plugin utilize Telegraf NGINX Plus API plugin.

Prerequisites

Your NGINX Plus server will need a location defined with the ngx_http_api_module activated. Please refer to module documentation for more details on enabling API.

Configuration

The agent provides an example task file to help you get started quickly, but requires you to provide the correct settings for your NGINX Plus installation. To enable the task:

  1. Make a copy of the NGINX Plus API example task file task-bridge-nginx_plus_api.yaml.example, renaming it to task-bridge-nginx_plus_api.yaml:

    On Windows, using Explorer or PowerShell:

    Copy
    > copy "C:\ProgramData\SolarWinds\Snap\tasks-autoload.d\task-bridge-nginx_plus_api.yaml.example" "C:\ProgramData\SolarWinds\Snap\tasks-autoload.d\task-bridge-nginx_plus_api.yaml"

    On Linux using command line:

    Copy
    $ sudo cp /opt/SolarWinds/Snap/etc/tasks-autoload.d/task-bridge-nginx_plus_api.yaml.example /opt/SolarWinds/Snap/etc/tasks-autoload.d/task-bridge-nginx_plus_api.yaml
  2. Edit the task file with settings specific to your NGINX Plus install:

    If you wish to also collect logs for this service, uncomment the last section in the example task file. For more information on collecting logs, see the logs collector docs.

    Copy
    ---
    version: 2

    schedule:
      type: cron
      interval: "0 * * * * *"
      
    plugins:
      - plugin_name: bridge
      
        config:
          nginx_plus_api:
            ## An array of API URI to gather stats.
            urls:
              - http://localhost/api
              
            ## Nginx API version, default: 3
            # api_version: 3
            ## Optional TLS Config
            # tls_ca: /path/to/cafile
            # tls_cert: /path/to/certfile
            # tls_key: /path/to/keyfile
            
            ## Use TLS but skip chain & host verification
            # insecure_skip_verify: false
            ## HTTP response timeout (default: 5s)
            response_timeout: "5s"
            
        publish:
          - plugin_name: publisher-appoptics
          
    ## If you want to gather logs for this integration, uncomment the following section.
    #  - plugin_name: logs
    #    config:
    #      sources:
    #        log_files:
    #          file_paths:
    #            - path: /var/log/nginx/access.log
    #            - path: /var/log/nginx/error.log
    #    publish:
    #     - plugin_name: publisher-appoptics
  3. Restart the agent:

    On Windows command line:

    Copy
    > net stop swisnapd
    > net start swisnapd

    On Linux command line:

    Copy
    $ sudo service swisnapd restart
  4. Enable the NGINX Plus API integration in AppOptics

    On the Integrations Page you will see NGINX Plus API integration available if the previous steps were successful. It may take a couple minutes before the NGINX Plus API integration is identified. Select the NGINX Plus API integration to open the configuration menu in the UI, and enable it. If you do not see it, see Troubleshooting Linux.

Testing Integration

To check if and what metrics can be collected with given configuration, run bridge plugin in debug mode:

On Windows command line:

Copy
> "C:\Program Files\SolarWinds\Snap\bin\snap-plugin-collector-bridge.exe" --debug-mode --plugin-config "{\"nginx_plus_api\": {\"urls\": [\"http://localhost/api\"]}}"

On Linux command line:

Copy
$ /opt/SolarWinds/Snap/bin/snap-plugin-collector-bridge --debug-mode --plugin-config "{\"nginx_plus_api\": {\"urls\": [\"http://localhost/api\"]}}"

Metrics and Tags

Metrics

The table below lists each of the metrics collected by the NGINX Plus integration. By default, all metrics are collected if they are available. To filter desired ones, please refer to Metric Format for more details.

Name
nginx_plus_api.processes.respawned
nginx_plus_api.connections.accepted
nginx_plus_api.connections.dropped
nginx_plus_api.connections.active
nginx_plus_api.connections.idle
nginx_plus_api.ssl.handshakes
nginx_plus_api.ssl.handshakes_failed
nginx_plus_api.ssl.session_reuses
nginx_plus_api.http_requests.total
nginx_plus_api.http_requests.current
nginx_plus_api.http_server_zones.processing
nginx_plus_api.http_server_zones.requests
nginx_plus_api.http_server_zones.responses_1xx
nginx_plus_api.http_server_zones.responses_2xx
nginx_plus_api.http_server_zones.responses_3xx
nginx_plus_api.http_server_zones.responses_4xx
nginx_plus_api.http_server_zones.responses_5xx
nginx_plus_api.http_server_zones.responses_total
nginx_plus_api.http_server_zones.received
nginx_plus_api.http_server_zones.send
nginx_plus_api.http_server_zones.discarded
nginx_plus_api.http_upstreams.keepalive
nginx_plus_api.http_upstreams.zombies
nginx_plus_api.http_upstream_peers.requests
nginx_plus_api.http_upstream_peers.unavail
nginx_plus_api.http_upstream_peers.healthchecks_checks
nginx_plus_api.http_upstream_peers.header_time
nginx_plus_api.http_upstream_peers.state
nginx_plus_api.http_upstream_peers.response_time
nginx_plus_api.http_upstream_peers.active
nginx_plus_api.http_upstream_peers.healthchecks_last_passed
nginx_plus_api.http_upstream_peers.weight
nginx_plus_api.http_upstream_peers.responses_1xx
nginx_plus_api.http_upstream_peers.responses_2xx
nginx_plus_api.http_upstream_peers.responses_3xx
nginx_plus_api.http_upstream_peers.responses_4xx
nginx_plus_api.http_upstream_peers.responses_5xx
nginx_plus_api.http_upstream_peers.received
nginx_plus_api.http_upstream_peers.healthchecks_fails
nginx_plus_api.http_upstream_peers.healthchecks_unhealthy
nginx_plus_api.http_upstream_peers.backup
nginx_plus_api.http_upstream_peers.responses_total
nginx_plus_api.http_upstream_peers.sent
nginx_plus_api.http_upstream_peers.fails
nginx_plus_api.http_upstream_peers.downtime
nginx_plus_api.http_caches.size
nginx_plus_api.http_caches.max_size
nginx_plus_api.http_caches.cold
nginx_plus_api.http_caches.hit_responses
nginx_plus_api.http_caches.hit_bytes
nginx_plus_api.http_caches.stale_responses
nginx_plus_api.http_caches.stale_bytes
nginx_plus_api.http_caches.updating_responses
nginx_plus_api.http_caches.updating_bytes
nginx_plus_api.http_caches.revalidated_responses
nginx_plus_api.http_caches.revalidated_bytes
nginx_plus_api.http_caches.miss_responses
nginx_plus_api.http_caches.miss_bytes
nginx_plus_api.http_caches.miss_responses_written
nginx_plus_api.http_caches.miss_bytes_written
nginx_plus_api.http_caches.expired_responses
nginx_plus_api.http_caches.expired_bytes
nginx_plus_api.http_caches.expired_responses_written
nginx_plus_api.http_caches.expired_bytes_written
nginx_plus_api.http_caches.bypass_responses
nginx_plus_api.http_caches.bypass_bytes
nginx_plus_api.http_caches.bypass_responses_written
nginx_plus_api.http_caches.bypass_bytes_written
nginx_plus_api.stream_upstreams.zombies
nginx_plus_api.stream_upstream_peers.unavail
nginx_plus_api.stream_upstream_peers.healthchecks_checks
nginx_plus_api.stream_upstream_peers.healthchecks_fails
nginx_plus_api.stream_upstream_peers.healthchecks_unhealthy
nginx_plus_api.stream_upstream_peers.healthchecks_last_passed
nginx_plus_api.stream_upstream_peers.response_time
nginx_plus_api.stream_upstream_peers.state
nginx_plus_api.stream_upstream_peers.active
nginx_plus_api.stream_upstream_peers.weight
nginx_plus_api.stream_upstream_peers.received
nginx_plus_api.stream_upstream_peers.backup
nginx_plus_api.stream_upstream_peers.sent
nginx_plus_api.stream_upstream_peers.fails
nginx_plus_api.stream_upstream_peers.downtime
nginx_plus_api.stream_server_zones.processing
nginx_plus_api.stream_server_zones.connections
nginx_plus_api.stream_server_zones.received
nginx_plus_api.stream_server_zones.sent
nginx_plus_api.location_zones.requests
nginx_plus_api.location_zones.responses_1xx
nginx_plus_api.location_zones.responses_2xx
nginx_plus_api.location_zones.responses_3xx
nginx_plus_api.location_zones.responses_4xx
nginx_plus_api.location_zones.responses_5xx
nginx_plus_api.location_zones.responses_total
nginx_plus_api.location_zones.received
nginx_plus_api.location_zones.sent
nginx_plus_api.location_zones.discarded
nginx_plus_api.resolver_zones.name
nginx_plus_api.resolver_zones.srv
nginx_plus_api.resolver_zones.addr
nginx_plus_api.resolver_zones.noerror
nginx_plus_api.resolver_zones.formerr
nginx_plus_api.resolver_zones.servfail
nginx_plus_api.resolver_zones.nxdomain
nginx_plus_api.resolver_zones.notimp
nginx_plus_api.resolver_zones.refused
nginx_plus_api.resolver_zones.timedout
nginx_plus_api.resolver_zones.unknown

Tags

The table below lists tags available for the NGINX Plus metrics.

Tag Name Metric Groups
hostname (@host) all metrics
source all metrics
port all metrics
id upstream_peers, stream_upstream_peers
upstream http_upstreams, stream_upstreams, upstream_peers, stream_upstream_peers
upstream_address upstream_peers, stream_upstream_peers
zone http_server_zones, upstream_server_zones, http_location_zones, resolver_zones

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.