diff --git a/content/includes/nginx-one-console/config-snippets/enable-nplus-api-dashboard.md b/content/includes/nginx-one-console/config-snippets/enable-nplus-api-dashboard.md index 02967dbd9..6bd0eaab3 100644 --- a/content/includes/nginx-one-console/config-snippets/enable-nplus-api-dashboard.md +++ b/content/includes/nginx-one-console/config-snippets/enable-nplus-api-dashboard.md @@ -36,3 +36,7 @@ server { } } ``` + +{{}} +Make sure that the `server` and `location` blocks are in the same configuration file, and not split across multiple files using `include` directives. +{{}} diff --git a/content/includes/use-cases/monitoring/enable-nginx-oss-metrics.md b/content/includes/use-cases/monitoring/enable-nginx-oss-metrics.md new file mode 100644 index 000000000..f9c399796 --- /dev/null +++ b/content/includes/use-cases/monitoring/enable-nginx-oss-metrics.md @@ -0,0 +1,53 @@ +--- +nd-product: MSC +nd-files: +- content/nginx-one-console/getting-started.md +- content/nginx-one-console/nginx-configs/metrics/enable-metrics.md +- content/nim/monitoring/overview-metrics.md +- content/nim/nginx-instances/add-instance.md +--- + +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; + } +} +``` + +{{}} +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. diff --git a/content/includes/use-cases/monitoring/enable-nginx-oss-stub-status.md b/content/includes/use-cases/monitoring/enable-nginx-oss-stub-status.md deleted file mode 100644 index 3b137a8ff..000000000 --- a/content/includes/use-cases/monitoring/enable-nginx-oss-stub-status.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -nd-product: MSC -nd-files: -- content/nginx-one-console/getting-started.md -- content/nginx-one-console/nginx-configs/metrics/enable-metrics.md -- content/nim/monitoring/overview-metrics.md -- content/nim/nginx-instances/add-instance.md ---- - -To collect basic metrics about server activity for NGINX Open Source, 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; - } -} -``` - -This configuration: - -- Enables the stub status API. -- 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). \ No newline at end of file diff --git a/content/includes/use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md b/content/includes/use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md index de8a33842..74e405367 100644 --- a/content/includes/use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md +++ b/content/includes/use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md @@ -12,7 +12,19 @@ nd-files: 5. In the **File name** box, enter `/etc/nginx/conf.d/dashboard.conf`, then select **Add**. 6. Paste the following into the new file workspace: -{{< include "nginx-one-console/config-snippets/enable-nplus-api-dashboard.md" >}} + +{{}} + +{{%tab name="without SSL"%}} +{{< include "/nginx-one-console/config-snippets/enable-nplus-api-dashboard.md" >}} + +{{% /tab %}} +{{%tab name="with SSL"%}} + +{{< include "/use-cases/monitoring/enable-nginx-plus-api-with-ssl.md" >}} + +{{% /tab %}} +{{% /tabs %}} 7. Select **Next**, review the diff, then select **Save and Publish**. 8. Open your browser to `http://:9000/dashboard.html` (replace `` with the IP or hostname of one of your group members). You should see the NGINX Plus dashboard. \ No newline at end of file diff --git a/content/includes/use-cases/monitoring/enable-nginx-plus-api-with-ssl.md b/content/includes/use-cases/monitoring/enable-nginx-plus-api-with-ssl.md new file mode 100644 index 000000000..1f8ae3fb8 --- /dev/null +++ b/content/includes/use-cases/monitoring/enable-nginx-plus-api-with-ssl.md @@ -0,0 +1,76 @@ +--- +nd-product: MSC +nd-files: +- content/nginx-one-console/getting-started.md +--- + +If SSL is enabled on the NGINX Plus API with self-signed certificates like this example: + +```nginx +# This block enables the NGINX Plus API and dashboard with SSL +# For configuration and security recommendations, see: +# https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#configuring-the-api +server { + # Change the listen port if 9000 conflicts + # (8080 is the conventional API port) + listen 9000 ssl; + ssl_certificate /etc/nginx/certs/nginx-selfsigned.crt; + ssl_certificate_key /etc/nginx/certs/nginx-selfsigned.key; + + location /api/ { + # To restrict write methods (POST, PATCH, DELETE), uncomment: + # limit_except GET { + # auth_basic "NGINX Plus API"; + # auth_basic_user_file /path/to/passwd/file; + # } + + # Enable API in write mode + api write=on; + + # To restrict access by network, uncomment the following lines and set your network: + # allow 192.0.2.0/24; # replace with your network + # allow 127.0.0.1/32; # allow local NGINX Agent to call the NGINX Plus API to retrieve metrics + # deny all; + } + + # Serve the built-in dashboard at /dashboard.html + location = /dashboard.html { + root /usr/share/nginx/html; + } +} +``` + +{{}} +Make sure that the `server` and `location` blocks are in the same configuration file, and not split across multiple files using `include` directives. +{{}} + +{{}} +To enable NGINX Agent to call the NGINX Plus API, follow the steps below: +- Add the following configuration to `/etc/nginx-agent/nginx-agent.conf`: +``` +data_plane_config: + nginx: + api_tls: + ca: "/etc/nginx/certs/nginx-selfsigned.crt" +``` +- 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 "NGINX Plus API" +``` +- Ensure that the following log message is seen +``` +NGINX Plus API found, NGINX Plus receiver enabled to scrape metrics +``` +{{}} + +{{}} +Here is an example of how to generate self-signed certificates +``` +openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/certs/nginx-selfsigned.key -out /etc/nginx/certs/nginx-selfsigned.crt -subj "/CN=localhost" -addext "subjectAltName=IP:127.0.0.1" +``` +{{}} \ No newline at end of file diff --git a/content/nginx-one-console/getting-started.md b/content/nginx-one-console/getting-started.md index dcfbfbc0e..b1ec6338d 100644 --- a/content/nginx-one-console/getting-started.md +++ b/content/nginx-one-console/getting-started.md @@ -159,13 +159,24 @@ The `install` script writes an `nginx-agent.conf` file to the `/etc/nginx-agent/ The NGINX One Console dashboard relies on APIs for NGINX Plus and NGINX Open Source Stub Status to report traffic and system metrics. The following sections show you how to enable those metrics. -### Enable NGINX Plus API +### Enable NGINX Plus Metrics +{{}} + +{{%tab name="without SSL"%}} {{< include "/use-cases/monitoring/enable-nginx-plus-api.md" >}} -### Enable NGINX Open Source Stub Status API +{{% /tab %}} +{{%tab name="with SSL"%}} + +{{< include "/use-cases/monitoring/enable-nginx-plus-api-with-ssl.md" >}} + +{{% /tab %}} +{{% /tabs %}} -{{< include "/use-cases/monitoring/enable-nginx-oss-stub-status.md" >}} +### Enable NGINX Open Source Metrics + +{{< include "/use-cases/monitoring/enable-nginx-oss-metrics.md" >}} --- @@ -181,10 +192,3 @@ After connecting your NGINX instances to NGINX One, you can monitor their perfor ### Overview of the NGINX One dashboard {{< include "/use-cases/monitoring/n1c-dashboard-overview.md" >}} - - - - - - - diff --git a/content/nginx-one-console/nginx-configs/metrics/enable-metrics.md b/content/nginx-one-console/nginx-configs/metrics/enable-metrics.md index 9d447eff7..60f75c9fb 100644 --- a/content/nginx-one-console/nginx-configs/metrics/enable-metrics.md +++ b/content/nginx-one-console/nginx-configs/metrics/enable-metrics.md @@ -12,27 +12,32 @@ nd-content-type: tutorial nd-product: NONECO --- -The NGINX One Console dashboard and metrics views present system metrics and detailed NGINX metrics gathered through the NGINX Plus API or the Stub Status API (for NGINX Open Source). +The NGINX One Console dashboard and metrics views present system metrics and detailed NGINX metrics gathered through the NGINX Plus API or the Stub Status API and NGINX access log (for NGINX Open Source). -To display metrics, complete the following steps: -1. Enable the API -2. Enable metric collection +## Enable NGINX Plus Metrics -## Enable NGINX Plus API and dashboard +### Enable NGINX Plus API and dashboard +{{}} + +{{%tab name="without SSL"%}} {{< include "/use-cases/monitoring/enable-nginx-plus-api.md" >}} -## Enable NGINX Plus API and dashboard with Config Sync Groups +{{% /tab %}} +{{%tab name="with SSL"%}} -To enable the NGINX Plus API and dashboard with [Config Sync Groups]({{< ref "/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}), add a file named `/etc/nginx/conf.d/dashboard.conf` to your shared group config. Any instance you add to that group automatically uses those settings. +{{< include "/use-cases/monitoring/enable-nginx-plus-api-with-ssl.md" >}} -{{< include "use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md" >}} +{{% /tab %}} +{{% /tabs %}} + +### Enable NGINX Plus API and dashboard with Config Sync Groups -## Enable NGINX Open Source Stub Status API +To enable the NGINX Plus API and dashboard with [Config Sync Groups]({{< ref "/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}), add a file named `/etc/nginx/conf.d/dashboard.conf` to your shared group config. Any instance you add to that group automatically uses those settings. -{{< include "/use-cases/monitoring/enable-nginx-oss-stub-status.md" >}} +{{< include "use-cases/monitoring/enable-nginx-plus-api-with-config-sync-group.md" >}} -## Enable NGINX Plus Metric Collection +### Enable NGINX Plus Metric Collection {{< include "/use-cases/monitoring/enable-nginx-plus-status-zone-limited.md" >}} @@ -40,4 +45,8 @@ After saving the changes, reload NGINX to apply the new configuration: ```shell nginx -s reload -``` \ No newline at end of file +``` + +## Enable NGINX Open Source Metrics + +{{< include "/use-cases/monitoring/enable-nginx-oss-metrics.md" >}} \ No newline at end of file diff --git a/content/nim/monitoring/overview-metrics.md b/content/nim/monitoring/overview-metrics.md index cb1fe13e6..ccd3a1786 100644 --- a/content/nim/monitoring/overview-metrics.md +++ b/content/nim/monitoring/overview-metrics.md @@ -36,7 +36,7 @@ NGINX Instance Manager stores historical data in an analytics database and appli ### NGINX Open Source metrics -{{< include "/use-cases/monitoring/enable-nginx-oss-stub-status.md" >}} +{{< include "/use-cases/monitoring/enable-nginx-oss-metrics.md" >}} After saving the changes, reload NGINX to apply the new configuration: @@ -44,20 +44,6 @@ After saving the changes, reload NGINX to apply the new configuration: nginx -s reload ``` -### NGINX access log metrics - -Enable access logging to collect traffic metrics by parsing logs. Use the following log format: - -```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; -``` - ## Troubleshooting System metrics are collected automatically by the NGINX Agent. To collect NGINX-specific metrics, additional configuration is required. \ No newline at end of file diff --git a/content/nim/nginx-instances/add-instance.md b/content/nim/nginx-instances/add-instance.md index f694dc170..f4d0f75bb 100644 --- a/content/nim/nginx-instances/add-instance.md +++ b/content/nim/nginx-instances/add-instance.md @@ -39,9 +39,9 @@ Make sure you have: {{< include "/use-cases/monitoring/enable-nginx-plus-api.md" >}} -### Enable NGINX Open Source Stub Status API +### Enable NGINX Open Source Metrics -{{< include "/use-cases/monitoring/enable-nginx-oss-stub-status.md" >}} +{{< include "/use-cases/monitoring/enable-nginx-oss-metrics.md" >}} ## Next steps