Modify ARMS agents for Java parameters and data reporting regions through a configuration file - Application Real-Time Monitoring Service

Application Real-Time Monitoring Service (ARMS) Java agents use static configuration files to control agent behavior, including application identity, instance tags, and data reporting regions.

Static configuration files have the lowest priority. Higher-priority sources, including dynamic configurations, Java system properties, and environment variables, override values set in configuration files:

Dynamic configurations (highest)
        ↓
Java system properties (-D flags)
        ↓
Environment variables
        ↓
Static configuration files (lowest)

When both a startup command flag (-D) and an environment variable specify the same setting, the startup command flag takes precedence.

Agents V4.x and later

In V4.x agents, all default configuration files are bundled inside the JAR package. To customize settings, create an external configuration file that overrides the built-in defaults.

Configure agent parameters

Create a .properties file, such as my-app.properties. Place it in the same directory as the agent JAR for easier management.

Add parameters as needed. All parameters default to empty. The last three parameters set instance tags in ARMS. Minimal configuration example Replace the following placeholders with actual values:

Parameter	Description
`arms.licenseKey`	LicenseKey for agent installation. Obtain it from the Java Application Monitor card on the Integration Center page, or by calling the DescribeTraceLicenseKey API.
`arms.appName`	Application name displayed in ARMS.
`profiler.tags.env`	Environment tag for the monitored instance.
`profiler.tags.version`	Version tag for the monitored instance.
`profiler.tags.customtags`	Custom instance tag.

Placeholder	Description	Example
`<your-license-key>`	ARMS LicenseKey	LTAI5tXxx
`<your-app-name>`	Application name	my-order-service

   arms.licenseKey=<your-license-key>
   arms.appName=<your-app-name>

Point the agent to your configuration file at startup. Use one of the following methods: Startup command flag Environment variable Replace /path/to/my-app.properties with the absolute path to your configuration file.
```
   -Dotel.javaagent.configuration-file=/path/to/my-app.properties
```
```
   OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/my-app.properties
```
Apply the modified configuration file to the installation of any ARMS agent for Java V4.x as needed.

Change the reporting region

The default reporting region depends on your integration method:

Integration method	Default region
Container Service for Kubernetes (ACK)	Region of your ACK cluster
Manual installation	Region of the Object Storage Service (OSS) bucket used for the agent download

Use one of the following methods to change the reporting region.

Method 1: ACK environment variable

For applications deployed in an ACK cluster:

Update the ack-onepilot component to V4.0.0 or later.
Add the ARMS_REPORT_REGION environment variable to the ack-onepilot-ack-onepilot application in the ack-onepilot namespace. Set the value to a supported ARMS region ID, such as cn-hangzhou or cn-beijing.
Restart existing applications or deploy new applications to apply the change.

Note

After you add this environment variable, all applications in the cluster report data to the specified region.

Method 2: Startup command flag or environment variable

Startup command flag

-Daliyun.javaagent.profileId=<region-id>

Environment variable

ALIYUN_JAVAAGENT_PROFILEID=<region-id>

Replace <region-id> with a supported ARMS region ID, such as cn-hangzhou.

Agents V3.x

Configure agent parameters

In the decompressed agent directory, open the arms-agent.config file.

Edit the parameters in arms-agent.config and save the file. You can also replace the file with a pre-configured version.

View the full arms-agent.config file (example)

########################################################################
#  Specify arms.licenseKey (obtained from the console) and arms.appName
#  (the name of the integrated application).
#
#  Example:
#  arms.licenseKey=XXXXXXXXXXXXXXX
#  arms.appName=Demo-Service
#
########################################################################

arms.licenseKey=

arms.appName=

########################################################################
#  The ARMS agent operates with default system configurations.
#  Maintain these settings to ensure system stability.
########################################################################

profiler.collector.trace.endpoint=arms-dc-hz.aliyuncs.com
profiler.collector.metric.endpoint=cn-hangzhou.arms.aliyuncs.com
profiler.collector.meta.endpoint=arms-dc-hz.aliyuncs.com
profiler.collector.endpoint=arms-dc-hz.aliyuncs.com


profiler.log.report.support=true

profiler.acm.endpoint=addr-hz-internal.edas.aliyun.com
profiler.acm.tenant=c845a7b4-23a1-4f28-a380-5ab30d8a280f
profiler.acm.region.id=cn-hangzhou

# The region where the ARMS agent reports the Microservices Engine (MSE) monitoring data.
profiler.mse.region=cn-hangzhou


# The agent log level: ERROR < WARN <  INFO <  DEBUG < TRACE
# Settings with a higher priority will output logs with a lower level.
profiler.agent.logger.level=WARN

# Global configuration: specifies whether to enable instrumentation. Retain the value true for the agent to work properly.
profiler.enable=true

# Global configuration: specifies whether to enable sampling function is enabled. Retain the value true to sample data properly.
profiler.sampling.enable=true

# Global configuration: the sampling rate, unit: %.
profiler.sampling.rate=10

###########################################################
# Dubbo                                                   #
###########################################################
profiler.dubbo.enable=true

###########################################################
# Google HTTP Client                                      #
###########################################################
profiler.googlehttpclient.enable=true

###########################################################
# Alibaba Cloud High-speed Service Framework (HSF)        #
###########################################################
profiler.hsf.enable=true

###########################################################
# HTTPClient3                                             #
###########################################################
profiler.httpclient3.enable=true

###########################################################
# HTTPClient4                                             #
###########################################################
profiler.httpclient4.enable=true

###########################################################
# JDK HTTP                                                #
###########################################################
profiler.jdkhttp.enable=true

###########################################################
# Jetty                                                   #
###########################################################
profiler.jetty.enable=true

###########################################################
# MyBatis                                                 #
###########################################################
profiler.mybatis.enable=true

###########################################################
# MySQL JDBC                                             #
###########################################################
profiler.mysql.enable=true

###########################################################
# OkHttp                                                 #
###########################################################
profiler.okhttp.enable=true

###########################################################
# Oracle JDBC                                             #
###########################################################
profiler.oracle.enable=true

###########################################################
# PostgreSQL JDBC                                         #
###########################################################
profiler.postgresql.enable=true

###########################################################
# Redis                                                   #
###########################################################
profiler.redis.enable=true

###########################################################
# Spring                                                  #
###########################################################
profiler.spring.enable=true

###########################################################
# Spring-boot                                             #
###########################################################
profiler.springboot.enable=true

###########################################################
# Tomcat                                                  #
###########################################################
profiler.tomcat.enable=true

###########################################################
# MongoDB                                                 #
###########################################################
profiler.mongodb.enable=true

###########################################################
# Lettuce                                                 #
###########################################################
profiler.lettuce.enable=true

###########################################################
# GRPC                                                    #
###########################################################
profiler.grpc.enable=true

###########################################################
# Thrift                                                  #
###########################################################
profiler.thrift.enable=true

###########################################################
# Memcached                                               #
###########################################################
profiler.memcached.enable=true

# Configurations for an invalid URL.


profiler.thresholds.limit=100

profiler.defined.method=

profiler.callstack.maxLength=128

profiler.callsql.maxLength=1024

profiler.tprof.enableThreadProfiler=true

profiler.alibabacloud.metaserver.address=100.100.100.200
###########################################################
# SOFARPC                                                #
###########################################################
profiler.sofa.rpc.enable=true

profiler.exception.stacktrace=2

###########################################################
# Tags                                                    #
###########################################################
#profiler.tags.env=prod
profiler.tags.env=

#profler.tags.version=v1.0
profiler.tags.version=

#profiler.tags.customtags=key1:value1&key2:value2
profiler.tags.customtags=

Important

Do not modify parameters other than those listed in the following table. Changing other parameters may cause unexpected sampling behavior. To adjust agent settings beyond these parameters, see Customize settings for a Java application.

The following table lists the parameters that you can safely modify.

Note

The profiler.tags.env, profiler.tags.version, and profiler.tags.customtags parameters specify the instance tags monitored in ARMS.
The last six parameters use the China (Hangzhou) region for example only.

Parameter	Description	Default value
`arms.licenseKey`	LicenseKey for agent installation. Obtain it from the Java Application Monitor card on the Integration Center page, or by calling the DescribeTraceLicenseKey API.	-
`arms.appName`	Application name displayed in ARMS.	-
`profiler.tags.env`	Environment tag for the monitored instance.	-
`profiler.tags.version`	Version tag for the monitored instance.	-
`profiler.tags.customtags`	Custom instance tag.	-
`profiler.collector.trace.endpoint`	Endpoint for trace data reporting.	arms-dc-hz.aliyuncs.com
`profiler.collector.metric.endpoint`	Endpoint for metric data reporting.	cn-hangzhou.arms.aliyuncs.com
`profiler.collector.meta.endpoint`	Endpoint for metadata reporting.	arms-dc-hz.aliyuncs.com
`profiler.collector.endpoint`	Endpoint for other data reporting.	arms-dc-hz.aliyuncs.com
`profiler.acm.endpoint`	Endpoint for Application Configuration Management (ACM) dynamic configurations.	addr-hz-internal.edas.aliyun.com
`profiler.acm.region.id`	Region ID for ACM dynamic configurations.	cn-hangzhou

Apply the modified configuration file to the installation of any ARMS agent for Java V3.x as needed.

Change the reporting region

The default reporting region depends on your integration method:

Integration method	Default region
Container Service for Kubernetes (ACK)	Region of your ACK cluster
Manual installation	Region of the OSS bucket used for the agent download

Use one of the following methods to change the reporting region.

Method 1: ACK environment variable (recommended)

For applications deployed in an ACK cluster:

Update the ack-onepilot component to V4.0.0 or later.
Add the ARMS_REPORT_REGION environment variable to the ack-onepilot-ack-onepilot application in the ack-onepilot namespace. Set the value to a supported ARMS region ID, such as cn-hangzhou or cn-beijing.
Restart existing applications or deploy new applications to apply the change.

Note

After you add this environment variable, all applications in the cluster report data to the specified region.

Method 2: Reinstall the agent (recommended)

For a manually installed agent, download a new installation package from the target region and reinstall the agent.

Method 3: Edit endpoint parameters (not recommended)

Modify the following parameters in arms-agent.config to point to the target region: profiler.collector.trace.endpoint, profiler.collector.metric.endpoint, profiler.collector.meta.endpoint, profiler.collector.endpoint, profiler.acm.endpoint, and profiler.acm.region.id. For endpoint values, see ARMS endpoints.

Important

The ARMS agent performs Virtual Private Cloud (VPC) connectivity checks. If VPC connectivity fails, the agent automatically falls back to the public network. Use VPC endpoints whenever possible.

Agents V2.x (deprecated)

ARMS Application Monitoring no longer supports Java agents V2.x. Upgrade your agent to V3.x or later as soon as possible.