Enable Metrics

Learn how to enable and use metrics for NGINX Management Suite API Connectivity Manager.

This documentation applies to NGINX Management Suite API Connectivity Manager 1.3.0 and later.

Overview

This guide walks through setting up and using metrics in NGINX Management Suite API Connectivity Manager (ACM).

Important:
The configuration presented in this guide is for demonstration purposes only. Securely configuring environments and proxies in ACM is not in scope for this tutorial but should be given full attention when planning for production use.

Currently, only the following metric is available:

Count of proxies in an environment

As we add new metrics, we’ll let you know in the ACM release notes and update this topic accordingly.

Before You Begin

To complete the instructions in this guide, you need the following:

Access to a virtual environment

Four virtual hosts with Linux installed — this guide uses Ubuntu 20.04 LTS.

Supported Linux distributions

The NGINX Management Suite gateway supports the following Linux distributions:

Distribution	Version	Architecture	Instance Manager	ACM	Notes
Amazon Linux	2 LTS	x86_64	2.0.0 and later	1.0.0 and later
CentOS	7.4 and later in the 7.x family	x86_64	2.0.0 and later	1.0.0 and later
Debian	10 11	x86_64 x86_64	2.0.0 and later 2.0.0 and later	1.0.0 and later 1.0.0 and later
Oracle Linux	7.4 and later in the 7.x family 8.0 and later in the 8.0.x family	x86_64 x86_64	2.0.0 and later 2.6.0 and later	1.0.0 and later Not supported
RHEL	7.4 and later in the 7.x family 8.x and later in the 8.x family 9.x and later in the 9.x family	x86_64 x86_64 x86_64	2.0.0 and later 2.0.0 and later 2.6.0 and later	1.0.0 and later 1.0.0 and later Not supported
Ubuntu	18.04 20.04 22.04	x86_64 x86_64 x86_64	2.0.0 and later 2.0.0 and later 2.3.0 and later	1.0.0 and later 1.0.0 and later 1.0.0 and later	Configuration Management for App Protect WAF is not compatible with Ubuntu 22.04.

Host Setup

This section configures the hosts used in this tutorial. In the following table, you’ll find the details of the test environment used in this tutorial’s examples. The options presented are the minimum host requirements for running a fully functional test environment. Remember that production environments may need more resources and incur greater costs.

Hosts	Virtual Cores	Memory	Storage	IP Address	Hostname
NGINX Management Suite Host	2 vCPUs	4GB	100GB	`192.0.2.2`	`acm-ctrl`
Data Plane Host	1 vCPU	1GB	10GB	`192.0.2.3`	`data-host`
Echo Server	1 vCPU	1GB	10GB	`192.0.2.4`	`echo-host`

Install NGINX Management Suite & API Connectivity Manager

Follow the steps in the Installation Guide to set up NGINX Management Suite and ACM. You do not need to configure a Developer Portal for this tutorial.

Install NGINX Agent on Data Plane Host

Run the following commands to install the NGINX Agent on the data plane host, create a new Instance Group called test-ig, and add the host to it:

curl -k https://192.0.2.2/install/nginx-agent > install.sh \
&& sudo sh install.sh -g test-ig \
&& sudo systemctl start nginx-agent

Install Echo Server

Note:
The server is designed for testing HTTP proxies and clients. It echoes information about HTTP request headers and bodies back to the client.

Download and install the latest version of Go by following the instructions on the official Go website.

Run the following commands to install and start Echo Server:

go env -w GO111MODULE=off
go get -u github.com/jmalloc/echo-server/...
PORT=10000 LOG_HTTP_BODY=true LOG_HTTP_HEADERS=true echo-server

Configure API Connectivity Manager

In this section, we use the ACM REST API to set up a proxy in ACM. You need to pass the NGINX Management Suite user credentials in the Basic Authentication header for each REST request.

Create Workspaces & Environment

To create an Infrastructure Workspace with a minimum configuration, send the following JSON request to the /infrastructure/workspaces endpoint:
```
POST https://192.0.2.2/api/acm/v1/infrastructure/workspaces
```
JSON Request
```
{
   "name": "infra-ws"
}
```
To create an environment with a minimum configuration, send the following JSON request to the /infrastructure/workspaces/infra-ws/environments endpoint. The proxyClusterName: test-ig is the name of the Instance Group that the data plane host was added to when you installed the NGINX Agent above. The hostnames array should contain the hostname of the data plane host.
```
POST https://192.0.2.2/api/acm/v1/infrastructure/workspaces/infra-ws/environments
```
JSON Request
```
{
   "name": "demo-env",
   "proxies": [
      {
         "proxyClusterName": "test-ig",
         "hostnames": [
            "data-host"
         ]
      }
   ]
}
```
To create a Service Workspace with a minimum configuration, send the following JSON request to the /services/workspaces endpoint.
```
POST https://192.0.2.2/api/acm/v1/services/workspaces
```
JSON Request
```
{
   "name": "service-ws"
}
```

Create a Basic API Proxy

To create an API proxy with a minimum configuration and the default policies, send the following JSON request to the /services/workspaces/service-ws/proxies endpoint. The Proxy service target is our Echo Server.

POST https://192.0.2.2/api/acm/v1/services/workspaces/service-ws/proxies

JSON Request

{
   "name": "test-proxy",
   "version": "v1",
   "proxyConfig": {
      "hostname": "data-host",
      "ingress": {
         "basePath": "/",
         "basePathVersionAppendRule": "NONE"
      },
      "backends": [
         {
            "serviceName": "backend-echo-svc",
            "serviceTargets": [
               {
                  "hostname": "192.0.2.4",
                  "listener": {
                     "enableTLS": false,
                     "port": 10000,
                     "transportProtocol": "HTTP"
                  }
               }
            ]
         }
      ]
   }
}

To test whether the API Proxy and backend Echo Server are working correctly, send a custom header and dummy JSON body to show these proxied values in the Echo Server response:

POST https://192.0.2.4/my/test/api
HEADERS:
   X-NGINX-Test: true

JSON Request

{
   "testKey": "testValue"
}

Verification

If everything is configured correctly in ACM and the Echo Server, the response should be similar to the following example:

Request served by echo-host

HTTP/1.0 POST /my/test/api

Host: 192.0.2.4
Accept: */*
Cache-Control: no-cache
Content-Length: 30
Content-Type: application/json
X-Correlation-Id: c241b72519e71cf7bce9262910ffbe40
X-Real-Ip: 192.0.2.1
X-NGINX-Test: true

{"testKey": "testValue"}

Get Count of Proxies in an Environment

To get the count of active proxies, send the following REST request to the /infrastructure/workspaces/infra-ws/environments/demo-env/api-count endpoint:

GET https://192.0.2.2/api/acm/v1/infrastructure/workspaces/infra-ws/environments/demo-env/api-count

If you’ve successfully configured a proxy the following count is returned.

Response