Provision the APM Java Agent

Connect to the host where the application server is installed and copy the APM Java Agent software file that you downloaded to any preferred location.
Ensure to login as the same user who installed the application server and that the application server user has read and write permissions to the directory to which the APM Java agent is downloaded or copied.
Ensure that you're logged in as the user who installed the application server and navigate to the directory where you downloaded or copied the APM Java agent software. Note that you must have read and write permissions to the directory that hosts the APM Java agent.
Review the following mandatory arguments that must be specified to provision an APM Java Agent.
- -service-name: The name of the service being monitored. This argument enables you to filter by service and view traces in the Trace Explorer user interface.
- -destination: The destination directory in which the APM Java Agent will be provisioned. Ideally, this should be a variable that you set as part of the prerequisite tasks to point to the application server destination directory. For example, $DOMAIN_HOME for the Oracle WebLogic Server Domain location. For microservices, the destination directory could be the standard home directory or any empty directory.
- -private-data-key: The agent installation key used by APM Java agents (private dataKey), which is generated when the APM domain is created.
- -data-upload-endpoint: The dataUploadEndpoint URL that is generated when the APM domain is created.
For more information on private dataKey and dataUploadEndpoint, see Obtain Data Upload Endpoint and Data Keys.

You can specify additional arguments when provisioning the APM Java agent. For information on these arguments and the scenarios in which they are useful, see Specify Proxy Arguments.
To view the help information for the provision-agent argument, run the following:
java -jar ./apm-java-agent-installer-<version>.jar provision-agent -help

For details, see Help Usage Information.
Provision the agent by specifying the mandatory arguments described in the previous step and running the following java command:
```
java -jar ./apm-java-agent-installer-<version>.jar provision-agent -service-name=<Name of the Service> -destination=<Destination_Directory> -private-data-key=<Agent installation key generated during APM domain creation> -data-upload-endpoint=<dataUploadEndpoint URL generated during APM domain creation>
```
Here's an example:
```
java -jar ./apm-java-agent-installer-1.1.jar provision-agent -service-name=apm_service -destination=$DOMAIN_HOME -private-data-key=IMWJ5UN2C6YOLQSUZ5Q7IGN3QACF4AZD -data-upload-endpoint=https://dataUploadEndpoint.com
```
On running the java command, if the APM Java agent is provisioned successfully:
- The Action [provision-agent] completed successfully message is displayed.
- The oracle-apm-agent directory is created in the destination directory. For example, $DOMAIN_HOME/oracle-apm-agent.
  The oracle-apm-agent directory should contain the following:
  - bin: Contains the starter of the aggregator.
  - bootstrap: Contains the agent startup .jar files that will be used by the -javaagent command to deploy the APM Java agent.
  - config: Contains the global configuration files, which can be edited. This directory contains:
    - The AgentConfig.properties file, which contains APM Java agent configuration arguments.
    - The ProbeConfig.acml file, which contains the configuration information related to probes.
  - install: Contains the <release-version>/config directory, which has the APM Java agent binaries and default configuration files. Note that the files in this directory must not be changed.
  - version: The version file that has information regarding the APM Java agent release version and activation date.
If the java command terminates and the APM Java agent is not provisioned successfully, then you can review the error details in the ApmAgentInstall.log file and the application server output log to correct the issue.

Help Usage Information

To view the help information and a list of options available when provisioning the agent, use the -help option.

java -jar ./apm-java-agent-installer-<version>.jar
                provision-agent
            -help

Example:

java -jar ./apm-java-agent-installer-<version>.jar provision-agent -help

Usage: 
apm-java-agent-installer-<version>.jar provision-agent [options ...] 

options:
   -service-name=<service name>
       (Required) Name of the service being monitored.

   -destination=<path>
       (Required) Path to create Agent home directory. The Agent software will be
       deployed to a 'oracle-apm-agent' sub-directory in the specified path.

   -private-data-key=<private_data_key>
       (Required) APM Agent private
      data key for Appserver Agents. This property
       is required for the APM Agent to connect to the Oracle APM Cloud, and it
       is specific to your APM Cloud Domain.

   -data-upload-endpoint=<https://host:port>
            (Required) Endpoint of Oracle APM Cloud. This property is required for the
            APM Agent to connect to the Oracle APM Cloud, and it is specific to your
            APM Cloud Domain.

   -enable-browser-agent-injection
       Enables the APM Agent to automatically inject the browser agent into HTML
       pages.  Make sure '-public-data-key' is also set, otherwise injection will
       not be enabled until one is provided.

   -public-data-key=<public_data_key>
       APM Agent public data key for Appserver Agents. This property is required
       for the injected browser agent to connect to the Oracle APM Cloud, and it
       is specific to your APM Cloud Domain.

   -activation-date=<YYYY-MM-DD>
       To stage newly installed Agent, and defer Agent running until Appserver
       restart on or later than specified date.

   -property=<key=value>
       Agent specific (i.e. starting with 'com.oracle.apm.agent') configuration
       properties. Multiple instances of -property can be specified.
       Alternatively, you can add these properties to the
       "AgentConfig.properties" file located in the Agent config directory
       (oracle-apm-agent/config/<version>).

   -overwrite
       Overwrite Agent deployment.

 Example:
   - Deploy Agent to user home directory      
      provision-agent -service-name=myservice -destination=/home/user
                      -private-data-key=12345 -data-upload-endpoint=https://<endpoint>
   - Deploy Agent to user home directory with additional properties
       provision-agent -service-name=myservice -destination=/home/user
                       -private-data-key=12345 -data-upload-endpoint=https://<endpoint>
                       -property=com.oracle.apm.agent.logging.level=WARNING

Oracle Cloud Infrastructure Documentation