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

You can control the default configurations of Application Real-Time Monitoring Service (ARMS) agents for Java through static configuration files.

Static configuration files only modify some static configurations and default configurations. The priority for these configurations is lower than that for dynamic configurations, Java system properties, and environment variables.

Agents V4.x and later

For these agents, all configuration files are built into the JAR package. You can create an external configuration file for writing external parameters. External configuration files override built-in configuration files in the JAR package, but are still below dynamic configurations, Java system properties, and environment variables.

Modify agent configurations

Create an agent configuration file with the extension .properties, such as my-app.properties, preferably in the directory where the agent is.

Write the following parameters as needed. Their default values are all empty.

Parameter	Description
arms.licenseKey	The LicenseKey required for installing the agent. You can obtain it by clicking the Java Application Monitor card on the Integration Center page in the ARMS console, or by calling DescribeTraceLicenseKey on the OpenAPI platform.
arms.appName	The application name.
profiler.tags.env	The application environment tag.
profiler.tags.version	The application version tag.
profiler.tags.customtags	Custom instance tag of the application.

The last three configuration items specify the tags of the instance monitored in ARMS.

When the agent starts, add -Dotel.javaagent.configuration-file=/path/to/my-app.properties to the startup command or set the environment variable OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/my-app.properties.
Note
- Replace /path/to/my-app.properties with the absolute path of the configuration file.
- When both the startup command and environment variable are configured, the startup command takes precedence.
Apply the modified configuration file to the installation of any ARMS agent for Java V4.x as needed.

Modify the reporting region

The default data reporting region depends on how it's integrated:

Integration through Alibaba Cloud Container Service for Kubernetes (ACK): The region of your ACK cluster.
Manual integration: The region of the Object Storage Service (OSS) bucket used for agent downloads.

To modify the region where the agent reports monitoring data:

Method 1

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. The value must be the ID of a region where ARMS is available. Example: cn-hangzhou or cn-beijing.
Restart the existing application or deploy a new application to report data across regions.
Note
After the environment variable is added, all applications deployed in the cluster report data to the region specified in the previous step.

Method 2

Add -Daliyun.javaagent.profileId=cn-hangzhou to the startup command, or add the ALIYUN_JAVAAGENT_PROFILEID=cn-hangzhou environment variable.

Note

Replace cn-hangzhou with any reporting region supported by ARMS.
When both the startup command and environment variable are configured, the startup command takes precedence.

Agents V3.x

Modify agent configurations

Go to the decompressed agent directory and find the arms-agent.config file.

Modify the configurations in the arms-agent.config file and save the changes, or replace them with an arms-agent.config file you prepared.

Expand to View the 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 other parameters in the configuration file, because this may lead to unexpected sampling results. To modify agent configurations, see Customize settings for a Java application.

Parameter	Description	Default value
arms.licenseKey	The LicenseKey required for installing the agent. Obtain it by clicking the Java Application Monitor card on the Integration Center page in the ARMS console, or by calling DescribeTraceLicenseKey on the OpenAPI platform.	-
arms.appName	The application name.	-
profiler.tags.env	The application environment tag.	-
profiler.tags.version	The application version tag.	-
profiler.tags.customtags	Custom instance tag of the application.	-
profiler.collector.trace.endpoint	Endpoint for reporting trace data.	arms-dc-hz.aliyuncs.com
profiler.collector.metric.endpoint	Endpoint for reporting metric data.	cn-hangzhou.arms.aliyuncs.com
profiler.collector.meta.endpoint	Endpoint for reporting metadata.	arms-dc-hz.aliyuncs.com
profiler.collector.endpoint	Endpoint for reporting other information.	arms-dc-hz.aliyuncs.com
profiler.acm.endpoint	Endpoint for listening dynamic configurations of Application Configuration Management (ACM).	addr-hz-internal.edas.aliyun.com
profiler.acm.region.id	Region where the dynamic configuration of ACM is.	cn-hangzhou

Note

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

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

Modify the reporting region

The default data reporting region depends on how it's integrated:

Integration through Alibaba Cloud Container Service for Kubernetes (ACK): The region of your ACK cluster.
Manual integration: The region of the Object Storage Service (OSS) bucket used for agent downloads.

To modify the region where the agent reports monitoring data:

Method 1 (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. The value must be the ID of a region where ARMS is available. For example, you can set the value to cn-hangzhou or cn-beijing.
Restart the existing application or deploy a new application to report data across regions.
Note
After the environment variable is added, all applications deployed in the cluster report data to the region specified in the previous step.

Method 2 (recommended)

For a manually installed agent, obtain a new installation package in the target region, and reinstall the agent.

Method 3 (not recommended)

Modify the parameters profiler.collector.trace.endpoint, profiler.collector.metric.endpoint, profiler.collector.meta.endpoint, profiler.collector.endpoint, profiler.acm.endpoint, and profiler.acm.region.id in the configuration file. For information about the endpoints, see Endpoints.

Important

The ARMS agent includes virtual public cloud (VPC) connectivity checks. If VPC connectivity fails, it automatically switches to the public network. Therefore, we recommend that you use VPC endpoints instead.

Agents 2.x

ARMS Application Monitoring no longer supports agents for Java V2.x. Upgrade your agent to a version later than V2.x as soon as possible.