We recently released the free public beta of NGINX Amplify, our new cloud‑based tool that gives you visibility and control of NGINX and NGINX‑delivered applications. NGINX Amplify receives information from a small agent which you install on your NGINX servers. It monitors NGINX and provides configuration analysis, graphs for specific metrics, dashboards that combine several metrics, and alerts.
This blog post is the first in a series about how to monitor NGINX with NGINX Amplify. In this first part, we walk you through the steps for creating an NGINX Amplify account and installing the agent on each of your NGINX servers. Then, we show you how to get started monitoring NGINX, including setting up an initial set of graphs, creating a simple dashboard, setting up an alert, and stepping through the configuration analysis.
In later blog posts, we’ll go more deeply into each of these capabilities, putting you well on the way to becoming an NGINX Amplify expert.
Before You Begin
You can help NGINX Amplify monitor NGINX, NGINX Plus, and your app servers optimally from the start. Perform the following steps before you sign up:
- If possible, upgrade to the most recent version of NGINX or NGINX Plus.
- Check that you are using a supported Linux distribution. As of this writing, supported distributions include Amazon Linux, CentOS, Debian, Red Hat Linux, and Ubuntu.
- Check that your Python version is supported. As of this writing, Python version 2.6 and 2.7 are supported – Python 3 is not.
- To get a full range of metrics:
- Make sure the directory and the configuration file where
stub_statusis defined are readable by the NGINX Amplify agent; if so, the agent accesses them automatically.
- For even more metrics, make a few simple changes to your log format configuration, then reload NGINX for the changes to take effect.
Creating an NGINX Amplify Account
Creating an NGINX Amplify account gives you access to the cloud‑based software behind NGINX Amplify. However, NGINX Amplify doesn’t actually monitor NGINX or your app servers until you install the agent on each server, as described in the next section.
Follow these steps to create your NGINX Amplify account:
- Visit the NGINX Amplify signup page.
- Fill in the form and agree to the Terms of Service.
- Click Sign up.
- In the new dialog that appears, fill in the additional information about yourself. Click Next.
Congratulations! You now have access to NGINX Amplify.
Note: If you have problems using NGINX Amplify, click the question mark (?) icon in the lower right of the main screen to communicate directly with our team. You may also receive automated suggestions from the team as you install NGINX Amplify and start using it.
The next section explains how to install the agent on your NGINX servers.
Installing the NGINX Amplify Agent on Your Servers
The instructions for adding a server to NGINX Amplify appear on‑screen after you create your account, as described in the previous section. You can also view the instructions in three additional ways:
- By clicking the + New System button in the bottom left corner of the main login screen
- In the NGINX Amplify documentation
- In this blog post
Follow these steps on each of your servers to install the NGINX Amplify agent and start monitoring NGINX:
- Either log into the server as root, or use the
sudocommand. (For you to be able to use this command, the local sudoers policy must grant you root privileges).
- Run this command to download the installation script (you can copy and paste the text below):
# curl -L -O https://raw.githubusercontent.com/nginxinc/nginx‑amplify‑agent/master/packages/install.sh
- Run the
install.shscript using your API_KEY (you can copy and paste the text below, but make sure to copy and paste the actual API_KEY from the on‑screen instructions in NGINX Amplify). For example:
The installation script runs automatically and sends output to your terminal as it progresses through roughly 15 steps. The NGINX Amplify agent then starts running.
# API_KEY='1234567890abcdef' sh ./install.sh
- After about a minute, check that the server appears in the Systems area of the Graphs page.
- Repeat the procedure above for all servers that need monitoring.
As you add servers, graphs appear in the Preview area of the Graphs page, displaying predefined metrics for each server. Within a few minutes, the graphs begin populating with the collected statistics.
When you click a system name in the Systems area of the Graphs page, small versions of graphs for that system appear in the Preview area. You can then click on a small graph to see a larger version in the Graph Feed area on the right. Expand your browser window to see larger versions of the graphs in the Graph Feed area.
After adding a few systems, your NGINX Amplify screen looks something like the following.
Note: You can add the NGINX Amplify agent to servers that don’t run NGINX or NGINX Plus if you find it convenient to do so. However, the information that NGINX Amplify provides for such servers is minimal.
Create a Dashboard for Monitoring
On the NGINX Amplify Dashboards page, you can configure custom graphs to report metrics of your choice. You can perform various operations on the incoming data, including filtering, summation and averaging of multiple metrics, and more. Use dashboards to monitor NGINX on specific servers or groups of servers, and to track specific microservices, entire applications, and more.
As an example, follow these steps to create an initial dashboard showing requests resulting in HTTP status code
- On the Dashboards drop‑down menu, click Create Dashboard.
- Click Add Graph in the upper right corner of the work area that appears.
- Enter a Title for your graph, such as 401 Errors.
- Choose the relevant metric from the drop‑down menu; in this case, it’s nginx.http.status.4xx. For NGINX Amplify list fields, such as this one, type in a character string to reduce the list of metrics to those that include the string you enter. For instance, you can type system to restrict the list to system metrics, or type nginx to restrict the list to NGINX metrics.
- Choose an NGINX instance from the drop‑down menu labeled Click to select NGINX.
- To apply a filter to the metric, click Apply filter. If you don’t apply a filter, the graph displays the combined count of all
- Click the drop‑down menu that appears, Click to select filter key. Choose the key value from the list; since we are filtering by HTTP status code in this scenario, it’s $status.
- Click Type or select filter value. Type 401, and click the words Use 401 as value, which appear as you type. (The filter doesn’t take effect if you type a value but don’t click the words that appear.)
- When you’ve filled in all fields with appropriate values, the Save button activates (turns green). Click it.
- The new graph appears on a new dashboard; it will be unpopulated until events that meet the filter conditions have occurred. To name the dashboard, click the default name (Untitled…), click Edit, and type the new name.
Adding an Alert
In addition to monitoring NGINX in real time, NGINX Amplify can alert you when the value of a certain metric goes outside a range that you define. Properly set up, alerts give you peace of mind, because you learn about unexpected server behavior very quickly. In some cases, an alert can tell you about a problem before it becomes visible to users; in other cases, an alert can ensure that, when a problem is becoming visible to users, you’re not the last to know.
- You can’t create alerts based on summaries or averages across a set of systems.
- Alerts are not filtered by hostname by default, so an alert tells you when any system goes outside the target range you’ve specified. To make an alert host‑specific, specify the hostname when configuring the alert.
Note: Every NGINX Amplify account has one predefined alert: you are alerted if NGINX Amplify goes down for more than two minutes. Remove this alert if you don’t need it.
Follow these steps to create an alert for checking a threshold for incoming bytes:
- On the Alerts page, click the Add new alert bar at the bottom of the page. The Create new alert dialog appears.
- Click the drop‑down menu labeled Click to select metric and click on a metric. (To narrow the list of choices to those that include a specific text string, type the string.)
- When you select a metric, more fields appear where you choose the factors to compare the metric against, such as a period of time and a threshold value. In Figure 5, we’ve created an alert that triggers when the inbound traffic exceeds 1 Mbps for more than 2 minutes.
- Optionally, specify one of your Systems which the alert applies to.
- If you don’t specify one system, the alert applies to each of your systems.
- Enter the Email address to notify when the alert is triggered. If the email address has not been previously used with NGINX Amplify, the system sends a verification email.
- Click Create alert.
Generate a Report About a System Configuration
When you install the agent software on a server, NGINX Amplify analyzes your configuration and generates a detailed report. The report includes status information and configuration advice:
- Status information. The current state of your NGINX instance, including the NGINX version, an overview of your configuration (including modules), security advisories, virtual servers, and SSL/TLS information.
- Static analysis. A breakdown of your configuration that provides recommendations to improve the performance, security, and reliability of your NGINX‑delivered applications.
Note: We recommend that you move to the most recent version of NGINX or NGINX Plus for optimal performance and security.
When you install the NGINX Amplify Agent on a system, we recommend that you review all sections of the report for actionable items, as follows:
- Version and Overview – Look for any surprises and address them.
- Security – Review and address all security advisories, as applicable.
- Virtual servers – Review Virtual servers to see a breakdown of configured servers and, if relevant, SSL/TLS information.
- SSL – Check the status of your SSL certificates and make sure nothing has expired. If you don’t want this analysis in the Reports, disable it in the Settings menu.
- Static analysis – Review and address all warnings as needed.
In a future blog post, we’ll go into depth about how to use the information on the Reports page.
We’re happy to provide this introduction to NGINX Amplify. We’ve shown you how to sign up, download the NGINX Amplify agent for each covered system, and set up initial graphs, dashboards, and alerts – as well as how to quickly evaluate the reports you get for each system. Future blog posts will go into more depth about how to get more out of NGINX Amplify.