Setting Up NGINX Amplify in 10 Minutes

This blog post is the first in a series about how to monitor NGINX and make the most out of your web delivery infrastructure with NGINX Amplify:

  1. Setting Up NGINX Amplify in 10 Minutes (this post)
  2. Improving Server Configuration with NGINX Amplify Reports
  3. Using NGINX Amplify Custom Dashboards and Filters for Better NGINX Monitoring
  4. Inside NGINX Amplify: Insights from Our Engineers

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.

In this first blog post in our series about how to monitor NGINX with NGINX Amplify, 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.

For more details about NGINX Amplify, see the related blog posts, our on‑demand webinar, and the official NGINX Amplify documentation on GitHub.

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:

  1. If possible, upgrade to the most recent version of NGINX or NGINX Plus.
  2. 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.
  3. Check that your Python version is supported. As of this writing, Python version 2.6 and 2.7 are supported – Python 3 is not.
  4. To get a full range of metrics:

  5. Make sure the directory and the configuration file where stub_status is defined are readable by the NGINX Amplify agent; if so, the agent accesses them automatically.
  6. 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:

  1. Visit the NGINX Amplify signup page.
  2. Fill in the form and agree to the Terms of Service.
  3. Click Sign up.

    Signup for an NGINX Amplify account by providing your name and company name and agreeing to the Terms of Service. This is the first step in the series on how to monitor NGINX.
    Figure 1. Enter your contact details on the NGINX Amplify Sign‑up screen
  4. 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:

  1. Either log into the server as root, or use the sudo command. (For you to be able to use this command, the local sudoers policy must grant you root privileges).
  2. 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
  3. Run the install.sh script 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:

    # API_KEY='1234567890abcdef' sh ./install.sh

    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.

  4. After about a minute, check that the server appears in the Systems area of the Graphs page.
  5. 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.

The NGINX Amplify Graphs page displays a list of modified systems, preview graphs for the selected system, and larger versions of some graphs for how to monitor NGINX
Figure 2. NGINX Amplify Graphs page with several systems monitored.

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 401 Unauthorized :

  1. On the Dashboards drop‑down menu, click Create Dashboard.
  2. Click Add Graph in the upper right corner of the work area that appears.
  3. Enter a Title for your graph, such as 401 Errors.
  4. 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.

  5. Choose an NGINX instance from the drop‑down menu labeled Click to select NGINX.
  6. 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 4xx errors.
  7. 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.
  8. 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.)

    In the 'Add graph to dashboard' dialog in NGINX Amplify, you create a custom graph by defining the metric, source, type of aggregation, and filter to apply [how to monitor NGINX with NGINX Amplify]
    Figure 3. Specifications for a new NGINX Amplify graph, ready to save.
  9. When you’ve filled in all fields with appropriate values, the Save button activates (turns green). Click it.
  10. 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.
A newly created NGINX Amplify dashboard with a single graph reporting errors with status code 401 [how to monitor NGINX with NGINX Amplify]
Figure 4. A new dashboard with a single graph.

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.

Two caveats:

  • 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:

  1. On the Alerts page, click the Add new alert bar at the bottom of the page. The Create new alert dialog appears.
  2. 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.)
  3. 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.
  4. Optionally, specify one of your Systems which the alert applies to.
  5. If you don’t specify one system, the alert applies to each of your systems.

  6. 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.
  7. Click Create alert.
In the 'Create new alert' dialog in NGINX Amplify, you create a custom alert by defining the metric, time period, threshold, system name, and recipient of the alert email [how to monitor NGINX with NGINX Amplify]
Figure 5. Create alerts in NGINX Amplify.

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.
The 'Version' tab on the NGINX Amplify Reports page reports the version of NGINX in use, the path to configuration files, and the number of config test and parser errors [how to monitor NGINX with NGINX Amplify]
Figure 6. Get an NGINX Configuration Report for each NGINX system you monitor.

In a future blog post, we’ll go into depth about how to use the information on the Reports page.

Summary

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. Our hope is that this blog post encourages you to sign up, or shows you how to get the most out of NGINX Amplify if you’ve already done so. Future blog posts will go into more depth about how to get more out of NGINX Amplify.

We look forward to your using NGINX Amplify, and to your feedback about how to improve it further. Use the ? icon in NGINX Amplify to provide feedback, or send us a message in the Comments section below.

Sign up for free and start using NGINX Amplify today.

Monitoring Highly Dynamic and Distributed Systems with NGINX Amplify

Cover image

Overcome challenges in collecting logs and metrics and acting on the results.