1. Using Oracle Infrastructure Monitoring
  2. Add Entities for Infrastructure Monitoring
  3. Add Entities Using JSON Files

Add Entities Using JSON Files

In order to monitor various entities, you need to first add them to Oracle Infrastructure Monitoring. Adding new entities to your service includes the tasks listed below.

Note:

You will need to add each entity and its corresponding credentials (if applicable) to its local monitoring agent (Cloud Agent). In some cases, remote monitoring is supported, see My Oracle Support Infrastructure Monitoring Cloud Service Master Note (Doc ID 2195015.1) for more release-specific information.

Note:

Before you begin, ensure that all required agent deployment steps have been performed. These steps are part of the initial setup of your service, see Install Cloud Agents in Installing and Managing Oracle Management Cloud Agents.

Oracle by Example

For examples on adding entities, take a look at the following tutorials:

1. Identify the Entity Types You Want to Monitor

You add entities to Oracle Infrastructure Monitoring directly through the UI, or by adding their respective JSON files to the system. The following table lists entities that the Cloud Agent can monitor for the Oracle Infrastructure Monitoring Service in the current release. Make a note of the entity type(s) you will want to monitor with your service.

In addition to being able to monitor conventional entity types, Infrastructure Monitoring also allows you to monitor Cloud services for third-party vendors that provide Cloud service REST APIs. The following table lists the current

2. Set Up Monitoring Credentials

Monitoring credentials are required to monitor some of the entities using Oracle Infrastructure Monitoring. To locate your entities and set up monitoring credentials, see Prerequisites and Monitoring Credentials.

3. Downloading and Customizing JSON Files

For monitoring, you must create two types of JSON files that contain information about the entities to be monitored:

  1. An entity definition JSON file for each entity type you’re adding.

  2. A corresponding credentials JSON file for each entity you’re adding, if credentials are required to monitor this entity.

To download and customize the JSON files that correspond to your entities, see Download and Customize Oracle Infrastructure Monitoring JSONs.

For information on the various properties and attributes associated with each entity, see Entity Attributes and Properties.

Encrypting the Credentials JSON File

For security, you can use GNU Privacy Guard (GPG) to encrypt text-based credential JSON files using asymmetric keypairs (public and private).

Prerequisites:

  • Ensure both the entities JSON file and credential JSON file have a .json extension.

  • GPG keys have been added to the Linux host in order to convert creds.json into creds.json.gpg (encrypted GPG file).

    For more information on adding GPG keys, see: https://www.cyberciti.biz/tips/linux-how-to-create-our-own-gnupg-privatepublic-key.html

    To convert the JSON files, run the following command::
    gpg –c  <path and name of credential json file>

    Enter the password (provided while adding GPG keys) twice.

    The credential file is converted to GPG format. For example, Db_creds.json.gpg.

  • Ensure the agent is up and running.

Procedure

Note:

The example used in this procedure shows how to encrypt credentials for a database entity using GPG.

  1. Add the entity.

    ./omcli add_entity agent add_db.json -credential_file add_db_creds.json.gpg -encryption_method_gpg

    Enter the passphrase that was provided when you added the GPG keys to the host.

  2. Verify the status of the newly added entity. 
    ./omcli status_entity agent add_db.json
Oracle Management Cloud Agent 
Copyright (c) 1996, 2016 Oracle Corporation.  All rights reserved.
omc_oracle_db.OracleDb11 : AGENT:entity fully monitored
  3. Verify that the newly added target appears when you list targets on the host.
    ./omcli config agent listtargets
Oracle Management Cloud Agent 
Copyright (c) 1996, 2016 Oracle Corporation.  All rights reserved.
[myhost.com, omc_host_linux]
[myhost.com:1839, Lama]
[OracleDb11_sys, omc_oracle_db_system]
[OracleDb11, omc_oracle_db]
[OracleDb11/orcl12c, omc_oracle_db_instance]
  4. Verify that the target and credentials are encrypted in target.xml. <Agent_Home>/agent_inst/sysman/emd/targets.xml 
    <Property NAME="DBPassword" VALUE="{ENC S}{AES-128}3DC4D610690287A389D913ECEA40531CF12DAFAD13940100" ENCRYPTED="TRUE"/>            
<Property NAME="DBRole" VALUE="{ENC S}{AES-128}4D98B5141164AD038C3634C1C8CED0BC56238B3173A0" ENCRYPTED="TRUE"/>                        
<Property NAME="DBUserName" VALUE="{ENC S}{AES-128}F4D7D350906F9778E45880A085AF1D4F164F7B3264A49C59E466FAE09B" ENCRYPTED="TRUE"/>

4. Adding Entities to Your Service

Run the following command from the agent installation directory, for example, on a UNIX system this directory is (<AGENT_BASE_DIR>/agent_inst/bin) to add each entity to your monitoring service:

Note:

When specifying the full path to a JSON file, make sure there are no spaces as these will cause the oemcli add_entity command to fail. 
omcli add_entity agent DEFINITION_FILE [-credential_file CREDENTIAL_FILE [-encryption_method_gpg]]

In this command:

  • DEFINITION_FILE is the entity definition JSON file that contains the details about the entity to be added. This file does not contain any actual credentials but it must contain a reference to credentials specified in the credentials file.

  • -credential_file is the credentials file parameter.

  • CREDENTIAL_FILE is the name of the credentials JSON file. You must define corresponding credentials for each entity that requires them, even if multiple entities happen to have the same monitoring credentials. Some entities may not require credentials for monitoring, in which case the -credential_file parameter can be omitted.

  • -encryption_method_gpg is an optional parameter; if specified, this option indicates that the file is encrypted using GNU Privacy Guard symmetric encryption.

    GNU Privacy Guard (GPG) is an encryption software that is OpenPGP (RFC 4880) compliant. You can use GPG to encrypt and decrypt files that contain sensitive data. To avoid saving sensitive information such as passwords in clear text,  you can first encrypt the credential JSON file with GPG and then use the encrypted JSON file along with the -encryption_method_gpg flag when adding your entity to the monitoring service.

For example, to add a database entity to an agent running on a UNIX system, run:

./omcli add_entity agent omc_oracle_db_prod1.json -credential_file omc_oracle_db_creds.json
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporations. All rights reserved.
Operation Succeeded; Accepted 1 of 1 entities for processing.
If you have an HA configuration (a virtual host with 2 or more physical hosts configured with failover software) note the following:

  • Your Cloud Agents must be installed on all hosts (virtual and physical hosts).

  • The Cloud Agents on your physical hosts will monitor the host entities. Therefore, the steps to enable host monitoring must be performed on the physical hosts, see Monitoring Credentials.

  • The entities you want monitored must be added using the Cloud Agent on the virtual host.

5. Verifying Added Entities

Verify your entity addition by running the following command from the same agent directory (<AGENT_BASE_DIR>/agent_inst/bin): 

omcli status_entity agent DEFINITION_FILE

where DEFINITION_FILE is the entity definition JSON file.

When the addition is complete, the verification will indicate that the entity is fully monitored. For example, if running on a UNIX host, verify as follows:

./omcli status_entity agent omc_oracle_db_prod1.json
Oracle Management Cloud Agent
Copyright (c) 1996, 2019 Oracle Corporation. All rights reserved.
omc_oracle_db.prod1 : AGENT : entity fully monitored

Navigate to the Enterprise Summary dashboard and note the new entity you added. Depending on your network latency and other load factors, allow a few minutes for this process to complete.

Troubleshooting

View Prerequisite Checks

If there are issues when adding an entity, you can obtain more information about the entity addition process by using the -verbose option when performing the verification. This option displays the results of the prerequisite checks which are run automatically during the entity discovery process. For each prerequisite check, the status and, if there is an error, the issue and associated resolution is shown.
omcli status_entity agent DEFINITION_FILE -verbose
./omcli status_entity agent apache_entity.json -verbose
Oracle Management Cloud Agent
Copyright (c) 1996, 2019 Oracle Corporation. All rights reserved.
omc_generic_apache.TestApache2 : AGENT:EntityOperationExeption: Entity Operation Failed: - (Entity count: 0  Validaiton checks: 2 errors found)
        OMC_GENERIC_APACHE-00002 Invalid value for property Is Remote (omc_is_remote).Provided value [ yres ] expected value is Yes or No.
Details:
CHECK 1     :  Validate input property - Listen Port (omc_listen_port)
Status      :  SUCCESS
Check 2     :  Validate input property -Is Remote (omc_is_remote)
Status      :  ERROR
Issue       :  OMC_GENERIC_APACHE-00002 Invalid value for property Is Remote
               (omc_is_remote).Provided value [ yres ] expected value is Yes or No.
Resolution  :  Provide expected value for property Is Remote (omc_is_remote) - 'Yes/No' .
CHECK 3     :  Validate if /server-status page [ http://host.company.com:54123/server-status  ] is accessible
Status      :  ERROR
Issue       :  com.sun.jersey.api.client.ClientHandlerException:  java.net.ConnectException:
               Connection refused (Connection refused)
Resolution  :  Enable access to Apache status page [  http://host.company.com:54123/server-status  ] for host [ host.company.com ]. Update (or add) the block that starts with <Location /server-status> in httpd.conf file. Graceful restart of Apache HTTP Server is required.

Check the Cloud Agent Log Files

For additional troubleshooting information, check the Cloud Agent logs. Entities discovery information is logged in the agent logs, on the hosts where agents are installed. For example, on UNIX hosts these are located in the <AGENT_BASE_DIR>/sysman/log/ directory:

While monitoring an Oracle Database, if you encounter metrics collection errors, it is possible that the monitoring password has expired. To reset the password and re-enable metrics collections:

  • gcagent_sdk.trc

  • gcagent.log

  1. Log in to the monitored database entity and alter the login attempts limit:
    SQL> ALTER PROFILE DEFAULT LIMIT FAILED_LOGIN_ATTEMPTS UNLIMITED;
SQL> Alter user <monitoring user> account unlock;
  2. On the agent host, update the entity monitoring password. For example, on a UNIX host:
    ./omcli update_entity <the original host entity JSON file>
  3. Return to the database entity and reset the login attempts limit to the recommended value 5:
    SQL> ALTER PROFILE DEFAULT LIMIT FAILED_LOGIN_ATTEMPTS 5;

Forcing Entity Discovery

Under certain circumstances, you may want a discovery job to proceed regardless of what issues are raised by the prerequisite checks. For example, when installing a composite entity such as a database system, even though prerequisite validation issues occur when trying to discover a net listener, you may only care about discovering the RAC databases, ASM, and other select database system child entities rather than stopping the discovery process for the entire database system. To do this, you can force the discovery job to proceed via the force option.

When the force option is used, you tell the discovery job to report all issues that occur when the prerequisite validation checks are run, but ignore the check recommendations and to go ahead with the discovery attempt.

Specify the -force option when executing the omcli add_entity or update_entity verb. 

./omcli update_entity <entity definition json file> -force