Connecting Agents

Prerequisites

• The network between your host and APM is normal. You can run the curl -kv command to check the network. For example, if you select region CN-Hong Kong and set Access Mode to Enhanced Agent, log in to the host where the application is deployed and run the curl -kv 100.125.6.106:41333 command to check the network connectivity. For details about access addresses in other regions, see Agent Access Addresses.
• Java supports enhanced Agents.

Procedure

1. Log in to the APM console.
2. Click on the left and choose Application > Application Performance Management.
3. In the navigation pane, choose Application Monitoring > Applications.
4. On the displayed page, click Connect Application.
   Figure 1 Connecting an application
   

5. Select a region and application. Click Create Application. In the dialog box that is displayed, create an application by referring to Creating an Application.
   Figure 2 Basic information
   

6. Select Enhanced Agent for Access Mode.
7. Select Java for Backend Language.
   Figure 3 Access mode
   

8. Use a remote login tool, such as PuTTY, to log in to the Linux host where the Agent is to be installed and run related commands as the user with the root or service permissions.
9. Select an access mode based on the application type and access data by following the instructions.
   • Enhanced Agent
     • VM Access
       1. Choose System Management > Access Keys and obtain the AK and SK required by the Java Agent. For details about how to obtain the access key, see Access Keys.
       2. Use a remote login tool, such as PuTTY, to log in to the Linux host where the Agent is to be installed and run related commands as the user with the root or service permissions. Use the account who starts the application to run the installation command.
       3. Download and install JavaAgent:

          curl -k https://javaagent.obs.****.com/apm_agent_install2.sh -o apm_agent_install.sh && bash apm_agent_install.sh -ak {APM_AK} -sk {APM_SK} -masteraddress https://**.**.**.**:**** -obsaddress https://javaagent.obs..****.com -version latest; history -cw; history -r

          Table 1 VM access parameters

          Parameter	Description	Mandatory
          APM_AK APM_SK	AK and SK for installing JavaAgent. To obtain APM_AK and APM_SK, see Access Keys. When you copy the command to install JavaAgent, delete {} when setting APM_AK and APM_SK. Example: curl -k https://javaagent.***/apm_agent_install2.sh -o apm_agent_install.sh && bash apm_agent_install.sh -ak * -sk * -masteraddress https://**** -obsaddress https://javaagent.***.com -version latest; history -cw; history -r	Yes
          masteraddress	Access address. For details, see Agent Access Addresses.	Yes
          version	Agent version. The latest Agent provided by APM supports multiple JDK environments.	Yes

       4. Add the startup command and restart the application. It takes about 1 minute to install the Agent. After the installation is complete, add JVM parameters to the startup script of your application and then restart it. Startup command format:

          java -javaagent:Agent installation path/apm-javaagent/apm-javaagent.jar=appName=Component name,env=Environment name,envTag=Environment tag,business=Application alias,subBusiness=Sub-application name -jar User application.jar

          Example of a startup command:

          java -javaagent:/root/my-dir/apm-javaagent/apm-javaagent.jar=appName=my-service,env=dev -jar test-2.0.0-SNAPSHOT.jar

          Table 2 Startup command parameters

          Parameter	Description	Mandatory
          Agent Installation Path	Path for installing the Agent.	Yes
          Component Name	Component name, which must start with a letter. Each component name must be unique under an application. A component can contain multiple environments. If there are duplicate names, use instanceName to distinguish them.	Yes
          Environment Name	Name of an environment where an application is deployed. A program can be deployed in different environments (such as the test or live network environment). Each environment is deployed in one region and has a unique region attribute. If this parameter is blank, the default environment will be used.	No
          Environment Labels	Environment tag for filtering environments. Different environments may have the same tag. This parameter can be left blank.	No
          App Name	Name of an application (a global concept). Create an application before specifying this parameter. If this parameter is left blank, the automatically created application will be used.	No
          Sub-application Name	Sub-application (a global concept). It is a subfolder under the application. If this parameter is left blank, resources will be mounted to the root application. Up to three layers of sub-applications are supported. For example, for a/b/c, each represents one layer.	No
          User Application	Name of a user application.	Yes

     • CCE Access
       1. Prerequisites
          • You are advised to install self-developed Agents for the Java applications deployed in CCE containers.
          • A containerized application has been deployed using CCE.
       2. Choose System Management > Access Keys and obtain the AK and SK required by the Java Agent. For details about how to obtain the access key, see Access Keys.
       3. APM only supports Java applications deployed on CCE. Table 3 describes the parameters.

          Table 3 Parameters for configuring performance management

          Parameter	Description
          Probe	Select a target probe. Options: Disable and APM 2.0.
          Probe Version	Version of the probe. You are advised to select a probe version based on the CPU architecture of the node where the workload is located. The latest Agent provided by APM supports multiple JDK environments.
          Probe Upgrade Policy	Policy for the probe upgrade. The default value is Auto upgrade upon restart. Automatic upgrade upon restart: The system downloads the probe image each time the pod is restarted. Manual upgrade: If a local image is available, it will be used. If no local image is available, the system downloads the probe image.
          APM Environment	Enter an APM environment name. This parameter is optional.
          APM App	Select an existing APM application.
          Sub-app	Enter an APM sub-application. This parameter is optional.
          Access Key	The system automatically obtains the APM key. For details, see Access Keys.

       4. Log in to the CCE console and connect the Java application to APM through the Pinpoint probe. For details about CCE access, see Connecting JavaAgents for Applications Deployed in CCE Containers.
   • OpenTelemetry
     Ingest data. The following lists the parameters and steps.

     Table 4 Parameter description

     Parameter	Description	Mandatory
     Agent Installation Path	OpenTelemetry Agent path, that is, the path for storing the Agent after it is downloaded.	Yes
     Application	Display name of the application. An application (global concept) is a logical unit, such as an independent functional module. You can view the same application information in all regions.	Yes
     Component	Component name, which must start with a letter. Each component name must be unique under an application. A component can contain multiple environments. If there are duplicate names, use instanceName to distinguish them.	Yes
     Environment	Name of an environment where an application is deployed. A program can be deployed in different environments (such as the test or live network environment). Each environment is deployed in one region and has a unique region attribute. If this parameter is blank, the default environment will be used.	No
     Sub-application	Sub-application (a global concept). It is a subfolder under the application. If this parameter is left blank, resources will be mounted to the root application. Up to three layers of sub-applications are supported. For example, for a/b/c, each represents one layer.	No
     User Application	Name of a user application.	Yes

     1. Download the OpenTelemetry Java Agent. Go to the OpenTelemetry website to download Agent 1.x (recommended). Then save the Agent file to a directory that the Java process has the access permission, for example, /root/my-dir.
     2. Use a remote login tool, such as PuTTY, to log in to the Linux host where the Agent is to be installed and run related commands as the user with the root or service permissions. Use the account who starts the application to run the installation command.
     3. Configure the startup command and restart the application. Startup command format:

        java -javaagent:opentelemetry-agent-path -Dotel.exporter.otlp.traces.endpoint=http://**.**.**.**:*** -Dotel.exporter.otlp.headers=Authentication=****** -Dotel.service.name=Application name.Component name.Environment name -Dotel.metrics.exporter=none -jar User application.jar

        Example of a startup command:

        java -javaagent:/root/my-dir/opentelemetry-javaagent.jar -Dotel.exporter.otlp.traces.endpoint=http://**.**.**.**:*** -Dotel.exporter.otlp.headers=Authentication=****** -Dotel.service.name=default.my-service.dev -Dotel.metrics.exporter=none -jar myApp.jar

   • SkyWalking
     Ingest data. The following lists the parameters and steps.

     Table 5 Parameter description

     Parameter	Description	Mandatory
     Agent Installation Path	SkyWalking Agent path, that is, the path for storing the Agent after it is downloaded.	Yes
     Application	Display name of the application. An application (global concept) is a logical unit, such as an independent functional module. You can view the same application information in all regions.	Yes
     Component	Component name, which must start with a letter. Each component name must be unique under an application. A component can contain multiple environments. If there are duplicate names, use instanceName to distinguish them.	Yes
     Environment	Name of an environment where an application is deployed. A program can be deployed in different environments (such as the test or live network environment). Each environment is deployed in one region and has a unique region attribute. If this parameter is blank, the default environment will be used.	No
     Sub-application	Sub-application (a global concept). It is a subfolder under the application. If this parameter is left blank, resources will be mounted to the root application. Up to three layers of sub-applications are supported. For example, for a/b/c, each represents one layer.	No
     User Application	Name of a user application.	Yes

     1. Download the SkyWalking Agent. Go to the SkyWalking website to download Java Agent 8.9.0 or later (recommended). Decompress the package and save the Agent file to a directory that the Java process can access. To enable a plug-in, place the new plug-in to the /plugins directory during startup. To disable the plug-in, delete the plug-in from the directory. By default, log files are output to the /logs directory.
     2. Add the startup command and restart the application.
        1. There are two ways to configure the Agent:
           • Configure the application startup command.

             java -javaagent:skywalking-agent-path -Dskywalking.collector.backend_service=100.79.29.107:11800 -Dskywalking.agent.authentication=***** -Dskywalking.agent.service_name=Application name.Component name.Environment name -jar <User Application>.jar

           • Configure the agent/config/agent.config file.

             collector.backend_service=100.79.29.107:11800
             agent.authentication=******
             agent.service_name=Application name.Component name.Environment name

        2. Configure the JavaAgent path and restart the application.

           java -javaagent:skywalking-agent-path -jar yourApp.jar 

           Note: If you configure the Agent in both ways, only the configuration in the startup command takes effect.

           Example of a startup command:

           java -javaagent:/root/my-dir/opentelemetry-javaagent.jar -Dskywalking.collector.backend_service=100.79.29.107:11800 -Dskywalking.agent.authentication=***** -Dskywalking.agent.service_name=<default.my-service.dev> -jar myApp.jar

Dynamically Configuring master.address and AK/SK

APM supports dynamic configuration of the master.address and AK/SK.

You can set the APM_MASTER_ADDRESS, APM_ACCESS_KEY (apm-ak), and APM_SECRET_KEY (apm-sk) environment variables. For details about how to obtain the AK/SK, see Connecting Agents Through a Proxy. For details about how to obtain the master.address, see Agent Access Addresses.

• If you set the AK/SK and master.address in both the JavaAgent configuration file and environment variables, your environment variable settings will take precedence.
• Agents later than 2.3.19 support dynamic configuration of master.address and AK/SK.