Update NGINXaaS documentation for native-metrics integration (#292)

* Update NGINXaaS documentation for native-metrics integration

* Fix missing metrics and aggregation type in metric catalog

* Move listener_backlog to nginxaas statistics

Author: arpith-f5

content/nginxaas-azure/changelog.md

@@ -13,6 +13,13 @@ To see a list of currently active issues, visit the [Known issues]({{< ref "/ngi
 
 To review older entries, visit the [Changelog archive]({{< ref "/nginxaas-azure/changelog-archive" >}}) section.
 
+
+## May 20, 2025
+
+- {{% icon-feature %}} **Azure Monitor Platform Metrics**
+
+   NGINXaaS now publishes platform metrics directly to Azure Monitor. Compared to legacy monitoring based on custom metrics, platform metrics offers reduced latency and higher reliability. We strongly recommend migrating your alerts to use platform metrics for improved monitoring and management. For more details on enabling platform metrics, please refer to [Enable Monitoring]({{< relref "/nginxaas-azure/monitoring/enable-monitoring.md">}}).
+
 ## April 22, 2025
 
 ### What's New

content/nginxaas-azure/monitoring/configure-alerts.md

@@ -11,7 +11,7 @@ type:
 
 ## Overview
 
-{{<note>}}F5 NGINX as a Service for Azure (NGINXaaS) publishes custom metrics to Azure Monitor. To learn more about how to create and manage metrics-based alert rules, refer to the [Alerts section in Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-create-new-alert-rule?tabs=metric) documentation from Microsoft. {{</note>}}
+{{<note>}}F5 NGINX as a Service for Azure (NGINXaaS) publishes platform metrics to Azure Monitor. To learn more about how to create and manage metrics-based alert rules, refer to the [Alerts section in Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-create-new-alert-rule?tabs=metric) documentation from Microsoft. {{</note>}}
 
 This guide explains how to create and configure metrics-based alerts for your NGINXaaS for Azure deployment using Azure Monitor.
 

content/nginxaas-azure/monitoring/enable-monitoring.md

@@ -8,75 +8,54 @@ type:
 - how-to
 ---
 
-Monitoring your application's performance is crucial for maintaining its reliability and efficiency. F5 NGINX as a Service for Azure (NGINXaaS) seamlessly integrates with Azure Monitor, allowing you to collect, correlate, and analyze metrics for a thorough understanding of your application's health and behavior. With Azure Monitor, you gain access to a wealth of information regarding your application's operations. You can:
+Monitoring your application's performance is crucial for maintaining its reliability and efficiency. F5 NGINX as a Service for Azure (NGINXaaS) seamlessly integrates with Azure Monitor, allowing you to collect, correlate, and analyze metrics for a thorough understanding of your application's health and behavior. 
 
-- Review Metrics: Examine the performance data collected from your application.
-- Correlate Data: Connect different data points to gain insights into application performance trends.
-- Analyze Performance: Dive deep into metrics to gain a comprehensive understanding of how your application operates.
-- Create Alerts: Set up proactive monitoring by configuring alerts that notify you of potential issues before they escalate.
+Refer to the [Azure monitor overview](https://docs.microsoft.com/en-us/azure/azure-monitor/overview) documentation from Microsoft to learn more about Azure Monitor.
 
-{{<note>}}NGINXaaS for Azure publishes *custom* metrics to Azure Monitor. To learn about the differences between standard and custom metrics, refer to the [Custom metrics in Azure Monitor overview](https://docs.microsoft.com/en-us/azure/azure-monitor/essentials/metrics-custom-overview) documentation from Microsoft. Azure Monitor custom metrics are currently in public preview.{{</note>}}
+### Prerequisites
 
+- A system assigned managed identity with `Monitoring Metrics Publisher` role.
 
-### Prerequisites
+{{<note>}} When a system assigned managed identity is added to the deployment through portal, this role is automatically added.{{</note>}}
 
-- A user assigned managed identity or a system assigned managed identity with `Monitoring Metrics Publisher` role.
+## Collection
 
-{{<note>}} When a user assigned managed identity or a system assigned managed identity is added to the deployment through portal, this role is automatically added.{{</note>}}
+Azure Monitor will collects metrics from the NGINXaaS deployment automatically if the prerequisites are met. No configuration is required.
 
-- User must be an owner or user access administrator for NGINX deployment resource to complete this set up.
+## Exporting
+You can export Azure Monitor metrics to other destinations like Log Analytics workspace, Azure Storage Account, Azure Event Hubs or Azure Monitor partner solutions using Diagnostic Setting. For more information, see the [Metrics diagnostic setting](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/diagnostic-settings).
 
-- If you're unfamiliar with Azure Monitor, refer to the [Azure monitor overview](https://docs.microsoft.com/en-us/azure/azure-monitor/overview) documentation from Microsoft.
+To configure diagnostic settings for a service, see [Create diagnostic settings in Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/create-diagnostic-settings).
 
-## Enable monitoring
+{{<note>}} Not all metrics are exportable via diagnostic settings, for a list of exportable metrics, see [NGINXaaS exportable metrics](https://learn.microsoft.com/en-us/azure/azure-monitor/reference/supported-metrics/nginx-nginxplus-nginxdeployments-metrics).{{</note>}}
 
-1. Log in to the Azure portal and navigate to your NGINXaaS for Azure deployment.
-2. In the navigation pane under **Settings**, select the **NGINX monitoring** section.
-3. Turn on the **Send metrics to Azure Monitor** setting.
 
-## View metrics with Azure Monitor metrics explorer
+## Cost and retention
+Azure Monitor platform metrics are ingested and stored free of charge, with a standard retention period of 93 days. Adding alerts, querying Azure Monitor using REST API or exporting metrics using Azure Monitor's diagnostic settings would incurs costs. For detailed pricing, you can refer to the [Azure Monitor pricing page](https://azure.microsoft.com/en-us/pricing/details/monitor/).
 
-1. In the navigation pane under **Monitoring**, select the **Metrics** section to access the Azure Monitor metrics explorer for your NGINXaaS deployment.
-2. Refer to the [Azure Monitor metrics explorer](https://docs.microsoft.com/en-us/azure/azure-monitor/essentials/metrics-getting-started) documentation from Microsoft to learn how you can create queries.
 
-{{<note>}}Many of NGINX Plus's advanced statistics need to be enabled in the "nginx.conf" file before they will appear in the metrics explorer, for example "plus.http.request.bytes_*". Refer to [Gathering Data to Appear in Statistics](https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#gathering-data-to-appear-in-statistics) to learn more.{{</note>}}
+## View metrics with Azure Monitor metrics explorer
 
-## Retrieve metrics through Azure Monitor API
+Access the [Microsoft Azure portal](https://portal.azure.com)
 
-This section shows you how to effectively discover, gather and analyze NGINXaaS metrics through the Azure Monitor API.
+1. Go to your NGINXaaS for Azure deployment.
+2. In the navigation pane under **Monitoring**, select the **Metrics** section to access the Azure Monitor metrics explorer for your NGINXaaS deployment.
 
-{{<note>}}Refer to [Authenticate Azure Monitor requests](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/rest-api-walkthrough?tabs=portal#authenticate-azure-monitor-requests) for instructions on authenticating your API requests against the Azure Monitor API endpoint.{{</note>}}
+Refer to the [Azure Monitor metrics explorer](https://docs.microsoft.com/en-us/azure/azure-monitor/essentials/metrics-getting-started) documentation from Microsoft to learn how you can create queries.
 
-1. **Retrieve metric namespaces:** Each metric belongs to a category, or "namespace", which groups similar types of metrics together. We recommend listing all namespaces for NGINXaaS to locate the metrics you're interested in. The following `curl` example shows how to retrieve all metrics namespaces on your NGINXaaS deployment:
+{{<note>}}Many of NGINX Plus's advanced statistics need to be enabled in the "nginx.conf" file before they will appear in the metrics explorer, for example "plus.http.request.bytes_*". Refer to [Gathering Data to Appear in Statistics](https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#gathering-data-to-appear-in-statistics) to learn more.{{</note>}}
 
-   ```bash
-   curl --request GET --header "Authorization: Bearer $TOKEN" "https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/my-nginx-rg/providers/NGINX.NGINXPLUS/nginxDeployments/my-nginx-dep/providers/microsoft.insights/metricNamespaces?api-version=2024-02-01"
-   ```
+## Retrieve metrics through Azure Monitor REST API
 
-   The following JSON shows an example response body:
+This section shows you how to effectively discover, gather and analyze NGINXaaS metrics through the Azure Monitor REST API.
 
-   ```json
-   {
-     "value": [
-    	...
-   	{
-         "id": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/my-nginx-rg/providers/NGINX.NGINXPLUS/nginxDeployments/my-nginx-dep/providers/microsoft.insights/metricNamespaces/NGINX Connections Statistics",
-         "name": "nginx connections statistics",
-   	  "type": "Microsoft.Insights/metricNamespaces",
-         "classification": "Custom",
-         "properties": {
-           "metricNamespaceName": "nginx connections statistics"
-         }
-       },
-   	...
-     ]
-   }
-   ```
+{{<note>}}Refer to [Authenticate Azure Monitor requests](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/rest-api-walkthrough?tabs=portal#authenticate-azure-monitor-requests) for instructions on authenticating your API requests against the Azure Monitor API endpoint.{{</note>}}
 
-2. **Retrieve metric definitions:** Metrics definitions give you insights into the various metrics available for NGINXaaS within a namespace and what they represent. The following `curl` example shows how to retrieve all metrics definitions within the `nginx connections statistics` namespace for your NGINXaaS deployment:
+
+1. **Retrieve metric definitions:** Metrics definitions give you insights into the various metrics available for NGINXaaS within a namespace and what they represent. The following `curl` example shows how to retrieve all metrics definitions within the `nginx connections statistics` namespace for your NGINXaaS deployment:
 
    ```bash
-   curl --request GET --header "Authorization: Bearer $TOKEN" "https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/my-nginx-rg/providers/NGINX.NGINXPLUS/nginxDeployments/my-nginx-dep/providers/microsoft.insights/metricDefinitions?metricnamespace=nginx%20connections%20statistics&api-version=2024-02-01"
+   curl --request GET --header "Authorization: Bearer $TOKEN" "https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/my-nginx-rg/providers/NGINX.NGINXPLUS/nginxDeployments/my-nginx-dep/providers/microsoft.insights/metricDefinitions?api-version=2024-02-01"
    ```
 
    The following JSON shows an example response body:
@@ -88,50 +67,51 @@ This section shows you how to effectively discover, gather and analyze NGINXaaS
        {
          "id": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/my-nginx-rg/providers/NGINX.NGINXPLUS/nginxDeployments/my-nginx-dep/providers/microsoft.insights/metricdefinitions/Nginx Connections Statistics/nginx.conn.current",
          "resourceId": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/my-nginx-rg/providers/NGINX.NGINXPLUS/nginxDeployments/my-nginx-deployment",
-         "namespace": "NGINX Connections Statistics",
+         "namespace": "NGINX.NGINXPLUS/nginxDeployments",
+         "category":"nginx connections statistics",
          "name": {
            "value": "nginx.conn.current",
-           "localizedValue": "nginx.conn.current"
+           "localizedValue": "Current connections"
          },
          ...
-       },
+       }
    	...
      ]
    }
    ```
 
-3. **Metric values:** Finally, you can obtain the actual metric values which represent real-time or historical data points that tell you how your NGINXaaS is performing. The following `curl` example shows how to retrieve the value of metric `nginx.conn.current` within the `nginx connections statistics` namespace over a 10-minute time window averaged over 5 minute intervals:
+2. **Metric values:** You can obtain the actual metric values which represent real-time or historical data points that tell you how your NGINXaaS is performing. The following `curl` example shows how to retrieve the value of metric `nginx.conn.current` over a 10-minute time window averaged over 5 minute intervals:
 
    ```bash
-   curl --request GET --header "Authorization: Bearer $TOKEN" "https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/my-nginx-rg/providers/NGINX.NGINXPLUS/nginxDeployments/my-nginx-dep/providers/microsoft.insights/metrics?metricnamespace=nginx%20connections%20statistics&metricnames=nginx.conn.current&timespan=2024-03-27T20:00:00Z/2024-03-27T20:10:00Z&aggregation=Average&interval=PT5M&api-version=2024-02-01"
+   curl --request GET --header "Authorization: Bearer $TOKEN" "https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/my-nginx-rg/providers/NGINX.NGINXPLUS/nginxDeployments/my-nginx-dep/providers/microsoft.insights/metrics?metricnames=nginx.conn.current&timespan=2025-03-27T20:00:00Z/2025-03-27T20:10:00Z&aggregation=Average&interval=PT5M&api-version=2024-02-01"
    ```
 
    The following JSON shows an example response body:
 
    ```json
    {
      "cost": 9,
-     "timespan": "2024-03-27T20:00:00Z/2024-03-27T20:10:00Z",
+     "timespan": "2025-03-27T20:00:00Z/2025-03-27T20:10:00Z",
      "interval": "PT5M",
      "value": [
        {
          "id": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/my-nginx-rg/providers/NGINX.NGINXPLUS/nginxDeployments/my-nginx-dep/providers/Microsoft.Insights/metrics/nginx.conn.current",
          "type": "Microsoft.Insights/metrics",
          "name": {
            "value": "nginx.conn.current",
-           "localizedValue": "nginx.conn.current"
+           "localizedValue": "Current connections"
          },
-         "unit": "Unspecified",
+         "unit": "Count",
          "timeseries": [
            {
              "metadatavalues": [],
              "data": [
                {
-                 "timeStamp": "2024-03-27T20:00:00Z",
+                 "timeStamp": "2025-03-27T20:00:00Z",
                  "average": 4
                },
                {
-                 "timeStamp": "2024-03-27T20:05:00Z",
+                 "timeStamp": "2025-03-27T20:05:00Z",
                  "average": 4
                }
              ]
@@ -140,7 +120,7 @@ This section shows you how to effectively discover, gather and analyze NGINXaaS
          "errorCode": "Success"
        }
      ],
-     "namespace": "nginx connections statistics",
+     "namespace": "NGINX.NGINXPLUS/nginxDeployments",
      "resourceregion": "eastus2"
    }
    ```