Oracle Cloud Infrastructure Documentation

Management Agent

A Management Agent is installed on a host. A management agent can be installed directly on a host (for example, a host on your premises or on a third-party cloud platform) or indirectly as a plug-in for an oracle cloud agent (in the case of a Compute Instance). A management agent's plug-ins monitor and collect data from its host, which they then report to the Management Agent Cloud Service.

Management agents are used within JMS to collect data about Java Application, Java Runtimes and Installations. The agent reports the following data to the management agent cloud service:
  • The presence of a Java Runtime installation
  • The start of a Java application
  • The start of a Java Runtime
  • Data provided by Java Usage Tracker

A management agent may have one or more Tags.

See also, Managed Instance.

The management agent cloud service is an OCI service that manages management agents and their life cycle. For more details, see Management Agent Concepts.

Installing a Management Agent

This section describes the process to install a management agent for both on-premises and OCI instances.

Prerequisites:
  • You have read Perform Prerequisites for Deploying Management Agents and ensured that your host meets the prerequisites, including the requirement for JDK 8 (update 361, JDK 1.8.0_361, or later). The management agent isn't compatible with any other versions of the JDK.
  • To install a management agent on a host, you must meet the prerequisites described in Install Management Agents. For more information, see Configuring a Management Agent for Java Management Service.

    Caution:

    To update the Java runtime used by the management agents, you should follow the instructions detailed in the Using Java with Management Agent section to ensure the management agents continue working.
  • JMS recommends using JDK (instead of JRE) for setting up MACS.
  • JMS recommends setting up the management agent with a Java installation that is independent of system java. For example, while installing the management agent, set JAVA_HOME to JDK 8 that is not managed by the operating system's package management system.
  • You have completed the policy set up steps for the installation script to run successfully.
  • You have ensured that the clock on your host is synchronized with the OCI platform. You'll be unable to install a management agent if your host's clock is skewed more than five minutes from the OCI platform. For more information, see Maximum Allowed Client Clock Skew.

This section describes the steps to configure a management agent for both on-premises and OCI platforms:

Note

You can install a management agent in a container. For details see Tracking Java Usage in a Container.

Using Installation Script

JMS provides an installation script that you can use to set up management agents using a single command.

Note

Supported platforms include Oracle Linux, Ubuntu, and Windows (x86 and x64).
The script does the following functions:
  • Install the Management Agent software.
  • Configure the agent with a specific key for the fleet.
  • Install JMS plugins for Java runtime discovery and usage reporting and Lifecycle management operations.
  • Configure the usage tracker.

Downloading the Installation Script

Follow these instructions to download the installation script:

  1. Use either of the following options to start downloading the script:
    • Create a Fleet: When you click Create and follow the onscreen instructions, the Download software and installation script is available from the Install a management agent section of the Set up management agent panel.
    • Viewing a Fleet: When you select an existing fleet, click More actions and Set up management agent. The Download software and installation script window opens.
  2. In the Download software and installation script window, there are two tables:
    • Download management agent software: select the agent software relevant for your platform. The following information is presented along with package:
      • Download: the agent software package for each platform
      • Package type: type of packaging, for example, ZIP, RPM
      • Agent version: version number of the agent software
      • Size (MB): size of the package
      • SHA-256 Checksum: the hash code of the downloadable
    • Download installation script: select the installation script relevant for your platform. The following information is presented:
      • Download: downloadable installation script and software for each platform
      • File type: the type of the script, for example, pshell, shell
      • Size: size of the installation script
  3. Transfer the agent software and script to your machine that you want to register with the fleet.
The installation process installs an Oracle Cloud Agent on OCI platform or a Management Agent on an on-premises host, along with JMS plugins. The installation script may also install the following Oracle applications and third-party tools; if they are not already present on the host:

Oracle applications:

Third-party tools:

  • curl: a command-line tool and library used for transferring data with URLs.
  • jq: a command-line JSON processor used to map and transform structured data.
  • unzip: utility used to extract files from a zipped single file or similar file archive. This is used only on Ubuntu platform.
  • snap: a software packaging and deployment system used embed applications on Linux devices. This is used only on Ubuntu platform.
On-Premises Linux

This section describes the steps to run the downloaded script on an on-premise host running on Linux platform.

Steps

  1. Go to the folder where you saved the installation script and management agent software. Run the script using the following command: 
    $ sudo bash ./JMS_YourFleetName_linux.sh
    If installation is successful, you'll see a message similar to the following: 
    ...
Management Agent installation has been completed.
Management Agent plugin 'Java Management Service' installation has been completed.
Management Agent plugin 'Java Usage Tracking' installation has been completed.
Management Agent was successfully registered using key YourFleetName (ocid1.managementagentinstallkey.oc1.iad.<ocid hash>).Assigned JMS Fleet is YourFleetName (ocid1.jmsfleet.oc1.iad.<ocid hash>).
    Note

    By default, the installation script collects user names on the agents. The following parameters are set to:
    • user-name-collection = enabled
    • FIPS mode on Linux = disabled
    • Proxy = no proxy
    If you want to disable this feature, update the parameter --enable-user-name=false in the installation script.

    Run the --help command to view the description of options such as enabling or disabling user name, proxy settings, FIPS, and so on.

    The following are the optional parameters along with the description:
    
    --dist-path          Path to management agent installation file if it isn't in the same folder as the install script.
    -c, --cleanup        Uninstall plugins, delete configuration files or restore originals from backups and exit.
    -f, --force          Forcing management agent installation on the instance.
    --enable-user-name   Enable collecting user name for account which started java application.
                         Useful for meaningful application names for WebLogic and Tomcat servers.
                         Format is --enable-user-name=true|false (for example, --enable-user-name=false).
                         Modify /etc/oracle/java/usagetracker.properties and add or remove 'user.name' in 'additionalProperties'.
                         Default value is true.
    --enable-fips-mode   Enable FIPS mode for plugins in USGov realms.
                         Format is --enable-fips-mode=true|false (for example, --enable-fips-mode=false).
                         Modify /etc/environment and create a line with ENV_AGENT_PLUGIN_FIPS_APPROVED=true or false.
                         Default value is false.
    --proxy-host         Add proxy host to curl commands, add or replace line 'ProxyHost = VALUE' in install key before Management Agent setup.
                         Format is --proxy-host="VALUE" (for example, --proxy-host="100.0.0.10").
                         Default is no proxy.
    --proxy-port         Add proxy port to curl commands, add or replace line 'ProxyPort = VALUE' in install key before Management Agent setup.
                         Format is --proxy-port="VALUE" (for example, --proxy-port="8050").
    --proxy-user         Add proxy user to curl commands, add or replace line 'ProxyUser = VALUE' in install key before Management Agent setup.
                         Format is --proxy-user="VALUE" (for example, --proxy-user="opc").
    --proxy-password     Add proxy password to curl commands, add or replace line 'ProxyPassword = VALUE' in install key before Management Agent setup.
                         Format is --proxy-password="VALUE" (for example, --proxy-password="example").
    --proxy-realm        Add or replace line 'ProxyRealm = VALUE' in install key before Management  Agent setup.
                         Format is --proxy-realm="VALUE" (for example, --proxy-realm="OC1").
    -h, --help           Print usage message end exit.
  2. (Optional) To verify if the management agent is running, type: 
    $ sudo systemctl status mgmt_agent
    The results will show: 
    mgmt_agent.service - mgmt_agent
   Loaded: loaded (/etc/systemd/system/mgmt_agent.service; enabled; vendor preset: disabled)
   Active: active (running) since Wed 2022-08-24 07:05:38 GMT; 24s ago
  Process: 1772 ExecStart=/opt/oracle/mgmt_agent/agent_inst/bin/agentcore start sysd (code=exited, status=0/SUCCESS)
 Main PID: 1864 (wrapper)
   Memory: 414.6M
   CGroup: /system.slice/mgmt_agent.service
           ├─1864 /opt/oracle/mgmt_agent/agent_inst/bin/./wrapper /opt/oracle/mgmt_agent/agent_inst/bin/../config/wrapper.conf wrapper.syslog.ident=mgmt_agent wrapper.pidfile=/opt/oracle/mgmt_agent/agent_inst/bin/../log...
           └─2171 /usr/java/jdk1.8.0_301-amd64/bin/java -Dorg.tanukisoftware.wrapper.WrapperSimpleApp.maxStartMainWait=5 -Djava.security.egd=file:///dev/./urandom -XX:+HeapDumpOnOutOfMemoryError -Dpolyglot.engine.AllowE...

Aug 24 07:05:21 name-agent-stage systemd[1]: Starting mgmt_agent...
Aug 24 07:05:21 name-agent-stage agentcore[1772]: Removed stale pid file: /opt/oracle/mgmt_agent/agent_inst/bin/../log/mgmt_agent.pid
Aug 24 07:05:21 name-agent-stage agentcore[1772]: Starting mgmt_agent...
Aug 24 07:05:33 name-agent-stage agentcore[1772]: Waiting for mgmt_agent..............
Aug 24 07:05:34 name-agent-stage sudo[2752]: mgmt_agent : TTY=unknown ; PWD=/opt/oracle/mgmt_agent/agent_inst/bin ; USER=root ; ENV=ORACLE_CLOUD_AGENT_PLUGIN_COOKIE=<Cookie_ID> LOGDIR=/opt/or...
Aug 24 07:05:38 name-agent-stage systemd[1]: Started mgmt_agent.

    You can also view the console to verify if the management agent is running. See Management Agents Console Overview for more information.

    The log files are located in the /opt/oracle/mgmt_agent/plugins/jm/stateDir/log directory.

On-Premises Windows

This section describes the steps to run the downloaded script on an on-premise host running on Windows platform.

Note

On 32 bit instances, run the script with parameter --force-32bit-installer as described in the following steps.

Steps

  1. Open PowerShell as administrator.
    To ensure you have the correct permissions to run the script, type Set-ExecutionPolicy RemoteSigned and answer A.
  2. Go to the folder where you downloaded the script and management agent software. To run the script, enter: 
    .\JMS_YourFleetName_windows.ps1
    If installation is successful, you'll see a message similar to the following: 
    ...
Agent was successfully registered using key YourFleetName (ocid1.managementagentinstallkey.oc1.<ocid hash>) and assigned to fleet YourFleetName (ocid1.jmsfleet.oc1.<ocid hash>)
Management Agent with plugins installation has been completed.
    Note

    By default, the installation script collects user names on the agents. The following parameters are set to:
    • user-name-collection = enabled
    • Proxy = no proxy
    If you want to disable this feature, update the parameter --enable-user-name=false in the installation script.

    Run the --help command to view the description of options such as enabling or disabling user name, proxy settings, and so on.

    The following are the optional parameters along with the description:
    
    --force-32bit-installer Force 32 bit Management Agent installation. Use this parameter to monitor a 32 bit Windows instance.
    --dist-path             Path to management agent installation file if it isn't in the same folder as the install script. 
    -c, --cleanup           Uninstall plugins, delete configuration files or restore originals from backups and exit.
    -f, --force             Uninstall plugins, delete configuration files or restore originals from backups and continue installation.
    --enable-user-name      Enable collecting user name for account which started java application.
                            Useful for meaningful application names for WebLogic and Tomcat servers.
                            Format is --enable-user-name=true|false (for example, --enable-user-name=false).
                            Modify /etc/oracle/java/usagetracker.properties and add or remove 'user.name' in 'additionalProperties'.
                            Default value is true.
    --enable-fips-mode      Enable FIPS mode for plugins in USGov realms.
                            Format is --enable-fips-mode=true|false (for example, --enable-fips-mode=false).
                            Modify /etc/environment and create a line with ENV_AGENT_PLUGIN_FIPS_APPROVED=true or false.
                            Default value is false.
    --proxy-host            Add proxy host to curl commands, add or replace line 'ProxyHost = VALUE' in install key before Management Agent setup.
                            Format is --proxy-host="VALUE" (for example, --proxy-host="100.0.0.10").
                            Default is no proxy.
    --proxy-port            Add proxy port to curl commands, add or replace line 'ProxyPort = VALUE' in install key before Management Agent setup.
                            Format is --proxy-port="VALUE" (for example, --proxy-port="8050").
    --proxy-user            Add proxy user to curl commands, add or replace line 'ProxyUser = VALUE' in install key before Management Agent setup.
                            Format is --proxy-user="VALUE" (for example, --proxy-user="opc").
    --proxy-password        Add proxy password to curl commands, add or replace line 'ProxyPassword = VALUE' in install key before Management Agent setup.
                            Format is --proxy-password="VALUE" (for example, --proxy-password="example").
    --proxy-realm           Add or replace line 'ProxyRealm = VALUE' in install key before Management  Agent setup.
                            Format is --proxy-realm="VALUE" (for example, --proxy-realm="OC1").
    -h, --help              Print usage message end exit.
  3. (Optional) Type the following to verify if installation is successful: Get-Service -name mgmt_agent.
The log files are located in the /opt/oracle/mgmt_agent/plugins/jm/stateDir/log directory.
OCI Linux

This section describes the steps to run the downloaded script on an OCI instance running on Linux platform.

Note

You need to add the policy 
ALLOW dynamic-group JMS_DYNAMIC_GROUP TO MANAGE instances IN COMPARTMENT Fleet_Compartment
before you install a management agent on Linux for OCI. You can remove the policy after you've installed the management agent.

Steps

  1. Go to the folder where you saved the installation script and management agent software. Run the script using the following command: 
    $ sudo bash ./JMS_YourFleetName_linux.sh
    If installation is successful, you'll see a message similar to the following: 
    ...
Management Agent installation has been completed.
Management Agent plugin 'Java Management Service' installation has been completed.
Management Agent plugin 'Java Usage Tracking' installation has been completed.
Management Agent was successfully registered using key YourFleetName (ocid1.managementagentinstallkey.oc1.iad.<ocid hash>).Assigned JMS Fleet is YourFleetName (ocid1.jmsfleet.oc1.iad.<ocid hash>).
    Note

    By default, the installation script collects user names on the agents. The following parameters are set to:
    • user-name-collection = enabled
    • FIPS mode on Linux = disabled
    • Proxy = no proxy
    If you want to disable this feature, update the parameter --enable-user-name=false in the installation script.

    Run the --help command to view the description of options such as enabling or disabling user name, proxy settings, FIPS, and so on.

    The following are the optional parameters along with the description:
    
    --install-mgmt-agent Force Management Agent installation on instance. Use this parameter to monitor an OCI instance belonging to a different tenancy or region.  
    --dist-path          Path to management agent installation file if it isn't in the same folder as the install script.
    -c, --cleanup        Uninstall plugins, delete configuration files or restore originals from backups and exit.
    -f, --force          Uninstall plugins, delete configuration files or restore originals from backups and continue installation.
    --enable-user-name   Enable collecting user name for account which started java application.
                         Useful for meaningful application names for WebLogic and Tomcat servers.
                         Format is --enable-user-name=true|false (for example, --enable-user-name=false).
                         Modify /etc/oracle/java/usagetracker.properties and add or remove 'user.name' in 'additionalProperties'.
                         Default value is true.
    --enable-fips-mode   Enable FIPS mode for plugins in USGov realms.
                         Format is --enable-fips-mode=true|false (for example, --enable-fips-mode=false).
                         Modify /etc/environment and create a line with ENV_AGENT_PLUGIN_FIPS_APPROVED=true or false.
                         Default value is false.
    --proxy-host         Add proxy host to curl commands, add or replace line 'ProxyHost = VALUE' in install key before Management Agent setup.
                         Format is --proxy-host="VALUE" (for example, --proxy-host="100.0.0.10").
                         Default is no proxy.
    --proxy-port         Add proxy port to curl commands, add or replace line 'ProxyPort = VALUE' in install key before Management Agent setup.
                         Format is --proxy-port="VALUE" (for example, --proxy-port="8050").
    --proxy-user         Add proxy user to curl commands, add or replace line 'ProxyUser = VALUE' in install key before Management Agent setup.
                         Format is --proxy-user="VALUE" (for example, --proxy-user="opc").
    --proxy-password     Add proxy password to curl commands, add or replace line 'ProxyPassword = VALUE' in install key before Management Agent setup.
                         Format is --proxy-password="VALUE" (for example, --proxy-password="example").
    --proxy-realm        Add or replace line 'ProxyRealm = VALUE' in install key before Management  Agent setup.
                         Format is --proxy-realm="VALUE" (for example, --proxy-realm="OC1").
    -h, --help           Print usage message end exit.
  2. (Optional) To verify if the management agent is running, run the following script on your Linux machine: 
    curl -H "Authorization: Bearer Oracle" http://169.254.169.254/opc/v2/instance/
    where 169.254.169.254 is the IP address of the OCI Compute Instance Metadata Service.
    If installation is successful, you'll see a message similar to the following: 
    
{    
 "desiredState": "ENABLED",
 "name": "Management Agent"
},
{
 "desiredState": "ENABLED",
 "name": "Oracle Java Management Service"
}
The log files are located in the /var/log/oracle-cloud-agent/plugins/oci-jms/ directory.

Manual Installation

You can manually install a management agent on a non-OCI host.

This section describes the steps to manually install a management agent on:

On-Premises Linux

This section describes the steps to manually run the downloaded script on an on-premise host running on Linux platform.

Steps

Note

The installation instructions are the same for Oracle Linux and Ubuntu unless a difference between the two is noted.
  1. Download the management agent software, as described in Download the Agent Software. For Oracle Linux, download and install the contents of the rpm file. For Ubuntu, download and install the contents of the zip file.
  2. Create an agent install key, as described in Create an Agent Install Key.
  3. Download a response file template, as described Create a Response File. Edit the response file and add Service.plugin.jms.download=true at the bottom of the file. Save the file.
  4. For Lifecycle Management Operations, edit the response file and add Service.plugin.jm.download=true at the bottom and then save the file.
    Edit the /etc/sudoers file and add the following to the end of the file: 
    #To change ownership of the Java Management Service plugin to root 
mgmt_agent ALL=(ALL) NOPASSWD:/opt/oracle/mgmt_agent/agent_inst/bin/chown_recursive_ep.sh 
#To run the Java Management Service plugin under root user 
mgmt_agent ALL=(root) NOPASSWD: ALL
  5. Install and start the management agent, as described in Install Management Agents.
    Note

    Verify the output from the setup.sh (Oracle Linux) script or the installer.sh (Ubuntu) script. If the console output indicates that the plug-in has failed to deploy, then ensure that the clock on your host is synchronized with the clock on the OCI platform. For more information, see Maximum Allowed Client Clock Skew.
  6. Configure Java Usage Tracker using the JMS service plug-in setup script, as follows:

    Option 1. Generate usage tracker with standard functionality.

    Run the following commands.

    VERSION=$(sudo ls /opt/oracle/mgmt_agent/agent_inst/config/destinations/OCI/services/jms/)
sudo bash /opt/oracle/mgmt_agent/agent_inst/config/destinations/OCI/services/jms/"${VERSION}"/scripts/setup.sh --force
    This script creates the file /etc/oracle/java/usagetracker.properties with appropriate permissions. By default, the file contains the following lines:
    com.oracle.usagetracker.logToFile = /var/log/java/usagetracker.log
com.oracle.usagetracker.additionalProperties = java.runtime.name
    If successful, you should see a message in the console similar to
    /var/log/java created
/etc/oracle/java/usagetracker.properties created
    If successful, you should see a message in the console similar to: 
    /var/log/java created
/etc/oracle/java/usagetracker.properties created

    Option 2. Generate usage tracker with additional functionality to collect the user.name property for better identification of applications running in Application Servers like Weblogic.

    Run the following commands:
    VERSION=$(sudo ls /opt/oracle/mgmt_agent/agent_inst/config/destinations/OCI/services/jms/)
sudo bash /opt/oracle/mgmt_agent/agent_inst/config/destinations/OCI/services/jms/"${VERSION}"/scripts/setup.sh --force --enable-user-name
    This script creates the file /etc/oracle/java/usagetracker.properties with appropriate permissions. This script creates the file with appropriate permissions. By default, the file contains the following lines:
    com.oracle.usagetracker.logToFile = /var/log/java/usagetracker.log
com.oracle.usagetracker.additionalProperties = java.runtime.name,user.name
The log files are located in the /opt/oracle/mgmt_agent/plugins/jm/stateDir/log/ directory.
On-Premises Windows

This section describes the steps to manually run the downloaded script on an on-premise host running on Windows platform

Steps

Note

The installation instructions are the same for Linux and Ubuntu unless a difference between the two is noted.
  1. Download the management agent software, as described in Download the Agent Software. For Linux, download and install the contents of the rpm file. For Ubuntu, download and install the contents of the zip file.
  2. Create an agent install key, as described in Create an Agent Install Key.
  3. Download a response file template, as described Create a Response File. Edit the response file and add Service.plugin.jms.download=true at the bottom of the file. Save the file.
  4. For Lifecycle Management Operations, edit the response file and add Service.plugin.jm.download=true at the bottom and then save the file.
  5. Install and start the management agent, as described in Install Management Agents.
    Note

    To uninstall a management agent, see Uninstalling a Management Agent.
    Note

    To modify a management agent's tags, see Modifying a Management Agent's Tags.
  6. Option 1. Generate usage tracker with standard functionality. Open a command prompt as an administrator, and run the following commands. 
    dir /b C:\Oracle\mgmt_agent\agent_inst\config\destinations\OCI\services\jms >%TEMP%\version.txt
set /p VERSION=<%TEMP%\version.txt
powershell -ep Bypass C:\Oracle\mgmt_agent\agent_inst\config\destinations\OCI\services\jms\%VERSION%\scripts\setup.ps1 --force
    • This script creates:
      • usagetracker.properties in C:\Program Files\Java\conf
      • usagetracker.log in C:\ProgramData\Oracle\Java
      By default, the file usagetracker.properties contains the following lines:
      com.oracle.usagetracker.logToFile = C:\ProgramData\Oracle\Java\usagetracker.log
com.oracle.usagetracker.additionalProperties = java.runtime.name

      Option 2. Generate usage tracker with additional functionality to collect the user.name property for better identification of applications running in Application Servers like Weblogic.

      Open command prompt as administrator, and run the following commands:
      dir /b C:\Oracle\mgmt_agent\agent_inst\config\destinations\OCI\services\jms >%TEMP%\version.txt
set /p VERSION=<%TEMP%\version.txt
powershell -ep Bypass C:\Oracle\mgmt_agent\agent_inst\config\destinations\OCI\services\jms\%VERSION%\scripts\setup.ps1 --force --enable-user-name
      This script creates:
      • usagetracker.properties in C:\Program Files\Java\conf
      • usagetracker.log in C:\ProgramData\Oracle\Java
      By default, the usagetracker.properties file contains the following lines:
      com.oracle.usagetracker.logToFile = C:\ProgramData\Oracle\Java\usagetracker.log
com.oracle.usagetracker.additionalProperties = java.runtime.name,user.name

    For more information, see Enabling and Configuring Java Usage Tracker.

  7. Verify the installation, as described in Verify the Management Agent Installation.
  8. Optional. Specify how frequently the management agent will report data to JMS and which file system paths on the host will be scanned to discover Java Runtime installations. See Modifying a Management Agent Settings.
The log files are located in the /opt/oracle/mgmt_agent/plugins/jm/stateDir/log/ directory.
OCI Linux

Follow these steps if your host is a Compute Instance on Oracle Cloud Infrastructure (OCI).

Before you begin, review the prerequisites and the overview of the steps.

Note

This functionality isn't available for Windows instances running on Oracle Cloud Infrastructure. See the System Requirements for platforms currently supported by JMS.
Prerequisites: You've read:

Overview

  1. Enable the Management Agent plugin.
  2. Deploy the JMS service plug-in Java Usage Tracker.
  3. Enable Lifecycle Management Operations.
  4. Associate the management agent with your fleet.
  5. Configure Java Usage Tracker.
  6. Verify the installation of the management agent on your host.
  7. (Optional). Customize which file system paths on your host will be scanned to discover installations of Java Runtimes, and how frequently the agent will report data to JMS.

Steps

  1. Enable the Management Agent plugin on your compute instance's Oracle Cloud Agent, as described in Enable Management Agents Using the Console.
  2. Deploy the service plug-in named Java Usage Tracking, as described in Deploy a Plug-in Using the Agents Page.
  3. For Lifecycle Management Operations, enable the Oracle Java Management Service plugin on your compute instance's Oracle Cloud Agent.
    1. Open the navigation menu and click Compute > Instances.
    2. Click the instance that you're interested in.
    3. Click the Oracle Cloud Agent tab.

      The list of plugins is displayed.

    4. Toggle the Enabled switch for the Oracle Java Management Service plugin.
  4. To associate the management agent with your fleet, add a tag to the management agent with the following details:
    • Tag namespace: jms
    • Tag key: fleet_ocid
    • Tag value: the OCID of the existing fleet
    For more information, see Modifying a Management Agent's Tags.
  5. Configure Java Usage Tracker using the JMS service plug-in setup script, as follows:

    • Option 1: Generate usage tracker with standard functionality.

      Run the following commands.

      VERSION=$(sudo ls /var/lib/oracle-cloud-agent/plugins/oci-managementagent/polaris/agent_inst/config/destinations/OCI/services/jms)
sudo bash /var/lib/oracle-cloud-agent/plugins/oci-managementagent/polaris/agent_inst/config/destinations/OCI/services/jms/${VERSION}/scripts/setup.sh --force
      This script creates the file /etc/oracle/java/usagetracker.properties with appropriate permissions. By default, the file contains the following lines:
      com.oracle.usagetracker.logToFile = /var/log/java/usagetracker.log
com.oracle.usagetracker.additionalProperties = java.runtime.name
      If successful, you should see a message in the console similar to
      /var/log/java created
/etc/oracle/java/usagetracker.properties created

    • Option 2: Generate usage tracker with additional functionality to collect the user.name property for better identification of applications running in Application Servers like Weblogic.

      Run the following commands:
      VERSION=$(sudo ls /var/lib/oracle-cloud-agent/plugins/oci-managementagent/polaris/agent_inst/config/destinations/OCI/services/jms)
sudo bash /var/lib/oracle-cloud-agent/plugins/oci-managementagent/polaris/agent_inst/config/destinations/OCI/services/jms/${VERSION}/scripts/setup.sh --force --enable-user-name
      If successful, you should see a message in the console similar to: 
      /var/log/java created
/etc/oracle/java/usagetracker.properties created

    For more information, see Enabling and Configuring Java Usage Tracker.

  6. Verify the installation, as described in Verify Management Agents on Compute Instances.
  7. Optional. Specify how frequently the management agent will report data to JMS and which file system paths on the host will be scanned to discover Java Runtime installations. See Modifying a Management Agent Settings.
The log files are located in the /var/log/oracle-cloud-agent/plugins/oci-jms/ directory.

Upgrading a Management Agent

Oracle recommends using the latest version of the Management Agent software. Upgrading gives access to the latest functionality. For information about getting the latest version, see Upgrading Management Agents.

Oracle recommends the Automatic Upgrade method. By default Auto Upgrade is set to Disable by the Management Agent Cloud Service. Follow the steps in Enable Auto Update to enable automatic upgrade of Management Agents.

Modifying Management Agents' Settings

Note

This feature requires version 210918.1427 or later of the management agent software installed on all of your hosts. You can download the latest version of the software by using the contextual menu of a fleet in the Fleet Dashboard or from a fleet's Fleet Properties Tab. See also Installing a Management Agent.
You can modify the following management agents' settings for a fleet:
  • Which file system paths the fleet's management agents scan on their hosts to discover Java Runtime installations
  • How frequently the fleet's management agents report usage and Java Runtime installations to JMS

Prerequisites: You have selected a fleet from the fleet dashboard.

  1. Click Modify Agent Settings. You are prompted to modify the general settings and the file system paths that the management agents scan. Every management agent in a fleet uses these settings.
  2. Modify the General settings:
    1. Java runtime usage in minutes: specify the frequency at which the management agent must report Java usage to JMS. The values must be between 5 and 90 minutes. The default value is 5 minutes.
    2. Agent polling interval: specify the frequency at which the management agent must check the work requests. For example, if the value specified is 10 minutes, the agent checks the work requests every 10 minutes and executes them. The values must be between 10 minutes and 12 hours. The default value is 10 minutes.
    3. Work request retention period: specify the time period for JMS to store the work requests. The values must be between 7 to 30 days. The default value is 2 weeks.
  3. Modify the File scanning settings:
    1. Java runtime discovery: specify frequency at which the management agents should scan their hosts for Java runtime installations. The values must be between 3 to 24 hours. The default value is 24 hours.
      To stop management agents scanning for Java runtime installations, deselect Enable Java runtime discovery.
    2. Modify the file system paths that the management agents should scan on their Linux and Windows hosts to find Java runtime installations.
      Reasons for customizing the directories include:
      • Customization: include your own Java runtime installation, such as /etc/java.
      • Performance: exclude paths to reduce the time taken by the management agent to scan, lower processor load, and reduce memory usage.
      • Privacy: exclude paths to omit corresponding directories whose contents you want to remain private.
    3. In the Exclude Path(s) section for each operating system, provide a list of file system paths to be excluded from the scan. Subdirectories are also excluded by default.
      To exclude more paths, click + another path, and then provide the details of the additional path. To remove a path, click X to its right.
    4. In the Include Path(s) section for each operating system, provide a list of file system paths to be scanned. Subdirectories are also included by default.
      The management agent includes the following paths by default:
      • Linux
        • /usr/java
        • /usr/lib/jvm
        • /usr/lib64/graalvm
        • /opt
      • Windows
        • c:\\Program Files\\Java

      To include more paths, click + another path, and then provide the details of the additional path. To remove a path, click X to its right.

      Note

      File scanning looks for Java installations in the physical directories. Java installation symlinks (symbolic or soft link) will not be detected by file scanning.
    For a description of the syntax to describe file systems paths, see Include/Exclude Path Patterns.
  4. Click Save changes.
    Note

    Changes to the management agents' settings may take some time to be effective.

Include/Exclude Path Patterns

The management agent uses the following patterns to describe the include and exclude paths.
Pattern Description
** This pattern specifies all volumes. (This is equivalent to / on Linux.)
/* This pattern matches one directory with any name. (For example, on Linux the pattern /usr/*/java matches /usr/lib32/java and /usr/lib64/java.)
/** This pattern matches one or more directories with any name. (For example, on Linux the pattern /usr/**/java matches /usr/lib32/java and /usr/lib/jvm/java.)

${ENV_VAR}

${ENV_VAR:-default value}

System or environment variable. If the variable is null or not set, the value of the optional subsequent variable expansion is used.

For example, if you specify ${HOME:-/home/opc}, the management agents will use the $HOME environment variable on their hosts. If the $HOME environment variable is null or not set on a host, then /home/opc will be used on that host instead.

(This syntax simulates that provided by Shell Parameter Expansion.)

Note

Characters including ?, [, ], {, and } may exist in the path, and are not expanded when matching paths. For example, the include path pattern /[a-c]/jav?/*c assumes there is a file system path with exactly this name.

Modifying a Management Agent's Tags

You can modify a management agent's tags after you have installed it. The reasons for modifying an agent's tags include, but are not restricted to
  • You made a mistake when installing the agent and want to correct its tag(s)
  • You created a fleet and want it to contain the agent's corresponding managed instance
Note

If you modify the agents tags so that the agent moves to a new fleet, the historic data of the managed instance associated with the agent will not move to the new fleet.

For example, if the tag of an agent associated with a managed instance was changed from fleet A's OCID to fleet B's OCID on January 1, 2021, then fleet A will contain the managed instance's data until January 1, 2021 and fleet B will contain the management instance's data from January 1, 2021.

For more information, see Resource Tags.

  1. Sign in to the Oracle Cloud Console as an administrator using the credentials provided by Oracle, as described in Signing into the Console.
    For more information, see Using the Console.
  2. Find the agent you want to modify.
    1. In the Oracle Cloud Console, open the navigation menu and click Observability & Management. Under Management Agent, click Agents.
    2. Select the compartment containing the agent from the Compartment drop-down list.
    3. Click the name of the agent in the table.
  3. To add a tag key-value pair to the agent, click Add Tags. For example, to associate the agent with an existing fleet, add a tag as follows:
    • Tag namespace: jms
    • Tag key: fleet_ocid
    • Tag value: the OCID of the existing fleet
    Note

    It's not possible to provide multiple values for the fleet_ocid key. This ensures that a managed instance can't be contained by more than one fleet.
  4. To edit or remove an existing tag, select the Tags tab and click Edit Pencil Icon next to the tag you want to modify. For example, to move the agent to another fleet, replace the existing value of the tag whose key is fleet_ocid (in the jms namespace) with the OCID of the other fleet.
    Note

    You can only edit the value of the tag. To modify a tag's key, remove the tag, and add a new tag as described earlier.

Management Gateway

The Management Gateway provides a single point of communication between the Management Agents (or any other customer-side products) and the Oracle Cloud Infrastructure.

If you want your agents to communicate through a single point with the Oracle Cloud Infrastructure, follow the instructions in Management Gateway.

Uninstalling a Management Agent

If you no longer want to use JMS, or if you have encountered the error message "Please uninstall the agent and remove the service file before installing the new agent!", remove the agent by following the procedure described in Remove Management Agents.