sematext-agent-nginx

SPM Agent for monitoring Nginx

Usage no npm install needed!

<script type="module">
  import sematextAgentNginx from 'https://cdn.skypack.dev/sematext-agent-nginx';
</script>

README

Build Status

This is the NGINX monitoring Agent for Sematext Cloud

Preparation

  1. Get a free Sematext account

  2. Create a Monitoring App of type "Nginx" and copy the SPM App Token - or execute the commands displayed in the Sematext UI (which are described here as well)

  3. Install Node.js on your Nginx server

  4. Activate Nginx stub_status module in the server section e.g. in /etc/nginx/sites-enabled/default:

location /nginx_status {
  # Turn on nginx stats
  stub_status on;
  # I do not need logs for stats
  access_log   off;
  # Security: Please use you local IP address instead ...
  allow all;
}

Optional preparation for PHP FastCGI Process Manager (FPM): To add monitoring for PHP-FPM follow these instructions.

Setup

# Install sematext-agent-nginx 
npm i sematext-agent-nginx -g
# If you use Sematext Cloud EU, set region for API endpoints
# sematext-nginx-setup -r EU
# Install systemd or upstart service file for sematext-agent-nginx 
sematext-nginx-setup -t YOUR_SPM_TOKEN_HERE -n http://localhost/nginx_status

Configuration

The setup script stores the configuration in /etc/sematext/sematext-agent-nginx.config

In case you want to change settings later edit /etc/sematext/sematext-agent-nginx.config. A typical case is to add receiver URL for On-Premises installation of SPM in the config file:

# default value for SaaS / Sematext Cloud: https://spm-receiver.sematext.com:443/receiver/v1/_bulk
spmSenderBulkInsertUrl: http://your-spm-server:8084/_bulk
# default value for SaaS / Sematext Cloud: https://event-receiver.sematext.com
eventsReceiverUrl:  http://your-spm-server:8083

Restart the Sematext Nginx Agent after config changes, depending on the init system:

  • Upstart (Ubuntu):
    sudo service sematext-agent-nginx restart
  • Systemd (Linux others):
    sudo systemctl stop sematext-agent-nginx
    sudo systemctl start sematext-agent-nginx
  • Launchd (Mac OS X):
    sudo launchctl stop com.sematext.sematext-agent-nginx
    sudo launchctl stop com.sematext.sematext-agent-nginx

For tests you can just run the agent from command line:

sematext-agent-nginx --config /etc/sematext/sematext-agent-nginx.config

Results

NGINX Metrics in Sematext:

Docker

Sematext Agent for Nginx includes a docker file and startup script to build a Docker image.

git clone https://github.com/sematext/sematext-agent-nginx.git
cd sematext-agent-nginx
docker build -t sematext/sematext-agent-nginx .

The Sematext Nginx Agent supports following parameters on Docker:

Environment Variable Description
Required parameters
SPM_TOKEN your SPM Token for the Nginx SPM App
NGINX_STATUS_URL the URL to Nginx server, delivering the stats (see Nginx configuration above). Please note the servername/ip must be reachable from the agent container. You might need to use --link nginx-container-name to create the network link. NGINX_STATUS_URL is not required with DOCKER_AUTO_DISCOVERY.
Docker auto discovery Detect new nginx containers for monitoring!
DOCKER_AUTO_DISCOVERY Enable auto discovery of containers e.g. DOCKER_AUTO_DISCOVERY=true
SPM_DOCKER_NETWORK Name of the network to be used for HTTP queries to nginx. If this is set to "host" and docker run parameter --net=host the connection is made to the exposed ports. If this is not set or any other network name (e.g. bridge) the connection is done via nginx container IP address and 'internal' port 80 (used inside the nginx container). This feature works only when the Docker socket is mounted with -v /var/run/docker.sock:/var/run/docker.sock
NGINX_STATUS_PATH Location of the nginx status page e.g. "/nginx_status"
PHP_FPM_STATUS_PATH Location of the PHP FPM status page e.g. "/status"
IMAGE_NAME_PATTERN Regular expression to match nginx image name. Default value 'nginx'
General parameters
HTTPS_PROXY Url to HTTPS proxy if the agent runs behind a firewall
SPM_RECEIVER_URL Optional for SPM On-Premises, default value: https://spm-receiver.sematext.com:443/receiver/v1/_bulk for On-Premises receiver use http://your-spm-server:8084
EVENTS_RECEIVER_URL Optional for SPM On-Premises, default value: https://event-receiver.sematext.com. For On-Premises use http://your-spm-server:8083

Example:

docker run --name sematext-agent-nginx -e SPM_TOKEN=YOUR_SPM_NGINX_TOKEN_HERE  \ 
-e NGINX_STATUS_URL=http://nginx-server/nginx_status \ 
-d  sematext/sematext-agent-nginx

Example with auto discovery of nginx containers via Docker API:

docker run --name sematext-agent-nginx \
-e SPM_TOKEN=YOUR_SPM_NGINX_TOKEN_HERE \
-e NGINX_STATUS_PATH=/nginx_Status \
-e DOCKER_AUTO_DISCOVERY=true \
--net=host -e SPM_DOCKER_NETWORK=host \
-v /var/run/docker.sock:/var/run/docker.sock -d \
sematext/sematext-agent-nginx

Support