Getting Started with Java Management Service

Java Management Service (JMS) is a native Oracle Cloud Infrastructure (OCI) service that monitors Java deployments on OCI instances and instances running in customer data centers. It enables you to observe and manage the use of Java in your enterprise.

This chapter includes the following topics:

About Java Management Service

Java Management Service (JMS) is a reporting and management infrastructure integrated with Oracle Cloud Infrastructure Platform services to observe and manage your use of Java SE (on-premise or in the Cloud).

As a customer, you can:
  • Use insights from JMS to optimize your workloads across your enterprise (desktop, server, cloud); and
  • Protect your Java SE investments by identifying outdated Java installations, unauthorized applications, and Java runtime and application mismatches. For example, your application is using JDK 11, but you learn it's using JDK 8.
JMS helps systems administrators to answer questions such as:
  • Which vendors are providing the Java installations in my environment?
  • Are my applications using their intended Java installations?
  • Are unauthorized applications running?
  • How many outdated Java installations do I have?
As the stewards of Java, Oracle can provide answers to these questions. Oracle uniquely leverages its expertise to gain critical insights into Java application behavior, compliance, and performance.
Note

JMS is a region specific service and regions are independent. See Regions and Domain Availability.

System Requirements

Java Management Service currently supports the following operating systems:
Operating System Version - all 64 bit
Windows 2019, 2016, 2012 R2, 10
Note

The OCA plugin isn’t available for Windows at this time.
Oracle Linux 6, 7, 8
Red Hat Enterprise Linux 6, 7, 8
CentOS 6, 7
SUSE Linux Enterprise Server 12, 15
Ubuntu 20.04.3 LTS
Java Management Service relies on the Java Usage Tracker to report Java usage. The Java Usage Tracker tracks how Oracle Java Runtime Environments are being used in your systems and captures the JRE version, vendor, the application being run, and other details. Additionally, JMS also periodically performs a file scan to detect Java runtimes that are not captured by the Java Usage Tracker because they aren't being used or don't have the Java Usage Tracker capabilities. OpenJDK binaries will be detected by JMS through file scanning but won't have usage associated because they don't have Java Usage Tracker capabilities. Java Usage Tracker is available for all releases of Java 7, and later, and also for the following older Java releases:
  • 6u25 and later updates

  • 5.0u33 and later updates

  • 1.4.2_35 and later updates

For 1.8.0_60 and later versions, the usage tracker properties file can be in a central location. As part of the agent installation, JMS currently only generates the usage tracker properties file in the central location. Although versions earlier than 1.8.0_60 have usage tracker, JMS won't capture the associated usage information, since it doesn't write usage to the central location. Usage information for these versions will be missing (even though they have usage tracker capabilities) because these runtimes need usage tracker in the JRE installations folder and not in the central location. If you want usage records, ask your System Administrator to manually place the usage tracker properties file in the JRE installations folder for these versions.

To install a management agent on a host, you must meet the prerequisites described in Install Management Agents. In particular, your host must meet the Generic Prerequisites for Deploying Management Agents, including the requirement for JDK 8 (update 281, JDK 1.8.0_281, or higher). The management agent is not compatible with any other versions of the JDK. For more information, see Configuring a Management Agent for Java Management Service.

Note

To update the Java Runtime used by the Management Agents, you should follow the instructions in the Using Java with Management Agent section to ensure the Management Agents continue working.

Key Concepts and Terminology

The following concepts and terminology will help you get started with Java Management Service. The Oracle Cloud Infrastructure documentation provides related terminology.

Application

An application refers to a Java program.

The name of an application is derived from the fully-qualified name of its main class. An application can run on multiple Java Runtimes.

Compartment

A compartment enables you to organize and control access to your cloud resources, such as a Fleet or a Management Agent. A compartment should be thought of as a logical group and not as a physical container.

For more details, see OCI Key Concepts and Terminology.

Compute Instance

A Compute Instance is a host that is provisioned and managed by Oracle Cloud Infrastructure. For more information, see Overview of the Compute Service.

Fleet

A fleet is the primary collection with which you interact when using JMS. It contains Managed Instances that share rules and policies.

Installation

An installation refers to an installation of a Java Runtime on one or more hosts.

An installation is identified by four attributes:
  • File system path, such as /usr/lib/jvm/jdk13.0.1/
  • Vendor, such as Oracle Corporation
  • Operating System version, such as Linux 5.4.17-2011.7.4.el7uek.x86_64
  • Architecture, such as x64

Java Runtime

A Java Runtime Environment (JRE, or Java Runtime) is a Java Virtual Machine (JVM), Java platform core classes, and supporting Java platform libraries. It's released as a certain version of a distribution or included with a vendor's product release. A Java Runtime can be installed to run a single Application or to be used by many applications.

A Java Runtime is identified by three attributes:
  • Vendor, such as Oracle Corporation
  • Name of distribution to which it belongs, such as OpenJDK Runtime Environment
  • Version, such as 1.8.0_282

When displayed by JMS, a Java Runtime from Oracle indicates if it requires an update.

Log Configuration

JMS uses the OCI Logging service to store inventory and operation logs. Inventory logs are Custom Logs that store the Java Runtime inventory and usage related information reported from the hosts by the Management Agent. Operation logs are Custom Logs for storing the logs related to operations carried out through JMS. Each fleet has its own unique inventory and operation log. Logs are placed under a Log Group. By relying on logs and JMS reports, you can do additional analytics using Logging Analytics.

Managed Instance

A Management Agent that has been installed on a host is known as a Managed Instance. A host can be any computer running in your enterprise. In most cases, the host is a computer on your premises, but it can be on OCI or on any other cloud platform. A managed instance has a unique identity that's used by JMS to distinguish it from other managed instances.

A managed instance must be contained by only one Fleet.

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 Applications, 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.

Oracle Cloud Agent

An Oracle Cloud Agent is a lightweight process that manages plug-ins running on a compute instance. Its plug-ins collect performance metrics, install OS updates, and perform other instance management tasks. An example plug-in is a Management Agent.

For more information, see Managing Plugins with Oracle Cloud Agent.

Tag

A tag is a key-value pair that you use to add metadata to your OCI resources.

JMS uses a tag in the namespace jms with the key fleet_ocid to identify the contents of a fleet. The managed instances contained in a fleet are identified by the tag value corresponding to the OCID of the fleet. (For more information, see Creating a Fleet.)

For a more detailed description of tags, see Tagging Overview.

Tenancy

When you sign up for Oracle Cloud Infrastructure, Oracle creates a tenancy for you or your enterprise. This is a secure and isolated partition within Oracle Cloud Infrastructure where you can create, organize, and administer your cloud resources.

Work Request

A Work Request allow you to monitor long-running operations such as Java Runtime Lifecycle Management operations. When you launch such an operation, JMS creates a work request. A work request is an activity log that enables you to track each step in the operation's progress. Work requests are helpful in the following scenarios:
  • If an operation fails, a Work Request can help you determine which step of the process had an error.
  • Some operations affect multiple resources. For example, a delete Java Runtime operation could affect multiple Java Runtimes, Java Runtime installation paths and Managed Instances. A work request provides a list of the resources that an operation affects.

Checking Required OCI Resources

To enable you to swiftly get going with JMS, the Onboarding Wizard creates and checks required policies, tags, and other configurations, while the Log Configuration Wizard covers missing log configurations. This section describes how to use the Onboarding Wizard and Log Configuration Wizard.

Note

The Onboarding Wizard creates the OCI resources similar to those described in Setting Up Oracle Cloud Infrastructure for Java Management Service.
Prerequisites:
  • You've signed up for an account with Oracle Cloud Infrastructure and have received your sign-in credentials.
  • You've logged in to the Oracle Cloud Infrastructure Console and selected Java Management from the navigation menu.

Using the Onboarding Wizard

  1. Click Inspect Prerequisites.
  2. Click Allow to automate the creation of prerequisite OCI resources, such as permissions and polices.

    You'll be presented with an error message if JMS isn't successful and JMS will roll back any changes.

  3. Optional steps:
    1. Click Details to view the OCI resources that JMS will create on your behalf.
    2. Expand Policy Details to view a detailed description of the OCI resources that JMS will attempt to create on your behalf.
    3. Click Set up JMS to automate the creation of the OCI resources described.

      You'll be presented with a list of errors and their causes if JMS doesn't successfully create the policies on your behalf. JMS will roll back any changes.

Using the Log Configuration Wizard

  1. The Log Configuration wizard is presented by JMS if at least one fleet in a compartment has missing log configurations. Click Enable log configuration to automate log configuration for all fleets with missing log configurations.

    You'll be presented with an error message if JMS isn't successful and JMS will roll back any changes.

  2. Optional steps:
    1. Click View Details to view the fleets that have missing log configuration.
    2. Use the checkbox to define the scope of the operation.
    3. Click Enable log configuration to automate the creation of log configuration for all selected fleets. You'll be presented with a list of errors and their causes if JMS isn't successful. JMS will roll back any changes.

Setting Up Oracle Cloud Infrastructure for Java Management Service

Before you can use Java Management Service, you must ensure that your Oracle Cloud Infrastructure environment is set up correctly to allow the communication flow between all required components and cloud services.

This section describes the manual steps to set up Oracle Cloud Infrastructure for Java Management Service. You can skip this section if you've used the Onboarding Wizard. (The Onboarding Wizard automates these steps. For more information, see Checking Required OCI Resources.)

Review the prerequisites and the overview of the steps.

Prerequisites:

Overview

  1. Sign in to Oracle Cloud Infrastructure.
  2. Create a compartment for your JMS resources.
  3. Create a new tag namespace.
  4. Create a new tag key.
  5. Create a user group for your JMS users.
  6. Create one or more user accounts for your JMS users.
  7. Create policies for your user group to access and manage JMS fleets, management agents, and management agent install keys, metrics, and tag namespaces.
  8. Create a dynamic group of all management agents.
  9. Create policies that enable the management agents to interact with JMS, allow JMS to store monitoring data in your tenancy, and use tag namespaces..
  10. Create policies for log configuration.
  11. (Optional) Create policies to perform Java Runtime Lifecycle Management operations.

Steps

  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. Create a compartment for your JMS resources.
    When you sign up for OCI, Oracle creates your tenancy with a root compartment that holds all of your cloud resources. You can think of the root compartment like the root folder in a file system. Oracle recommends that you set up a dedicated compartment for each project so you can associate a compartment with a particular activity or task.
    1. In the Oracle Cloud Console, open the navigation menu and click Identity & Security. Under Identity, click Compartments.
    2. Click Create Compartment.
    3. In the Create Compartment dialog box, enter a name for the compartment (for example, Fleet_Compartment), and a description. The compartment name is required when you create policies. (See Step 7.)
    4. Specify the parent compartment by selecting the root compartment for your tenancy from the drop-down list.
    5. Click Create Compartment.
    6. Find your new compartment in the table of compartments, then hover over the compartment's OCID. Click Copy to copy the OCID into the clipboard and then paste it into your favorite text editor. You'll require it in a later step.
    For more information, see Setting Up Your Tenancy and Managing Compartments.
  3. Create a new tag namespace.
    1. In the console navigation menu, click Governance & Administration. Under Governance, click Tag Namespaces.
    2. Click Create Tag Namespace.
    3. In the Create Tag Namespace dialog box, select the root compartment for your tenancy from the drop-down list.
    4. In the Namespace Definition Name field, enter a name, such as jms.
    5. In the Description field, enter a description, such as For OCI Java Management use only.
    6. Click Create Tag Namespace.
    For more information, see Managing Tags and Tag Namespaces.
  4. Create a new tag key definition in the new tag namespace.
    1. In the console navigation menu, under Governance, click Tag Namespaces.
    2. From the list of namespaces, click the name of your Namespace, such as jms.
    3. Click Create Tag Key Definition.
    4. In the Create Tag Key Definition dialog box, enter the name for the new tag key, for example, fleet_ocid and its description, such as Use to tag a management agent with JMS fleet membership.
    5. Click Create Tag Key Definition.
  5. Create a user group.
    1. In the console navigation menu, click Identity & Security. Under Identity, click Groups.
    2. Click Create Group.
    3. In the Create Group dialog box, enter a name for the group (for example, FLEET_MANAGERS) and a description.
    4. Click Create.
    For more information, see Managing Groups.
  6. Create user accounts for each of your users by following these instructions, Adding Users.
    For more information, see Managing Users.
  7. Create policies for the user group to access and manage JMS fleets, management agents, management agent install keys, metrics, and tag namespaces.

    A policy allows members of a user group to access and manage OCI resources and to monitor workloads.

    1. In console navigation menu, click Identity & Security. Under Identity, click Policies.
    2. Click Create Policy.
    3. In the Create Policy dialog box, enter a name for the policy (for example, JMS_Policy), and a description.
    4. Select the root compartment for your tenancy from the drop-down list.
    5. Click Show manual editor.
    6. In the text box, enter the following statements:
      ALLOW GROUP FLEET_MANAGERS TO MANAGE fleet IN COMPARTMENT Fleet_Compartment
      ALLOW GROUP FLEET_MANAGERS TO MANAGE management-agents IN COMPARTMENT Fleet_Compartment
      ALLOW GROUP FLEET_MANAGERS TO MANAGE management-agent-install-keys IN COMPARTMENT Fleet_Compartment
      ALLOW GROUP FLEET_MANAGERS TO READ METRICS IN COMPARTMENT Fleet_Compartment
      ALLOW GROUP FLEET_MANAGERS TO MANAGE tag-namespaces IN TENANCY
    7. To monitor workloads on OCI using a Management Agent, and if your OCI instances are in a Fleet_Compartment, then enter the following:
      
      ALLOW GROUP FLEET_MANAGERS TO MANAGE instance-family IN COMPARTMENT Fleet_Compartment
      ALLOW GROUP FLEET_MANAGERS TO READ instance-agent-plugins IN COMPARTMENT Fleet_Compartment
      If your OCI instances are in a different compartment, replace Fleet_Compartment with the name of your compartment.
    8. Click Create.
    For more information, see Managing Policies.
  8. Create a dynamic group for management agents communication.
    To interact with the Oracle Cloud Infrastructure service end-points, you must explicitly consent to let the management agents carry on the communication.
    1. In the console navigation menu, click Identity & Security. Under Identity, click Dynamic Groups.
    2. Click Create Dynamic Group.
    3. In the Create Dynamic Group dialog box, enter a name for the dynamic group (for example, JMS_DYNAMIC_GROUP), a description, and a matching rule to allow Management Agents to interact with the Oracle Cloud Infrastructure service end-points.
      For RULE 1, enter
      ALL {resource.type='managementagent', resource.compartment.id='<fleet_compartment_ocid>'}
      Note

      Replace <fleet_compartment_ocid> with the OCID of the compartment that you created in Step 2. (You should have pasted it into a text editor.)

      To monitor workloads in OCI, permit the compute instances' management agents to register with the management agent cloud service of the compartment containing the OCI compute resources,

      For RULE 2, enter
      ANY {instance.compartment.id = '<fleet_compartment_ocid>'}
    4. Click Create.
    For more information, see Managing Dynamic Groups.
  9. Create policies for management agent communication.
    These policies enable the management agents to interact with JMS, allow JMS to store monitoring data in your tenancy, and use tag namespaces.
    1. Create a policy using the instructions in Step 7.
      Note

      You can also add the following statements to the policy created in Step 7, instead of creating a new one.

    2. Enter a name for the policy (for example, JMS_Agent_Policy), and a description.
    3. Select the root compartment for your tenancy from the drop-down list.
    4. Select the Manual Editor, and in the text box, enter the following statements:
      ALLOW DYNAMIC-GROUP JMS_DYNAMIC_GROUP TO USE METRICS IN COMPARTMENT Fleet_Compartment
      ALLOW DYNAMIC-GROUP JMS_DYNAMIC_GROUP TO MANAGE management-agents IN COMPARTMENT Fleet_Compartment 
      ALLOW SERVICE javamanagementservice TO MANAGE metrics IN COMPARTMENT Fleet_Compartment WHERE target.metrics.namespace='java_management_service' 
      ALLOW DYNAMIC-GROUP JMS_DYNAMIC_GROUP TO USE tag-namespaces IN TENANCY
    5. Click Create.
  10. Create policies for log configuration. These policies allows JMS to interact with OCI Logging service for setting up Log Configuration for fleets in the compartment.
    1. Create a policy using the instructions in Step 7.
      Note

      You can also add the following statements to the policy created in Step 7, instead of creating a new one.

    2. Enter a name for the policy (for example, JMS_Logging_Policy), and a description.
    3. Select the root compartment for your tenancy from the drop-down list.
    4. Select the Manual Editor, and in the text box, enter the following statements:
      ALLOW SERVICE javamanagementservice TO MANAGE log-groups IN COMPARTMENT Fleet_Compartment
      ALLOW SERVICE javamanagementservice TO MANAGE log-content IN COMPARTMENT Fleet_Compartment
      ALLOW DYNAMIC-GROUP JMS_DYNAMIC_GROUP TO MANAGE log-content IN COMPARTMENT Fleet_Compartment
    5. Click Create.
  11. (Optional) Create policies to perform Java Runtime Lifecycle Management operations.
    1. Create a policy using the instructions in Step 7.
      Note

      You can also add the following statements to the policy created in Step 7, instead of creating a new one.

    2. Enter a name for the policy (for example, JMS_LCM_Policy), and a description.
    3. Select the root compartment for your tenancy from the drop-down list.
    4. Select the Manual Editor, and in the text box, enter the following statements:
      ALLOW SERVICE javamanagementservice TO READ instances IN tenancy
      ALLOW SERVICE javamanagementservice TO INSPECT instance-agent-plugins IN tenancy
    5. Click Create.

Getting Help

Follow the guidance below if you encounter an error or issue with Oracle Cloud Infrastructure or need help with Java Management Service.

Review the Troubleshooting chapter.

Review Getting Help and Contacting Support in the OCI documentation.

If you're unable to resolve your issue, open a support service request using the Help menu (Help Menu Icon) in the OCI console.