# Overview: NGINX instance metrics


> Understanding how the NGINX Agent collects and reports metrics


## Overview

F5 NGINX Instance Manager collects two types of data:

- **System metrics**: Data about the data plane system, such as CPU and memory usage.
- **Traffic metrics**: Data from processed traffic, including NGINX OSS, NGINX Plus, and NGINX logs.

The NGINX Agent collects metrics every 15 seconds and publishes them every 60 seconds.

For a full list of available metrics, see the [Metrics Catalog Reference](/nim/monitoring/catalogs/metrics.md).

## How metrics are collected and reported

The NGINX Agent collects metrics every 15 seconds while running on the host. Metrics are then downsampled and sent to the Manager server once per minute.

NGINX Instance Manager stores historical data in an analytics database and applies roll-ups:

- Data up to **8 days old** is stored with **1-minute resolution**.
- Data **8 to 30 days old** is stored with **5-minute resolution**.
- Data **30 days to 15 months old** is stored with **1-hour resolution**.
- Data older than **15 months** is stored with **1-day resolution**.

### F5 NGINX Plus metrics

To collect comprehensive metrics for NGINX Plus, including bytes streamed, information about upstream systems and caches, and counts of all HTTP status codes, add the following to your NGINX Plus configuration file, for example `/etc/nginx/nginx.conf` or an included file:

**Note:** 
- By default, all clients can call the API.  
- To limit who can access the API, uncomment the `allow` and `deny` lines under `api write=on` and replace the example CIDR with your trusted network.  
- To restrict write methods (`POST`, `PATCH`, `DELETE`), uncomment and configure the `limit_except GET` block and set up [HTTP basic authentication](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html).  

**Note:** 
If there are issues with NGINX Agent discovering the NGINX Plus API, NGINX Agent can be manually configured with the address of the NGINX Plus API. 

- Add the following configuration to `/etc/nginx-agent/nginx-agent.conf`:
```
data_plane_config:
  nginx:
    api:
      url: "http://127.0.0.1:9000/api"
```
- Restart NGINX Agent for the configuration changes to take affect
```
sudo systemctl restart nginx-agent
```

- Run the following command 
```
sudo journalctl -u nginx-agent | grep "Found NGINX Plus API"
``` 
- Ensure that the following log message is seen 
```
Found NGINX Plus API
```

For more details, see the [NGINX Plus API module](https://nginx.org/en/docs/http/ngx_http_api_module.html) documentation and [Configuring the NGINX Plus API](/nginx/admin-guide/monitoring/live-activity-monitoring.md#configuring-the-api).

### NGINX Open Source metrics

To collect basic metrics about server activity for NGINX Open Source:

1. **Enable the stub status API**

Add the following to your NGINX configuration file:

```nginx
server {
   listen 127.0.0.1:8080;
   location /api {
       stub_status;
       allow 127.0.0.1;
       deny all;
   }
}
```

**Note:** 
Make sure that the `server` and  `location` blocks are in the same configuration file, and not split across multiple files using `include` directives.

This configuration:

- Enables the stub status API endpoint.
- Allows requests only from `127.0.0.1` (localhost).
- Blocks all other requests for security.

For more details, see the [NGINX Stub Status module documentation](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html).

2. **Configure access logging** 

Enable access logging in your NGINX configuration to collect detailed traffic metrics. Ensure that the following log format is used:

```nginx
log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for" '
'"$bytes_sent" "$request_length" "$request_time" '
'"$gzip_ratio" $server_protocol ';

access_log  /var/log/nginx/access.log  main;
```

This log format captures key metrics including request timing, response sizes, and client information.

After saving the changes, reload NGINX to apply the new configuration:

```shell
nginx -s reload
```

## Troubleshooting

System metrics are collected automatically by the NGINX Agent. To collect NGINX-specific metrics, additional configuration is required.