Oracle Management Agent for Enterprise Manager Cloud Control

Oracle Enterprise Manager (OEM) Management Agent is a software component that monitors targets running on hosts and communicates that information to the middle-tier Oracle Management Service (OMS). For more information, see Overview of Oracle Enterprise Manager cloud control 12c and Overview of Oracle Enterprise Manager cloud control 13c in the Oracle documentation.

Amazon RDS supports Management Agent through the use of the OEM_AGENT option. Management Agent requires an Amazon RDS DB instance running any of the following releases:

Amazon RDS supports Management Agent for the following versions of OEM:

Prerequisites for Management Agent

To use Management Agent, ensure that you meet the following prerequisites.

General prerequisites

Following are general prerequisites for using Management Agent:

Oracle Database release prerequisites

Following are the supported Oracle Database versions for each Management Agent version.

Following are prerequisites for different database versions:

OMS host communication prerequisites

Make sure that your OMS host and your Amazon RDS DB instance can communicate. Do the following:

Limitations for Management Agent

Following are some limitations to using Management Agent:

Option settings for Management Agent

Amazon RDS supports the following settings for the Management Agent option.

The following table lists the TLS cipher suites that the Management Agent option supports.

Adding the Management Agent option

The general process for adding the Management Agent option to a DB instance is the following:

If you encounter errors, check My Oracle Support documents for information about resolving specific problems.

After you add the Management Agent option, you don't need to restart your DB instance. As soon as the option group is active, the OEM Agent is active.

If your OMS host is using an untrusted third-party certificate, Amazon RDS returns the following error.

You successfully installed the OEM_AGENT option. Your OMS host is using an untrusted third party certificate. 
Configure your OMS host with the trusted certificates from your third party.        

If this error is returned, the Management Agent option isn't enabled until the problem is corrected. For information about correcting the problem, see the My Oracle Support document 2202569.1.

aws rds add-option-to-option-group \
    --option-group-name "myoptiongroup" \
    --options OptionName=OEM_AGENT,OptionVersion=13.1.0.0.v1,Port=3872,VpcSecurityGroupMemberships=sg-1234567890,OptionSettings=[{Name=OMS_HOST,Value=my.example.oms},{Name=OMS_PORT,Value=4903},{Name=AGENT_REGISTRATION_PASSWORD,Value=password}] \
    --apply-immediately

aws rds add-option-to-option-group ^
    --option-group-name "myoptiongroup" ^
    --options OptionName=OEM_AGENT,OptionVersion=13.1.0.0.v1,Port=3872,VpcSecurityGroupMemberships=sg-1234567890,OptionSettings=[{Name=OMS_HOST,Value=my.example.oms},{Name=OMS_PORT,Value=4903},{Name=AGENT_REGISTRATION_PASSWORD,Value=password}] ^
    --apply-immediately

Using the Management Agent

After you enable the Management Agent option, take the following steps to begin using it.

Modifying Management Agent settings

After you enable the Management Agent, you can modify settings for the option. For more information about how to modify option settings, see Modifying an option setting. For more information about each setting, see Option settings for Management Agent.

Performing database tasks with the Management Agent

You can use Amazon RDS procedures to run certain EMCTL commands on the Management Agent. By running these procedures, you can do the tasks listed following.

Getting the status of the Management Agent

To get the status of the Management Agent, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.get_status_oem_agent. This procedure is equivalent to the emctl status agent command.

The following procedure creates a task to get the Management Agent's status and returns the ID of the task.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.get_status_oem_agent() as TASK_ID from DUAL;            

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

Restarting the Management Agent

To restart the Management Agent, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.restart_oem_agent. This procedure is equivalent to running the emctl stop agent and emctl start agent commands.

The following procedure creates a task to restart the Management Agent and returns the ID of the task.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.restart_oem_agent as TASK_ID from DUAL;    

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

Listing the targets monitored by the Management Agent

To list the targets monitored by the Management Agent, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.list_targets_oem_agent. This procedure is equivalent to running the emctl config agent listtargets command.

The following procedure creates a task to list the targets monitored by the Management Agent and returns the ID of the task.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.list_targets_oem_agent as TASK_ID from DUAL;

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

Listing the collection threads monitored by the Management Agent

To list of all the running, ready, and scheduled collection threads monitored by the Management Agent, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.list_clxn_threads_oem_agent. This procedure is equivalent to the emctl status agent scheduler command.

The following procedure creates a task to list the collection threads and returns the ID of the task.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.list_clxn_threads_oem_agent() as TASK_ID from DUAL;          

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

Clearing the Management Agent state

To clear the Management Agent's state, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.clearstate_oem_agent. This procedure is equivalent to running the emctl clearstate agent command.

The following procedure creates a task that clears the Management Agent's state and returns the ID of the task.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.clearstate_oem_agent() as TASK_ID from DUAL;

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

Making the Management Agent upload its OMS

To make the Management Agent upload the Oracle Management Server (OMS) associated with it, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.upload_oem_agent. This procedure is equivalent to running the emclt upload agent command.

The following procedure creates a task that makes the Management Agent upload its associated OMS and return the ID of the task.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.upload_oem_agent() as TASK_ID from DUAL;

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

Pinging the OMS

To ping the Management Agent's OMS, run the Amazon RDS procedure rdsadmin.rdsadmin_oem_agent_tasks.ping_oms_oem_agent. This procedure is equivalent to running the emctl pingOMS command.

The following procedure creates a task that pings the Management Agent's OMS and returns the ID of the task.

SELECT rdsadmin.rdsadmin_oem_agent_tasks.ping_oms_oem_agent() as TASK_ID from DUAL;

To view the result by displaying the task's output file, see Viewing the status of an ongoing task.

Viewing the status of an ongoing task

You can view the status of an ongoing task in a bdump file. The bdump files are located in the /rdsdbdata/log/trace directory. Each bdump file name is in the following format.

dbtask-task-id.log 

When you want to monitor a task, replace task-id with the ID of the task that you want to monitor.

To view the contents of bdump files, run the Amazon RDS procedure rdsadmin.rds_file_util.read_text_file. The following query returns the contents of the dbtask-1546988886389-2444.log bdump file.

SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1546988886389-2444.log'));

For more information about the Amazon RDS procedure rdsadmin.rds_file_util.read_text_file, see Reading files in a DB instance directory.

Removing the Management Agent option

You can remove the OEM Agent from a DB instance. After you remove the OEM Agent, you don't need to restart your DB instance.

To remove the OEM Agent from a DB instance, do one of the following: