From 83fa0f60b75fd5917bb961852de894fd9ef727cf Mon Sep 17 00:00:00 2001 From: "quantstruct-canvas-preview[bot]" <224686132+quantstruct-canvas-preview[bot]@users.noreply.github.com> Date: Fri, 29 Aug 2025 22:32:08 +0000 Subject: [PATCH 1/4] Update content/amplify/nginx-amplify-agent/amplify-agent-overview.md --- content/amplify/nginx-amplify-agent/amplify-agent-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/amplify/nginx-amplify-agent/amplify-agent-overview.md b/content/amplify/nginx-amplify-agent/amplify-agent-overview.md index 235fb15cd..bd466f8f5 100644 --- a/content/amplify/nginx-amplify-agent/amplify-agent-overview.md +++ b/content/amplify/nginx-amplify-agent/amplify-agent-overview.md @@ -23,4 +23,4 @@ The NGINX Amplify Agent identifies an NGINX instance as any running NGINX master {{< note >}}There's no need to manually add or configure anything in the web interface after installing NGINX Amplify Agent. When NGINX Amplify Agent is started, the metrics and the metadata are automatically reported to the Amplify backend and visualized in the web interface.{{< /note >}} -When an NGINX instance is no longer in use it must be manually deleted in the web interface. The "Remove object" button can be found in the metadata viewer popup — see the [User Interface]({{< ref "/amplify/user-interface/">}}) documentation. \ No newline at end of file +When an NGINX instance is no longer in use it must be manually deleted in the web interface. The "Remove object" button can be found in the metadata viewer popup — see the [User Interface]({{< ref "/amplify/user-interface/">}}) documentation.\n\n## Definitions\n- metrics: Quantifiable measurements collected about the NGINX and system, such as request rate, latency, CPU, memory, and NGINX-specific metrics exposed by the stub_status and Amplify Agent collectors.\n- metadata: Descriptive information about monitored entities (NGINX instances, server blocks, PHP-FPM pools, databases) reported by Amplify to provide context for metrics.\n- instrumentation: The process of enabling, collecting, and exposing metrics and metadata from NGINX and the host to Amplify.\n- Amplify Agent: The lightweight Python application that runs on hosts to collect metrics/metadata and ship them to the Amplify backend.\n- NGINX instance: Any running NGINX master process identified by a unique binary path or configuration.\n\n## Instrumentation Guidance\nFollow these steps to enable and verify metrics collection:\n\n1) Ensure NGINX status can be scraped\n- If you want core request metrics, enable stub_status in your NGINX config:\n ```\n location = /nginx_status {\n stub_status on;\n allow 127.0.0.1;\n deny all;\n }\n ```\n- Verify the status page is accessible from the host running Amplify Agent.\n\n2) Run Amplify Agent under the correct user and with appropriate permissions\n- Ensure the amplify-agent process runs as a user with access to:\n - NGINX binaries and configurations\n - NGINX logs and access logs\n - write permissions for Amplify logs\n- Example (check/current user):\n ```\n ps aux | grep amplify\n ```\n\n3) Permissions for logs and configuration\n- Ensure read permissions for the agent on the NGINX config and logs:\n - chmod -R o+r /etc/nginx /var/log/nginx\n - chown -R amplify:amplify /var/log/amplify-agent\n\n4) Enable additional metrics via existing references\n- Amplify collects a base set of metrics by default; to add more (e.g., PHP-FPM, MySQL, etc.), follow the Additional NGINX metrics guidance in the Amplify docs:\n - see /amplify/metrics-metadata/other-metrics.md\n- Example of enabling extra metrics (conceptual):\n ```\n # amplify-agent.conf (conceptual)\n [nginx]\n enable_metrics = true\n additional_metrics = true\n ```\n\n5) Restart/apply changes\n- After changes to config or status, restart the agent:\n - sudo systemctl restart amplify-agent\n - or sudo service amplify-agent restart\n\n6) Verification\n- In the Amplify UI, you should start seeing metrics and metadata within about 1 minute.\n\n### Notes on instrumentation and references\n- The exact syntax for enabling additional metrics depends on the metrics you want; refer to Amplify docs for precise steps.\n- If you change the NGINX code to expose additional metrics, re-load NGINX to apply changes.\n\n## Configuration\nKey metrics-related settings in amplify-agent.conf (essentials, proxy, log level) and restart/apply Changes:\n- Essentials: ensure the agent is pointed to your Amplify site and has a valid token/API key\n- Proxy: if you use a proxy, configure in the agent config\n- Log level: set log_level (INFO, DEBUG) to control verbosity\n- Apply changes by restarting the agent:\n - sudo systemctl restart amplify-agent\n\n## Practical Examples\n1) Fresh install with default metrics\n- Install Amplify Agent on a host, configure API key/site, start service, verify in Amplify UI within ~1 minute.\n- Snippet:\n ```\n # amplify-agent.conf (conceptual)\n [amp]\n site = my-site\n token = \n log_level = INFO\n [proxy]\n http = http://proxy.example.com:8080\n ```\n\n2) Enabling extra metrics via Additional NGINX metrics\n- Enable in the config as per docs and restart agent. After restart, you should see extra metrics in the UI.\n\n3) Verifying in Amplify UI\n- Open the Amplify UI and navigate to the host; you should start seeing metrics within ~1 minute.\n" \ No newline at end of file From f9817b4a35fb683c977b1c443bab00ec53cb43bc Mon Sep 17 00:00:00 2001 From: "quantstruct-canvas-preview[bot]" <224686132+quantstruct-canvas-preview[bot]@users.noreply.github.com> Date: Fri, 29 Aug 2025 22:32:10 +0000 Subject: [PATCH 2/4] Update content/amplify/nginx-amplify-agent/troubleshooting-metrics-collection.md --- .../troubleshooting-metrics-collection.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/content/amplify/nginx-amplify-agent/troubleshooting-metrics-collection.md b/content/amplify/nginx-amplify-agent/troubleshooting-metrics-collection.md index 5501b2fbe..2f7971b31 100644 --- a/content/amplify/nginx-amplify-agent/troubleshooting-metrics-collection.md +++ b/content/amplify/nginx-amplify-agent/troubleshooting-metrics-collection.md @@ -10,6 +10,14 @@ After you [install and start]({{< ref "/amplify/nginx-amplify-agent/install/inst If you don't see the new system or NGINX instance in the web interface, or (some) metrics aren't being collected, please review the following: +## Definitions + +### Instrumentation Guidance + +- Definitions and terminology for metrics collection, including Amplify Agent, receiver, stub_status, and metrics. +- Instrumentation Guidance: follow the practical steps in the Practical Demonstration section to diagnose metric collection issues. + + 1. The NGINX Amplify Agent package has been successfully [installed]({{< ref "/amplify/nginx-amplify-agent/install/installing-amplify-agent" >}}), and no warnings were reported during the installation. 2. The `amplify-agent` process is running and updating its [log file]({{< ref "/amplify/nginx-amplify-agent/install/configuring-amplify-agent#agent-logfile" >}}). 3. NGINX Amplify Agent is running under the same user as your NGINX worker processes. @@ -24,3 +32,28 @@ If you don't see the new system or NGINX instance in the web interface, or (some 12. Outbound TLS/SSL from the system to *receiver.amplify.nginx.com* is not restricted. This can be confirmed with `curl(1)`. [Configure a proxy server]({{< ref "/amplify/nginx-amplify-agent/install/configuring-amplify-agent#setting-up-a-proxy" >}}) for NGINX Amplify Agent if required. 13. *selinux(8)*, *apparmor(7)* or [grsecurity](https://grsecurity.net) are not interfering with the metric collection. E.g., for _selinux_(8)* review **/etc/selinux/config**. Try `setenforce 0` temporarily and see if it improves the situation for certain metrics. 14. Some VPS providers use hardened Linux kernels that may restrict non-root users from accessing */proc* and */sys*. Metrics describing system and NGINX disk I/O are usually affected. There is no easy workaround except for allowing NGINX Amplify Agent to run as `root`. Sometimes fixing permissions for */proc* and */sys/block* may work. + +## Practical Demonstration + +This section provides a step-by-step example to reproduce a metric collection issue, verify installation and agent process, check user permissions, verify time synchronization, confirm stub_status and DNS/egress reachability, collect logs, and validate resolution by rechecking the Amplify UI after fixes. Example diagnostic commands are provided in parentheses. + +### Step-by-step example +1) Reproduce the issue: intentionally disable a metric or simulate a misconfiguration. +2) Verify installation and agent process: + - systemctl status amplify-agent + - ps aux | grep amplify-agent | grep -v grep +3) Check user permissions: + - id amplify + - ls -ld /var/log/amplify-agent +4) Verify time synchronization: + - timedatectl status + - date +5) Confirm stub_status and DNS/egress reachability: + - curl -sS http://localhost/nginx_status || curl -sS http://127.0.0.1/nginx_status + - dig receiver.amplify.nginx.com + - curl -I https://receiver.amplify.nginx.com +6) Collect logs: + - tail -f /var/log/amplify-agent/amplify-agent.log +7) Validate resolution by rechecking the Amplify UI after fixes: + - Refresh the Amplify UI and verify metrics appear; wait up to 2 minutes and re-check. + From 3813096437025483289223cda74943f398493062 Mon Sep 17 00:00:00 2001 From: "quantstruct-canvas-preview[bot]" <224686132+quantstruct-canvas-preview[bot]@users.noreply.github.com> Date: Fri, 29 Aug 2025 22:32:12 +0000 Subject: [PATCH 3/4] Update content/amplify/metrics-metadata/metrics-overview.md --- content/amplify/metrics-metadata/metrics-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/amplify/metrics-metadata/metrics-overview.md b/content/amplify/metrics-metadata/metrics-overview.md index 6a6b34f2c..dbca01d48 100644 --- a/content/amplify/metrics-metadata/metrics-overview.md +++ b/content/amplify/metrics-metadata/metrics-overview.md @@ -8,4 +8,4 @@ docs: DOCS-972 Most metrics are collected by F5 NGINX Amplify Agent without requiring the user to perform any additional setup. For troubleshooting, see [Troubleshooting Metrics Collection]({{< ref "/amplify/nginx-amplify-agent/troubleshooting-metrics-collection.md" >}}). -Some additional metrics for NGINX monitoring will only be reported if the NGINX configuration file is modified accordingly. See [Additional NGINX Metrics]({{< ref "/amplify/metrics-metadata/nginx-metrics#additional-nginx-metrics" >}}), and review the *Source* and *Variable* fields in the metric descriptions that follow. \ No newline at end of file +Some additional metrics for NGINX monitoring will only be reported if the NGINX configuration file is modified accordingly. See [Additional NGINX Metrics]({{< ref "/amplify/metrics-metadata/nginx-metrics#additional-nginx-metrics" >}}), and review the *Source* and *Variable* fields in the metric descriptions that follow.\n\n## Definitions glossary\n\n- Metrics: Quantitative indicators collected by Amplify that describe the performance and usage of components being monitored (e.g., request rate, latency, error rate).\n\n- Metadata: Contextual information about metrics that helps interpret them, including the source, unit, dimension, and scope.\n\n- Instrumentation: The process by which Amplify Agent collects metrics, including sources, collectors, and any instrumentation endpoints.\n\n- Source: The origin of a metric (e.g., NGINX, Amplify Agent, system).\n\n- Variable: The parameter or dimension associated with a metric (e.g., server, location, method).\n\n- Additional NGINX Metrics: Metrics beyond the default set that provide deeper visibility into NGINX performance, requiring configuration.\n\n- UI: The Amplify web interface used to visualize and query metrics.\n\n- Queries: Filters and API calls used to retrieve specific metric data.\n\n- Data retention: How long metrics are stored.\n\n## Instrumentation Guidance\n\nThe Amplify Agent collects metrics by instrumenting NGINX and other data sources as configured. Default metrics are gathered automatically with no extra setup. Additional NGINX Metrics require explicit configuration to enable, and some metrics depend on NGINX status endpoints or modules being enabled in the NGINX config. Configurations that influence collection include:\n\n- Endpoints/metrics sources enabled (e.g., NGINX metrics endpoints, status modules).\n\n- The collection interval or sampling rate used by the Amplify Agent.\n\n- Whether Additional NGINX Metrics are enabled in the agent/UI and the scope of metrics selected.\n\n- Agent version and deployment environment.\n\nBest practices: ensure status modules are enabled, keep agent updated, and coordinate config changes with NGINX to avoid missing data during restarts.\n\n## Practical Examples\n\n- Example 1: Enable Additional NGINX Metrics\n\n 1. Refer to the Additional NGINX Metrics documentation and follow steps to enable extra metrics for your NGINX instances.\n\n 2. Reload/restart Amplify Agent if required.\n\n 3. Confirm in the UI that new NGINX metrics appear in the Metrics Explorer or in a saved query.\n\n- Example 2: Validate results in UI or via queries\n\n - In the Amplify UI, open Metrics Explorer, filter by NGINX-related metrics, and verify values are being reported for the selected time range.\n\n - Via API/queries, request metrics for NGINX with appropriate filters and confirm data continuity and expected ranges.\n\nCross-link: See Additional NGINX Metrics for details.\n \ No newline at end of file From 597afd9b0e484c6678a03991234fb75ee851f5f8 Mon Sep 17 00:00:00 2001 From: "quantstruct-canvas-preview[bot]" <224686132+quantstruct-canvas-preview[bot]@users.noreply.github.com> Date: Fri, 29 Aug 2025 22:32:13 +0000 Subject: [PATCH 4/4] Update content/amplify/faq/metrics-and-metadata.md --- content/amplify/faq/metrics-and-metadata.md | 47 ++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/content/amplify/faq/metrics-and-metadata.md b/content/amplify/faq/metrics-and-metadata.md index ea7820bd5..fa5aae22a 100644 --- a/content/amplify/faq/metrics-and-metadata.md +++ b/content/amplify/faq/metrics-and-metadata.md @@ -10,4 +10,49 @@ docs: DOCS-957 [NGINX Amplify Agent Metrics and Metadata]({{< ref "/amplify/nginx-amplify-agent/metadata-metrics-collection" >}}) -{{< note >}}For a complete list of metrics, refer to the [Metrics and Metadata documentation]({{< ref "/amplify/metrics-metadata" >}}).{{< /note >}} \ No newline at end of file +{{< note >}}For a complete list of metrics, refer to the [Metrics and Metadata documentation]({{< ref "/amplify/metrics-metadata" >}}).{{< /note >}} + +### Definitions + +- Data Collected by the Amplify Agent + The Amplify Agent gathers a combination of metrics and metadata about NGINX, the host, and the agent itself. This includes: + - NGINX metrics (requests, active connections, upstream status, etc.) + - System metrics (CPU, memory, disk, network) + - Agent metadata (agent version, host, timestamp) + - Optional additional metrics as configured (see Instrumentation Guidance) + +- What is Instrumented + Instrumentation refers to the code paths and configuration that enable collection of these metrics and their propagation to the Amplify backend. Metrics and metadata are collected by the agent, parsed, and transmitted to Amplify for visualization. Instrumentation is designed to be low overhead and pluggable via configuration. + +### Instrumentation Guidance + +- Overview + The Amplify Agent uses lightweight instrumentation to gather metrics and metadata from NGINX and the host. The instrumentation surface is exposed via the agent's config and is documented in the Instrumentation and Metrics Configuration docs. + +- Enabling additional metrics + To enable a broader set of metrics, follow the Instrumentation Guidance: + - Refer to the Instrumentation Overview doc for the supported metric sets and their enabling flags. + - Update the agent configuration with the appropriate flags or enablements, then restart the agent. + +- Verifying in the Amplify UI + After the agent restarts and begins sending data, open the Amplify UI and navigate to Metrics for your NGINX host. Verify that the newly enabled metrics appear under the NGINX metrics dashboards and correlate with expected signal within a few minutes. + +- Important notes + - Some metrics may require enabling specific modules or building optional instrumented components. + - See the Metrics Configuration documentation for details on per-metric enablement and data retention. + +### Practical Examples + +- Example 1: Enable additional metrics and validate in UI + 1) Update agent config to enable additional metrics per the Instrumentation Guidance. + 2) Restart the Amplify Agent to apply changes. + 3) In the Amplify UI, navigate to Metrics > NGINX and confirm that the newly enabled metrics are visible and updating. + 4) Compare metric values against expected ranges during normal load to validate correctness. + +- Example 2: Validate data presence after upgrade + 1) After upgrading Amplify components, confirm that the new metrics appear in the UI within 2-5 minutes. + 2) If missing, check agent logs for instrumentation errors and verify that the new metrics are enabled in the config. + +- References + - Instrumentation Overview: {{< ref "/amplify/instrumentation-overview" >}} + - Metrics Configuration: {{< ref "/amplify/metrics-configuration" >}} \ No newline at end of file