Skip to content

Latest commit

 

History

History
310 lines (204 loc) · 16.8 KB

amplify-faq.md

File metadata and controls

310 lines (204 loc) · 16.8 KB
Raw

1. General

1.1. What Is NGINX Amplify?

NGINX Amplify is a tool for comprehensive NGINX monitoring. With NGINX Amplify it's easy to proactively analyze and fix problems related to running and scaling NGINX-based web applications.

You can use NGINX Amplify to do the following:

  • Visualize and identify NGINX performance bottlenecks, overloaded servers, or potential DDoS attacks
  • Improve and optimize NGINX performance with intelligent advice and recommendations
  • Get notified when something is wrong with the application infrastructure
  • Plan web application capacity and performance
  • Keep track of the systems running NGINX

1.2. Where Is NGINX Amplify Hosted?

NGINX Amplify is a SaaS and it is currently hosted in AWS us-west-1 (US West, N. California).

1.3. Is the NGINX Amplify Agent Traffic Protected?

All communications between the agent and the backend are done securely over SSL/TLS. All traffic is always initiated by the agent. The backend system doesn't set up any connections back to the agent.

1.4. Is the NGINX Amplify Agent Code Publicly Available?

NGINX Amplify Agent is an open source application. It is licensed under the 2-clause BSD license, and is available here.

1.5. What is This Question About My Password When Installing NGINX Amplify Agent?

It could be that you're starting the install script from a non-root account. In this case you will need sudo rights. While it depends on a particular system configuration, with a non-root account sudo will typically ask for a password.

2. NGINX Amplify Agent

2.1. What Operating Systems are Supported?

The agent is currently officially packaged and supported for the following Linux flavors only:

  • Ubuntu 22.04 "jammy" (amd64/arm64)
  • Ubuntu 20.04 "focal" (amd64/arm64)
  • Ubuntu 18.04 "bionic" (amd64/arm64)
  • Debian 12 "bookworm" (amd64/arm64)
  • Debian 11 "bullseye" (amd64/arm64)
  • Debian 10 "buster" (amd64/arm64)
  • RHEL/CentOS/OEL 8 (amd64/arm64)
  • RHEL/CentOS/OEL 9 (amd64/arm64)
  • Amazon Linux 2 LTS (amd64/arm64)

The following platforms are no longer supported but still can be used with older agent packages powered by Python 2:

  • Ubuntu 16.04 "xenial" (i386/amd64/arm64)
  • Debian 9 "stretch" (i386/amd64)
  • RHEL/CentOS/OEL 6 (i386/amd64)
  • RHEL/CentOS/OEL 7 (amd64)
  • Amazon Linux (amd64)

Other OS and distributions below are not fully supported yet (and no agent packages are available), however you can grab a specialized install script here and see if it works for you. Run install-source.sh (as root) instead of install.sh and follow the dialog. You can copy the API key from the Amplify UI (find it in the Settings or in the New System pop-up).

  • FreeBSD
  • SLES
  • Alpine
  • Fedora

Feel free to submit an issue or a PR if you find something that has to be fixed.

We also have an experimental Ebuild for Gentoo.

2.2. What Version of Python is Required?

NGINX Amplify Agent starting from version 1.8.0 works with Python >= 3.6.

Previous versions were powered by Python 2.6 and 2.7 depending on the target platform.

2.3. How Do I Start to Monitor My Systems with NGINX Amplify?

  1. Download and run the install script.
# curl -sS -L -O \
https://github.com/nginxinc/nginx-amplify-agent/raw/master/packages/install.sh && \
API_KEY='YOUR_API_KEY' sh ./install.sh

where YOUR_API_KEY is a unique API key assigned when you create an account with NGINX Amplify. You can also find the API key in the Account menu.

  1. Verify that the Agent has started.
# ps ax | grep -i 'amplify\-'
2552 ?        S      0:00 amplify-agent

For manual installation, please check the user guide here.

2.4. What Do I Need to Configure the NGINX Amplify Agent to Properly Report Metrics?

After you install and start the agent, normally it should just start reporting right away, pushing aggregated data to the Amplify backend at regular 1 minute intervals. It'll take about a minute for the new system to appear in the Amplify web interface.

If you don't see the new system or NGINX in the web interface, or (some) metrics aren't being collected, please check the following:

  1. The Amplify Agent package has been successfully installed, and no warnings were seen upon the installation.
  2. The amplify-agent process is running and updating its log file.
  3. The agent is running under the same user as your NGINX worker processes.
  4. The NGINX is started with an absolute path. Currently the agent can't detect NGINX instances launched with a relative path (e.g. "./nginx").
  5. The user ID that is used by the agent and the NGINX , can run ps(1) to see all system processes. If ps(1) is restricted for non-privileged users, the agent won't be able to find and properly detect the NGINX master process.
  6. The time is set correctly. If the time on the system where the agent runs is ahead or behind the world's clock, you won't be able to see the graphs.
  7. stub_status is properly configured, and the stub_status module is included in the NGINX build (this can be checked with nginx -V).
  8. NGINX access.log and error.log files are readable by the user nginx (or by the user set in NGINX config).
  9. All NGINX configuration files are readable by the agent user ID (check owner, group and permissions).
  10. Extra configuration steps have been performed as required for the additional metrics to be collected.
  11. The system DNS resolver is correctly configured, and receiver.amplify.nginx.com can be successfully resolved.
  12. Oubound TLS/SSL from the system to receiver.amplify.nginx.com is not restricted. This can be checked with curl(1). Configure a proxy server for the agent if required.
  13. selinux(8), apparmor(7) or grsecurity are not interfering with the metric collection. E.g. for selinux(8) check /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 an easy workaround for this except for allowing the agent to run as root. Sometimes fixing permissions for /proc and /sys/block may work.

2.5. How Do I Verify that NGINX Amplify Agent Is Correctly Installed?

  1. On Ubuntu/Debian use:
# dpkg -s nginx-amplify-agent
  1. On CentOS and Red Hat use:
# yum info nginx-amplify-agent

2.6. How Can I Update NGINX Amplify Agent?

  1. On Ubuntu/Debian use:
# apt-get update && \
apt-get install nginx-amplify-agent
  1. On CentOS use:
# yum makecache && \
yum update nginx-amplify-agent

2.7. What System Resources are Required?

We work very hard to make the agent consume as little memory and CPU as possible. Normally it should be under 10% of CPU usage and a few dozen MBs of RSS memory. If you notice any anomalies in the system resource consumption, please create an issue at nginx-amplify-agent repo.

2.8. How Do I Restart NGINX Amplify Agent?

It's as simple as

# service amplify-agent restart

2.9. How Can I Uninstall NGINX Amplify Agent?

  1. On Ubuntu/Debian use:
apt-get remove nginx-amplify-agent
  1. On CentOS and Red Hat use:
yum remove nginx-amplify-agent

2.10. How Can I Override System Hostname?

If the agent is not able to determine the system's hostname, you can define it manually in /etc/amplify-agent/agent.conf

Check for the following section, and fill in the desired hostname:

[credentials]
..
hostname = myhostname1

The hostname should be something real — the following aren't valid hostnames:

  • localhost
  • localhost.localdomain
  • localhost6.localdomain6
  • ip6-localhost

2.11. How Can I Override the User ID for the Agent to Use?

Please check the following section of the NGINX Amplify public documentation.

2.12. Can I Use NGINX Amplify Agent with Docker?

Although the support for a Docker environment is currently experimental, in general the answer is yes. Please check the following part of the agent repository to find out more.

3. NGINX Amplify User Interface

3.1. What Browsers are Supported?

Currently the following desktop browsers are officially supported:

  • Chrome
  • Firefox
  • Safari
  • Opera

3.2. Is the Traffic to the Web Interface Secure?

We only support SSL/TLS connections to the Amplify web interface.

3.3. How Can I Delete a System or an NGINX Instance from NGINX Amplify?

If the goal is to completely delete a previously monitored object, then do the following:

  1. Uninstall the agent
  2. Delete objects from the web interface
  3. Delete alarms

To delete a system using the web interface — find it in the Inventory, and choose the [i] icon. You can delete objects from the popup window that appears next.

Bear in mind — deleting objects there will not stop the agent. To completely remove a system from monitoring, please stop or uninstall the agent first, and then clean it up in the web interface. Don't forget to also clean up any alerts.

4. NGINX Amplify Metrics and Metadata

4.1. What Metrics and Metadata are Collected?

NGINX Amplify Agent collects the following types of data:

  • NGINX metrics. The agent collects a lot of NGINX related metrics from stub_status, the NGINX Plus status API, the NGINX log files, and from the NGINX process state.
  • System metrics. These are various key metrics describing the system, e.g. CPU usage, memory usage, network traffic, etc.
  • PHP-FPM metrics. The agent can obtain metrics from the PHP-FPM pool status, if it detects a running PHP-FPM master process.
  • NGINX metadata. This is what describes your NGINX instances, and it includes package data, build information, the path to the binary, build configuration options, etc. NGINX metadata also includes the NGINX configuration elements.
  • System metadata. This is the basic information about the OS environment where the agent runs. This could be the hostname, uptime, OS flavor, and other data.

The agent will mostly use Python's psutil() to collect the metrics, but occasionally it may also invoke certain system utilities like ps(1).

To see the full list of metrics, please check the documentation here.

4.2. How Is the NGINX Configuration Parsed and Analyzed?

The agent is able to automatically find all relevant NGINX configuration files, parse them, extract their logical structure, and send the associated JSON data to the Amplify backend for further analysis and reporting.

To parse SSL certificate metadata the Amplify Agent uses standard openssl(1) functions. SSL certificates are parsed and analyzed only when the corresponding settings are turned on. SSL certificate analysis is off by default.

The agent DOES NOT ever send the raw unprocessed config files to the backend system. In addition, the following directives in the NGINX configuration are NOT analyzed — and their parameters ARE NOT exported to the SaaS backend: ssl_certificate_key, ssl_client_certificate, ssl_password_file, ssl_stapling_file, ssl_trusted_certificate, auth_basic_user_file, secure_link_secret.

For more information on configuration analysis and reports see the NGINX Amplify documentation.