Skip to Content

Monitor a private API gateway with ManageEngine Site24x7

Introduction

This guide describes how to expose the OpenResty NGINX-based connection and request metrics of a private API gateway and collect them with the ManageEngine Site24x7 NGINX plugin.

When configured, Site24x7 reports the following metrics for the gateway:

  • Active client connections.
  • Connections where the gateway is reading a request header.
  • Connections where the gateway is writing a response to the client.
  • Idle client connections that are waiting for a request.
  • Total client requests.
  • Successfully handled client connections.
  • Dropped connections.

These metrics come from the NGINX stub_status module, which is installed with the private API gateway but not enabled by default. The gateway also provides built-in /version, /healthcheck, and /stats endpoints that report the gateway version, availability, disk space, and cache performance. For more information, see Monitor a private API gateway.

Prerequisites

  • A private API gateway installed on Linux or running on Docker, with root or sudo access to the gateway host.
  • A Site24x7 account.
  • The Site24x7 Linux agent installed on the gateway host.
  • Python 3 or later on the gateway host, which the Site24x7 NGINX plugin requires.

Enable the NGINX status endpoint

These steps add an /nginx_status endpoint to the private API gateway and protect it with basic authentication.

Set the status credentials

The /nginx_status endpoint reads its user names and password hashes from the file /usr/local/openresty/nginx/conf/opstatsauth.conf. Each line of the file holds one user in the format username:password-hash.

  1. Run the following command, replacing USERNAME and PASSWORD with the credentials that Site24x7 will use. This command replaces the file, so the default credentials no longer work.

    echo "USERNAME:$(openssl passwd -6 'PASSWORD')" | sudo tee /usr/local/openresty/nginx/conf/opstatsauth.conf
    
  2. To add more users, add each one on its own line. Make sure the file ends with a newline character before you add a line, otherwise the new entry merges with the previous line and neither user can sign in.

Caution

Do not append credentials to the nginx_status.conf file. That file contains the endpoint configuration, not the user list.

Create the status configuration file

Create the file /usr/local/openresty/nginx/conf/onpremise/nginx_status.conf with the following contents:

access_log off;
auth_basic "Restricted";
auth_basic_user_file /usr/local/openresty/nginx/conf/opstatsauth.conf;
stub_status on;

Add the endpoint to the gateway configuration

  1. Open the file /usr/local/openresty/nginx/conf/onpremise.conf.

  2. After the location = /stats {...} block, add the following block:

    location /nginx_status {
        include /usr/local/openresty/nginx/conf/onpremise/nginx_status.conf;
    }
    
  3. Save the file.

Important

A private API gateway upgrade overwrites onpremise.conf. Create a backup of the file, and add the location /nginx_status block again after each upgrade.

Restart the gateway

Restart the private API gateway to apply the changes:

jitterbit-api-gateway-config -s restart

If the gateway does not start, check /usr/local/openresty/nginx/logs/error.log for configuration errors, such as unexpected end of file, and correct the files you edited.

Test the endpoint

From the gateway host, make a request with the credentials you set:

curl -u USERNAME:PASSWORD http://localhost/nginx_status

A successful response looks similar to the following:

Active connections: 2
server accepts handled requests
 120 120 340
Reading: 0 Writing: 1 Waiting: 1

A 401 response indicates incorrect credentials. If you receive a different response, confirm that the location block is in onpremise.conf and that the gateway restarted without errors.

Install the Site24x7 NGINX plugin

  1. On the gateway host, create a directory named nginx, and download the plugin files nginx.py and nginx.cfg from the Site24x7 NGINX plugin repository into it. Then set the first line of nginx.py to the path of your Python 3 interpreter:

    mkdir nginx
    cd nginx/
    wget https://raw.githubusercontent.com/site24x7/plugins/master/nginx/nginx.py && sed -i "1s|^.*|#! $(which python3)|" nginx.py
    wget https://raw.githubusercontent.com/site24x7/plugins/master/nginx/nginx.cfg
    
  2. Test that the plugin can read the gateway metrics:

    python3 nginx.py --nginx_status_url "http://localhost/nginx_status" --username "USERNAME" --password "PASSWORD"
    

    The command returns JSON that contains the metrics. If it returns an error, return to Test the endpoint.

  3. In nginx.cfg, set the following values under the [nginx] section:

    nginx_status_url = "http://localhost/nginx_status"
    username = "USERNAME"
    password = "PASSWORD"
    

    The plugin sends basic authentication only when both username and password are set, and it applies the timeout value (60 seconds by default) to each request.

  4. Move the nginx directory to /opt/site24x7/monagent/plugins/.

The Site24x7 agent detects the plugin within about five minutes. To view the metrics, in Site24x7 go to Plugins and select Plugin Integrations.

Monitor gateway availability

The NGINX plugin reports connection and request metrics, but not whether the gateway can log in to Harmony. To monitor availability, also add a Site24x7 website monitor for the gateway's /healthcheck endpoint. For more information about this endpoint, see Check the gateway health.

In Site24x7, go to Web and select Website, then configure the monitor:

  • Webpage URL: Enter the URL of the /healthcheck endpoint.
  • HTTP Method: Select GET. A HEAD request checks only that the URL responds.
  • Monitoring Locations: Select a global location only if Site24x7 can reach the gateway over the internet. Otherwise, use a Site24x7 On-Premise Poller that is on the same network as the gateway.
  • Accepted HTTP status codes: Accept 200 only. The endpoint returns 400 when the Harmony login fails.

For more information about these settings, see the Site24x7 documentation on adding a website monitor.

You can also add a content check for the text Health check complete and was a success.