Getting Started with Resource Discovery and Monitoring

Before you can use the Resource Discovery and Monitoring features of the OS Management Hub service, you need to enable the automatic deployment of the Management Agent and plugin. The following section guides you through the setup and configuration process to activate Resource Discovery and Monitoring functionality.

General Workflow for Setting Up Resource Discovery and Monitoring

Step 1: Choose the OCI Compartment

Step 2: Set Up OS Management Hub Service Policies

Step 3: Create a Dynamic Groups of All Management Agents

Step 4: Set Up Resource Discovery and Monitoring Policies

Step 5: Enabling Resource Discovery and Monitoring Manually

Step 6: (Optional) Set up Java Management Service

Note

Ensure that the prerequisites have been performed for the Management Agent. For more information on performing prerequisite setup tasks for the Management Agent, see Perform Prerequisites for Deploying Management Agents on Compute Instances. As part of the Management Agent setup, it will require the creation of a group of instances. Consider re-using the dynamic group whenever possible. For example, you create a dynamic group of instances that can be re-used in the following steps.

Management Agent policies only need to be set up once for each compartment or tenancy.

Step 1: Choose the OCI Compartment

You need to identify the OCI compartment where you want the feature enabled. Users of the Resource Monitoring and Discovery feature must have access to the Compute instances within this compartment. Once you've identified the OCI Compartment with the Compute instances containing the resources you want to monitor, you need to ensure the prerequisite policies have been set up.

Note

If you want to enable the features for multiple compartments, the policies described in subsequent sections must be set up for each compartment. For a list of resource types that can be monitored, see Monitor Resources.

Step 2: Set Up OS Management Hub Service Policies

If you have not already done so, you'll need to set up polices for the OS Management Hub service. These policies only need to be set up once, per compartment or per tenancy. Follow the OSMH Prerequisites instructions to set up policies for OS Management Hub.

You first need to create a dynamic group of Compute instances and then create policies on that dynamic group to enable OS Management Hub service.

A single instance can belong to a maximum of five dynamic groups. A good practice is to re-use the same dynamic group wherever possible across services instead of creating one or more dynamic groups for each service. Make a note of the dynamic group used to set up the policies for OS Management Hub service, and consider re-using that same dynamic group for the policies described in subsequent steps.

For more information about this limitation, see Managing Dynamic Groups.

Note

If a Compute instance existed before policy setup, you need to bounce its Oracle Cloud Agent or wait 24 hours for policies to take effect.

You can verify that the policy is in effect from the OS Management Hub service home page for a specific Compute instance.

Step 3: Create a Dynamic Groups of All Management Agents

To interact with the Oracle Cloud Infrastructure service end-points, users must explicitly create a dynamic group to allow Management Agents to communicate with the Management Agent service (MACS).

In this step, a dynamic group is created using the Identity and Access Management service from the OCI Console. This group includes all the management agents. This is a one-time set up step, as any new management agent being installed will automatically belong to this group based on resource type definition shown below. If you can, re-use the dynamic groups created while setting up the prerequisites the OS Management Hub service.

To access the Identity and Access Management service, open the navigation menu. Under Identity & Security, go to Identity and click Dynamic Groups.
Click Create Dynamic Group.
In the Create Dynamic Group dialog box, enter a name for the dynamic group, a description and the matching rules, and then click Create Dynamic Group.

For more information, see OS Management Hub Policies.

Create a Dynamic Group of Management Agent Resources

For example, you create a dynamic group named Management_Agent_Dynamic_Group with the following under RULE 1:

ALL {resource.type='managementagent', resource.compartment.id='ocid1.compartment.oc1.examplecompartmentid'}

Where resource.type='managementagent' is the management agent resource type definition for Management Agent at dynamic group level, and resource.compartment.id value is the compartment id.

Create a Dynamic Group of Instances

For example, you create a dynamic group named AppmgmtMonitoredInstances with the following under RULE 1:

ALL {instance.compartment.id='<compartment-ocid>'}

Note

The Management Agent and Instances dynamic groups are available to be created as a single dynamic group.

Create a Policy for Agent Communication

Once both dynamic groups are created, you need to create a policies to allow the management agents to interact with the Management Agent service and to allow the management agents to upload data to Oracle Cloud Infrastructure Monitoring service.

ALLOW DYNAMIC-GROUP Management_Agent_Dynamic_Group TO USE METRICS IN COMPARTMENT <compartment_name> where target.metrics.namespace = 'oracle_appmgmt'

ALLOW DYNAMIC-GROUP AppmgmtMonitoredInstances TO {MGMT_AGENT_DEPLOY_PLUGIN_CREATE, MGMT_AGENT_INSPECT, MGMT_AGENT_READ} IN COMPARTMENT <compartment_name>

Step 4: Set Up Resource Discovery and Monitoring Policies

The following policies/permissions are specific to Resource Discovery and Monitoring. The policies only need to be set up once for each compartment or tenancy.

Create the User Group AppmgmtUsers

You need to create a group of users who will use the monitoring features and then grant appropriate policies to the users.

Configure the Policy Statements

ALLOW GROUP AppmgmtUsers TO USE appmgmt-family IN COMPARTMENT <compartment_name>
ALLOW GROUP AppmgmtUsers TO READ metrics IN COMPARTMENT <compartment_name>

If the Compute instance existed before policy setup, bounce its Oracle Cloud Agent or wait 24 hours for policies to take effect.

Enabling Resource Discovery and Monitoring Automatically

The following dynamic group policies will allow each Compute instance to automatically enable this functionality. This allows each instance in the defined compartment(s) to automatically install the OCA Management Agent plugin and deploy the Stack Monitoring plugin that is required for OS Management service Monitored Resource and Top Processes functionality.

Configure the Policy Statements

ALLOW DYNAMIC-GROUP AppmgmtMonitoredInstances TO {APPMGMT_MONITORED_INSTANCE_READ, APPMGMT_MONITORED_INSTANCE_ACTIVATE} 
IN COMPARTMENT <compartment_name> where request.instance.id = target.monitored-instance.id

ALLOW DYNAMIC-GROUP AppmgmtMonitoredInstances TO {INSTANCE_READ,INSTANCE_UPDATE}
IN COMPARTMENT <compartment_name> where request.instance.id = target.instance.id

ALLOW DYNAMIC-GROUP AppmgmtMonitoredInstances TO {APPMGMT_WORK_REQUEST_READ, INSTANCE_AGENT_PLUGIN_INSPECT} 
IN COMPARTMENT <compartment_name>

Make sure the OS Management service is enabled/operational first. This is a prerequisite for automatic enabling functionality along with the policy setup performed above.

Within 15 minutes, the UI should start showing monitored resources/top processes.

Step 5: Enabling Resource Discovery and Monitoring Manually

The following procedure is only needed if the prior steps (which should have auto-deployed the agent) did not successfully occur for some reason.

Enabling Resource Discovery and Monitoring manually involves the following steps:

Deploy the Management Agent Plugin

From OCI Console main menu, select Compute and then Instances. The Instances page displays.
Click on the name of your instance from the table. The Instance Details page displays.
Click the Oracle Cloud Agent tab.
In the Enable Plugin column, make sure the Management Agent plugin is set to Enabled.
Proceed with Deploy the Stack Monitoring Management Agent Plugin.

Deploy the Stack Monitoring Management Agent Plugin

Once the Management Agent is enabled via calling UpdateInstance metadata, it will appear in the OCI Console where you deploy the Stack Monitoring plugin.

From the OCI Console main menu, click Observability & Management. Under Management Agent , click Agents. The Management Agents page displays.
From the Scope menu, select the desired Compartment. The agent running in the Compartment appears in the Agents list.
Click on the vertical ellipses (3 vertical dots) menu located at the far right of the agent line to open the drop-down menu showing actions that can be performed.
From the drop-down menu, choose Deploy Plugins. The Deploy Plugins dialog displays.
Select Stack Monitoring and click Update to close the dialog and initiate the deployment process.

The plugin will be installed on the selected agent (instance) in a few minutes and immediately start reporting metrics

Step 6: (Optional) Set up Java Management Service

If you are planning to use the Java Management Service integration, you will also need to complete these additional steps.

Complete Java Management Service Setup

Ensure that the prerequisites have been performed for the Java Management Service. For more information on performing prerequisite setup tasks for the Java Management Service, see Setting Up Oracle Cloud Infrastructure for Java Management Service. Part of setting up the Java Management Service requires the creation of a group of Management Agents and instances. For those steps, consider re-using the dynamic groups created for the OS Management Hub service and Management Agent setup.

Conifigure Management Agents on OCI Hosts

Follow Configuring a Management Agent on an OCI Compute Instance instructions for each host on which you want to collect Java Runtime details. For Step 4 of the instructions, make sure to execute the setup script with the --enable-user-name flag as shown in section describing collection of user.name property.

Create a Fleet

Create a fleet to group your Java Management resources. For instructions on how to create a Java Management Service fleet, see Creating a Fleet Using an Existing Management Agent Configuration.

Configure the User Policy Statement

You need to add following policy to your AppmgmtUsers group.

ALLOW GROUP AppmgmtUsers TO READ fleet IN COMPARTMENT <compartment_name>

Oracle Cloud Infrastructure Documentation

Step 1: Choose the OCI Compartment

Step 2: Set Up OS Management Hub Service Policies

Step 3: Create a Dynamic Groups of All Management Agents

Step 4: Set Up Resource Discovery and Monitoring Policies

Step 5: Enabling Resource Discovery and Monitoring Manually

Step 6: (Optional) Set up Java Management Service