The nginx integration collects connection metrics and access logs. Connection metrics capture the current state of the connection: active, reading, or waiting. Access logs are parsed for their connection details, which include fields mapped to request, client, server, and message.
For more information about nginx, see nginx.org.
Prerequisites
To collect and ingest nginx logs and metrics, you must install Ops Agent version 2.1.0 or higher.
This receiver supports nginx versions 1.18 and 1.20.
Configure your nginx instance
You must enable the stub_status
module in the nginx configuration file to set
up a locally reachable URL, for example, http://www.example.com/status
for the
status page. To enable the stub_status
module, complete the following steps:
Edit the
status.conf
file, or create the file if it doesn't exist. You can find this file in the nginx configuration directory, typically found at/etc/nginx/conf.d
.Add the following lines to the
server
section:location /status { stub_status on; access_log off; allow 127.0.0.1; deny all; }
Your configuration file might look like the following example:
server { listen 80; server_name 127.0.0.1; location /status { stub_status on; access_log off; allow 127.0.0.1; deny all; } location / { root /dev/null; } }
Reload the nginx configuration.
sudo service nginx reload
You can run the following command to automate the previous steps. It creates
a status.conf
file if it doesn't exist or overwrites the existing one if it
does exist. The command turns on stub_status
, reloads nginx, and verifies
that the expected information is exposed through the endpoint.
sudo tee /etc/nginx/conf.d/status.conf > /dev/null << EOF
server {
listen 80;
server_name 127.0.0.1;
location /status {
stub_status on;
access_log off;
allow 127.0.0.1;
deny all;
}
location / {
root /dev/null;
}
}
EOF
sudo service nginx reload
curl http://127.0.0.1:80/status
The sample output is:
Active connections: 1 server accepts handled requests 23 23 74 Reading: 0 Writing: 1 Waiting: 0
Alternately, instead of using a separate status.conf
file, you can also
directly embed the lines to the main nginx.conf
file, which
is typically located in one of the following directories: /etc/nginx
,
/usr/local/nginx/conf
, or /usr/local/etc/nginx
.
Configure the Ops Agent for nginx
Following the guide for Configuring the Ops Agent, add the required elements to collect logs and metrics from your nginx instances, and restart the agent.
Example configuration
The following command creates the configuration file to collect and ingest logs and metrics for nginx and restarts the Ops Agent on Linux.
sudo tee /etc/google-cloud-ops-agent/config.yaml > /dev/null << EOF
logging:
receivers:
nginx_access:
type: nginx_access
nginx_error:
type: nginx_error
service:
pipelines:
nginx:
receivers:
- nginx_access
- nginx_error
metrics:
receivers:
nginx:
type: nginx
stub_status_url: http://127.0.0.1:80/status
service:
pipelines:
nginx:
receivers:
- nginx
EOF
sudo service google-cloud-ops-agent restart
Configure logs collection
To ingest logs from nginx, you must create receivers for the logs nginx produces
and then create a pipeline for the new receivers. To configure a receiver for
your nginx_access
logs, specify the following fields:
Field | Default | Description |
---|---|---|
type |
The value must be nginx_access . |
|
include_paths |
[/var/log/nginx/access.log ] |
The log files to read. |
exclude_paths |
The log files to exclude, if include_paths contains a glob or directory. |
|
wildcard_refresh_interval |
60s |
The interval at which wildcard file paths in include_paths are refreshed. Given as a time duration, for example 30s or 2m . This property might be useful under high logging throughputs where log files are rotated faster than the default interval. |
To configure a receiver for your nginx_error
logs, specify the following
fields:
Field | Default | Description |
---|---|---|
type |
The value must be nginx_error . |
|
include_paths |
[/var/log/nginx/error.log ] |
The log files to read. |
exclude_paths |
The log files to exclude, if include_paths contains a glob or directory. |
|
wildcard_refresh_interval |
60s |
The interval at which wildcard file paths in include_paths are refreshed. Given as a time duration, for example 30s or 2m . This property might be useful under high logging throughputs where log files are rotated faster than the default interval. |
What is logged
The logName
of the nginx_access
and nginx_error
logs are derived from the
receiver IDs specified in the configuration. Detailed fields inside the
LogEntry
are as follows.
nginx_access
logs contain the
httpRequest
field:
Field | Type | Description |
---|---|---|
httpRequest.protocol |
string | Protocol used for the request |
httpRequest.referer |
string | Contents of the Referer header |
httpRequest.remoteIp |
string | Client IP address |
httpRequest.requestMethod |
string | HTTP method |
httpRequest.requestUrl |
string | Request URL (typically just the path part of the URL) |
httpRequest.responseSize |
string (int64 ) |
Response size |
httpRequest.status |
number | HTTP status code |
httpRequest.userAgent |
string | Contents of the User-Agent header |
jsonPayload.host |
string | Contents of the Host header (usually not reported by nginx) |
jsonPayload.user |
string | Authenticated username for the request |
timestamp |
string (Timestamp ) |
Time the request was received |
Log entries don't contain any fields that are blank or missing.
nginx_error
logs contain the following fields in the
LogEntry
:
Field | Type | Description |
---|---|---|
jsonPayload.level |
string | Log entry level |
jsonPayload.pid |
number | Process ID |
jsonPayload.tid |
number | Thread ID |
jsonPayload.connection |
number | Connection ID |
jsonPayload.message |
string | Log message |
jsonPayload.client |
string | Client IP address (optional) |
jsonPayload.server |
string | Nginx server name (optional) |
jsonPayload.request |
string | Original HTTP request (optional) |
jsonPayload.subrequest |
string | Nginx subrequest (optional) |
jsonPayload.upstream |
string | Upstream request URI (optional) |
jsonPayload.host |
string | Host header (optional) |
jsonPayload.referer |
string | Referer header (optional) |
severity |
string (LogSeverity ) |
Log entry level (translated) |
timestamp |
string (Timestamp ) |
Time the entry was logged |
Configure metrics collection
To collect metrics from nginx, you must create a receiver for nginx metrics and then create a pipeline for the new receiver. To configure a receiver for your nginx metrics, specify the following fields:
Field | Default | Description |
---|---|---|
type |
The value must be nginx . |
|
stub_status_url |
http://localhost/status |
The URL exposed by the nginx stub status module. |
collection_interval |
60s |
A time.Duration value, such as 30s or 5m . |
What is monitored
The following table provides the list of metrics that the Ops Agent collects from the nginx instance.
Metric type | |
---|---|
Kind, Type Monitored resources |
Labels |
workload.googleapis.com/nginx.requests
|
|
CUMULATIVE , INT64 gce_instance |
|
workload.googleapis.com/nginx.connections_accepted
|
|
CUMULATIVE , INT64 gce_instance |
|
workload.googleapis.com/nginx.connections_handled
|
|
CUMULATIVE , INT64 gce_instance |
|
workload.googleapis.com/nginx.connections_current
|
|
GAUGE , INT64 gce_instance |
state
|
Sample dashboard
You can view the metrics from this integration using a sample Cloud Monitoring dashboard. Complete the Installing sample dashboards procedures to import the Nginx Overview dashboard from the Sample library and view charts that display your nginx metrics.Verify the configuration
You can use the Logs Explorer and Metrics Explorer to verify that you correctly configured the nginx receiver. It might take one or two minutes for the Ops Agent to begin collecting logs and metrics.
To verify the logs are ingested, go to the Logs Explorer and run the following query to view the nginx logs:
resource.type="gce_instance"
logName=("projects/PROJECT_ID/logs/nginx_error" OR "projects/PROJECT_ID/logs/nginx_access")
To verify the metrics are ingested, go to
Metrics Explorer
and run the following query in the MQL tab.
fetch gce_instance
| metric 'workload.googleapis.com/nginx.requests'
| align rate(1m)
| every 1m
Troubleshooting
On most distributions, nginx comes with ngx_http_stub_status_module
enabled.
You can check if the module is enabled by running the following command:
sudo nginx -V 2>&1 | grep -o with-http_stub_status_module
The expected output is with-http_stub_status_module
, which means the module
is enabled. In rare cases, if the command returns no output, you must compile
nginx from source with the -with-http_stub_status_module
following the nginx
public documentation.