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 theprovision-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 thejava
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.
- The
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 theApmAgentInstall.log
file and the application server output log to correct the issue. - The
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