Use an Nginx forward proxy to connect applications to ARMS - Application Real-Time Monitoring Service

If your Java application runs in a network-restricted environment without direct Internet access, use NGINX as a forward proxy to relay monitoring data from the Application Real-Time Monitoring Service (ARMS) agent to the ARMS backend.

When to use a forward proxy

ARMS Application Monitoring requires network connectivity between the ARMS agent and the ARMS backend. Applications deployed in data centers or third-party cloud environments typically connect through the Internet or an Express Connect circuit. For more information, see Application Monitoring overview.

In network-restricted environments -- such as financial systems or security-sensitive data centers -- some hosts cannot access the Internet directly. In these cases, deploy NGINX as a forward proxy in the DMZ to relay data between the isolated application network and the ARMS backend.

Architecture

Data flows through three stages:

The ARMS agent collects traces, metrics, profiling data, and metadata from the Java application.
The agent sends all data to NGINX in the DMZ, rather than directly to the ARMS backend.
NGINX forwards each data type to the corresponding ARMS endpoint over the Internet.

To set this up, configure two components:

NGINX -- Proxy rules that forward each data type (traces, metrics, profiling, metadata) to the correct ARMS endpoint.
ARMS agent -- Endpoint settings that redirect data reporting to NGINX.

Prerequisites

Before you begin, make sure that you have:

NGINX installed and running with Internet access. For installation instructions, see the NGINX official documentation
The ARMS endpoints and ACM engine IP address for your Alibaba Cloud region. For details, see Network configurations required by the ARMS agent for Java
Your Alibaba Cloud account ID. For details, see How do I view the ID of an Alibaba Cloud account?

Configure NGINX

Edit /etc/nginx/site-available/default and add the following server blocks. Each block proxies a specific data type to the corresponding ARMS endpoint.

Replace the placeholder values with the endpoints and account ID from the prerequisites.

# --- Traces and continuous profiling (port 80) ---
server {
  listen 80 default_server;
  listen [::]:80 default_server;

  server_name arms-service;
  ignore_invalid_headers off;

  # Continuous profiling: replace <account-id> with your Alibaba Cloud account ID,
  # and replace the URL with your region's continuous profiling endpoint.
  location /<account-id> {
    proxy_pass http://arms-profiling-cn-shenzhen.oss-cn-shenzhen.aliyuncs.com;
  }

  # Traces: replace the URL with your region's trace endpoint.
  location / {
    proxy_pass http://arms-dc-sz.aliyuncs.com;
  }
}

# --- Metadata (port 9990) ---
server {
  listen 9990;
  server_name arms-meta;
  ignore_invalid_headers off;

  # Metadata: replace the URL with your region's trace endpoint (port 9990).
  location / {
    proxy_pass http://arms-dc-sz.aliyuncs.com:9990;
  }
}

# --- Metrics (port 80) ---
server {
  listen 80;
  server_name arms-metrics;
  ignore_invalid_headers off;

  # Metrics: replace the URL with your region's metric endpoint.
  location / {
    proxy_pass http://cn-shenzhen.arms.aliyuncs.com;
  }
}

# --- ACM engine discovery (port 8080) ---
server {
  listen 8080;
  server_name arms-acm;
  ignore_invalid_headers off;

  # Returns the server IP address for ACM engine discovery.
  location / {
    return 200 $server_addr;
  }
}

# --- ACM engine (port 8848) ---
server {
  listen 8848;
  server_name arms-acm;
  ignore_invalid_headers off;

  # ACM engine: replace the IP address with your region's ACM engine IP.
  location / {
    proxy_pass http://139.196.XX.XX:8848;
  }
}

The following table summarizes the port-to-data-type mapping:

Port	Server name	Data type	Proxy target
80	arms-service	Traces + continuous profiling	Trace endpoint and profiling OSS endpoint
9990	arms-meta	Metadata	Trace endpoint (port 9990)
80	arms-metrics	Metrics	Metric endpoint
8080	arms-acm	ACM engine discovery	Returns NGINX server IP
8848	arms-acm	ACM engine	ACM engine IP (port 8848)
9092	(stream block)	Diagnostic channel	Trace endpoint (port 9092)

Next, edit /etc/nginx/nginx.conf and add the following stream block for diagnostic channel forwarding:

# --- Diagnostic channel (port 9092) ---
stream {
    upstream arms-arthas {
        # Replace the URL with your region's trace endpoint.
        server arms-dc-sz.aliyuncs.com:9092;
    }

    server {
        listen 9092;
        proxy_pass arms-arthas;
    }
}

Note

The communication between NGINX and the ARMS backend uses HTTP. If your security policy requires encryption between the ARMS agent and NGINX, configure TLS on NGINX and update the agent endpoints accordingly.

Configure the ARMS agent

After NGINX is running, redirect the ARMS agent to report data through NGINX instead of the public ARMS endpoints. The forward proxy mode works with both manually installed agents and agents automatically installed in Kubernetes environments. For installation details, see Manually install an ARMS agent and Automatically install an ARMS agent in an open-source Kubernetes cluster.

Choose the section that matches your agent version and installation method.

The following table lists the agent endpoint parameters used in both versions:

Parameter	Value	Data type
`profiler.collector.trace.endpoint`	`arms-service`	Traces
`profiler.collector.metric.endpoint`	`arms-metrics`	Metrics
`profiler.collector.meta.endpoint`	`arms-meta`	Metadata
`profiler.collector.endpoint`	`arms-service`	General collection
`profiler.acm.endpoint`	`arms-acm`	ACM engine
`profiler.oss.endpoint`	`arms-service`	Continuous profiling (V3.2.0+)

Agent V4.x and later

Manual installation

Step 1: Add host entries

Add the following entries to /etc/hosts on the server where the application runs. Replace 10.0.0.201 with the IP address of your NGINX server.

10.0.0.201 arms-service
10.0.0.201 arms-metrics
10.0.0.201 arms-meta
10.0.0.201 arms-acm
# Replace cn-shanghai with your Alibaba Cloud region code.
10.0.0.201 arms-profiling-cn-shanghai.arms-service

Note

The ARMS agent resolves endpoint hostnames to connect to the backend. By mapping these hostnames to the NGINX IP in /etc/hosts, the agent sends data to NGINX without code changes.

Step 2: Update agent endpoint settings

Use one of the following methods:

Method 1: Configuration file (recommended)

Create an arms-agent.config file in the agent's root directory with the following parameters:

profiler.collector.trace.endpoint=arms-service
profiler.collector.metric.endpoint=arms-metrics
profiler.collector.meta.endpoint=arms-meta
profiler.collector.endpoint=arms-service
profiler.acm.endpoint=arms-acm
profiler.oss.endpoint=arms-service

Add the following JVM startup parameter to point the agent to this file:

-Darms.config.file=/path/to/arms-agent.config

Replace /path/to/arms-agent.config with the absolute path to your configuration file.

Method 2: JVM startup parameters

Pass all endpoint settings directly as JVM parameters:

-Dprofiler.collector.trace.endpoint=arms-service -Dprofiler.collector.metric.endpoint=arms-metrics -Dprofiler.collector.meta.endpoint=arms-meta -Dprofiler.collector.endpoint=arms-service -Dprofiler.acm.endpoint=arms-acm -Dprofiler.oss.endpoint=arms-service

Note

The configuration file (Method 1) is easier to maintain across multiple applications. JVM parameters (Method 2) work well for quick testing or single-application deployments.

Automatic installation in Kubernetes environments

Note

Before configuring a forward proxy for an automatically installed agent, update the agent to V3.2.0 or later.

Step 1: Get the current agent configuration

Log in to a pod that has the ARMS agent installed. Copy the contents of the agent configuration file at /home/admin/.opt/ArmsAgent/arms-agent.config.

Step 2: Create a ConfigMap

In the copied configuration, replace the endpoint values with the NGINX proxy hostnames:

profiler.collector.trace.endpoint=arms-service
profiler.collector.metric.endpoint=arms-metrics
profiler.collector.meta.endpoint=arms-meta
profiler.collector.endpoint=arms-service
profiler.acm.endpoint=arms-acm
profiler.oss.endpoint=arms-service

Create a ConfigMap from the modified configuration:

apiVersion: v1
kind: ConfigMap
metadata:
  name: arms-agent-proxy-mode.config
data:
  arms-agent.config: |-
    ### Paste your modified configuration here.
    profiler.collector.trace.endpoint=arms-service
    profiler.collector.metric.endpoint=arms-metrics
    profiler.collector.meta.endpoint=arms-meta
    profiler.collector.endpoint=arms-service
    profiler.acm.endpoint=arms-acm
    profiler.oss.endpoint=arms-service
    ### Paste your modified configuration here.

Step 3: Update the workload Deployment

Modify the Deployment YAML to mount the ConfigMap and add host aliases. Pay attention to the inline comments that highlight the values to customize.

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: spring-boot-demo
  name: spring-boot-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: spring-boot-demo
  template:
    metadata:
      labels:
        app: spring-boot-demo
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: spring-boot-demo
    spec:
      hostAliases:
      # Replace the IP address with the IP address of your NGINX server.
      - ip: "192.168.172.171"
        hostnames:
        - "arms-service"
        - "arms-metrics"
        - "arms-meta"
        - "arms-acm"
        # Replace cn-shenzhen with your Alibaba Cloud region code.
        - "arms-profiling-cn-shenzhen.arms-service"
      containers:
        - env:
            # Point the agent to the proxy-mode configuration file.
            - name: ARMS_CONFIG_FILE
              value: /home/admin/.opt/ArmsAgent/arms-agent-proxy-mode.config
          image: >-
            registry.cn-hangzhou.aliyuncs.com/ahas_apsara_adp/spring-boot-demo:wt-test
          imagePullPolicy: Always
          name: spring-boot-demo
          ports:
            - containerPort: 80
              protocol: TCP
          resources:
            limits:
              cpu: 500m
              memory: 1Gi
            requests:
              cpu: 250m
              memory: 512Mi
          volumeMounts:
            # Mount the proxy-mode configuration into the agent directory.
            - mountPath: /home/admin/.opt/ArmsAgent/
              name: arms-agent-proxy-mode
      imagePullSecrets:
        - name: wt-test
      volumes:
        # Map the ConfigMap to a volume.
        - configMap:
            name: arms-agent-proxy-mode.config
          name: arms-agent-proxy-mode

Agent V3.x and earlier

Manual installation

Step 1: Add host entries

Add the following entries to /etc/hosts on the server where the application runs. Replace 10.0.0.201 with the IP address of your NGINX server.

10.0.0.201 arms-service
10.0.0.201 arms-metrics
10.0.0.201 arms-meta
10.0.0.201 arms-acm
# Replace cn-shanghai with your Alibaba Cloud region code.
10.0.0.201 arms-profiling-cn-shanghai.arms-service

Step 2: Edit the agent configuration file

Open arms-agent.config in the agent's directory and update the following parameters:

# These 5 parameters exist in all agent versions:
profiler.collector.trace.endpoint=arms-service
profiler.collector.metric.endpoint=arms-metrics
profiler.collector.meta.endpoint=arms-meta
profiler.collector.endpoint=arms-service
profiler.acm.endpoint=arms-acm
# Added in agent V3.2.0 and later:
profiler.oss.endpoint=arms-service

Automatic installation in Kubernetes environments

Note

Before configuring a forward proxy for an automatically installed agent, update the agent to V3.2.0 or later.

Step 1: Get the current agent configuration

Log in to a pod that has the ARMS agent installed. Copy the contents of the agent configuration file at /home/admin/.opt/ArmsAgent/arms-agent.config.

Step 2: Create a ConfigMap

In the copied configuration, replace the endpoint values with the NGINX proxy hostnames:

profiler.collector.trace.endpoint=arms-service
profiler.collector.metric.endpoint=arms-metrics
profiler.collector.meta.endpoint=arms-meta
profiler.collector.endpoint=arms-service
profiler.acm.endpoint=arms-acm
profiler.oss.endpoint=arms-service

Create a ConfigMap from the modified configuration:

apiVersion: v1
kind: ConfigMap
metadata:
  name: arms-agent-proxy-mode.config
data:
  arms-agent.config: |-
    ### Paste your modified configuration here.
    profiler.collector.trace.endpoint=arms-service
    profiler.collector.metric.endpoint=arms-metrics
    profiler.collector.meta.endpoint=arms-meta
    profiler.collector.endpoint=arms-service
    profiler.acm.endpoint=arms-acm
    profiler.oss.endpoint=arms-service
    ### Paste your modified configuration here.

Step 3: Update the workload Deployment

Modify the Deployment YAML to mount the ConfigMap and add host aliases. Pay attention to the inline comments that highlight the values to customize.

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: spring-boot-demo
  name: spring-boot-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: spring-boot-demo
  template:
    metadata:
      labels:
        app: spring-boot-demo
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: spring-boot-demo
    spec:
      hostAliases:
      # Replace the IP address with the IP address of your NGINX server.
      - ip: "192.168.172.171"
        hostnames:
        - "arms-service"
        - "arms-metrics"
        - "arms-meta"
        - "arms-acm"
        # Replace cn-shenzhen with your Alibaba Cloud region code.
        - "arms-profiling-cn-shenzhen.arms-service"
      containers:
        - env:
            # Point the agent to the proxy-mode configuration file.
            - name: ARMS_CONFIG_FILE
              value: /home/admin/.opt/ArmsAgent/arms-agent-proxy-mode.config
          image: >-
            registry.cn-hangzhou.aliyuncs.com/ahas_apsara_adp/spring-boot-demo:wt-test
          imagePullPolicy: Always
          name: spring-boot-demo
          ports:
            - containerPort: 80
              protocol: TCP
          resources:
            limits:
              cpu: 500m
              memory: 1Gi
            requests:
              cpu: 250m
              memory: 512Mi
          volumeMounts:
            # Mount the proxy-mode configuration into the agent directory.
            - mountPath: /home/admin/.opt/ArmsAgent/
              name: arms-agent-proxy-mode
      imagePullSecrets:
        - name: wt-test
      volumes:
        # Map the ConfigMap to a volume.
        - configMap:
            name: arms-agent-proxy-mode.config
          name: arms-agent-proxy-mode

Verify the setup

Log in to the ARMS console.
In the left-side navigation pane, choose Application Monitoring > Application List.
Restart your application and wait approximately 2 minutes.
Confirm that the application appears on the Application List page and that monitoring data is being reported.

Troubleshooting

If the application does not appear after 2 minutes:

Symptom	What to check	How to check
No requests in NGINX logs	NGINX is not receiving data from the agent	Review `/var/log/nginx/access.log` for incoming requests. If empty, the agent cannot reach NGINX.
`ping arms-service` does not resolve to NGINX IP	DNS resolution is incorrect	Verify `/etc/hosts` entries (manual installation) or `hostAliases` configuration (Kubernetes).
NGINX receives requests but ARMS shows no data	NGINX cannot reach ARMS backend	From the NGINX host, run `curl -I http://<trace-endpoint>` to confirm Internet connectivity.
Agent starts but reports connection errors	Agent endpoint parameters are incorrect	Confirm that endpoint parameters point to `arms-service`, `arms-metrics`, `arms-meta`, and `arms-acm`.