Enable Metrics

This guide walks through setting up and using metrics in API Connectivity Manager.

Important
The configuration presented in this guide is for demonstration purposes only. Securely configuring environments and proxies in API Connectivity Manager 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:

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


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 following table lists the Linux distributions supported by NGINX Instance Manager and NGINX App Protect:

    Distribution Version Architecture NGINX Instance Manager Support NGINX App Protect Support
    Amazon Linux 2 LTS x86_64 Supported Support discontinued as of 2.18.0
    CentOS 7.4 and later in the 7.x family x86_64 Support discontinued as of 2.17.0 Supported
    Debian 11
    12
    x86_64
    x86_64
    Supported
    Supported on 2.13.0+
    Supported
    Supported
    Oracle Linux 7.4 and later in the 7.x family
    8.0 and later in the 8.x family
    x86_64
    x86_64
    Supported
    Supported on 2.6.0+
    Supported
    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
    Support discontinued as of 2.17.0
    Supported
    Supported on 2.6.0+
    Supported
    Supported
    Supported
    Ubuntu 20.04
    22.04
    24.04
    x86_64
    x86_64
    x86_64
    Supported
    Supported on 2.3.0+
    Supported on 2.18.0+
    Supported
    Supported
    Supported

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
F5 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

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

In /etc/nms/acm.conf, uncomment and set the enable_metrics property to true.

bash
# set to true to enable metrics markers from the acm code
enable_metrics = true

Run the following command to restart the API Connectivity Manager service:

sudo systemctl restart nms-acm

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:

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

To ensure that the advanced metrics modules are installed across all data plane hosts, please follow the steps in the Install NGINX Plus Metrics Module guide.


The server is designed for testing HTTP proxies and clients. It echoes information about HTTP request headers and bodies back to the client.
  1. Download and install the latest version of Go by following the instructions on the official Go website.

  2. Run the following commands to install and start Echo Server:

    shell
    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

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

  1. 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

    json
    {
       "name": "infra-ws"
    }
  2. 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

    json
    {
       "name": "demo-env",
       "proxies": [
          {
             "proxyClusterName": "test-ig",
             "hostnames": [
                "data-host"
             ]
          }
       ]
    }
  3. 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

    json
    {
       "name": "service-ws"
    }

  1. 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

    json
    {
       "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"
                      }
                   }
                ]
             }
          ]
       }
    }
  2. 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:

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

    JSON Request

    json
    {
       "testKey": "testValue"
    }

    Verification

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

    bash
    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"}

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:

    1

  1. On the left menu, select Infrastructure.
  2. Select a workspace from the table.
  3. Select the Actions menu (represented by an ellipsis, ...) next to your environment on the Actions column.
  4. Select Metrics.
  5. Update the start and end time of the metrics with the time range selection on the dashboard overview.
  6. To view metrics broken down by cluster in the environment, select the API Gateway Clusters tab.

  1. On the left menu, select Services.
  2. Select a workspace from the table.
  3. Select the Actions menu (represented by an ellipsis, ...) next to your environment on the Actions column.
  4. Select Metrics.
  5. Update the start and end time of the metrics with the time range selection on the dashboard overview.
  6. Filter by advanced routes with the advanced route selection on the dashboard overview.
  7. To view metrics broken down by status code in the proxy, select the API Gateway Clusters tab.