Update content/amplify/nginx-amplify-agent/amplify-agent-overview.md

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.
+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 = <your_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"