Oracle by Example brandingAdding a MongoDB Entity to Infrastructure Monitoring

section 0Before You Begin

This 15 minute tutorial shows you how to construct a JavaScript Object Notation (JSON) file to add a MongoDB entity to Oracle Management Cloud Infrastructure Monitoring.

Background

When you aren't using data from an on-premises Oracle Enterprise Manager Cloud Control, you can use the Oracle Management Cloud agent command-line interface, omcli, to add entities to be monitored by Infrastructure Monitoring. The entities are described by properties and their values in JSON files. In this tutorial, you add a MongoDB for monitoring.

What Do You Need?

  • A current subscription to Oracle Management Cloud
  • A host where the Oracle Management Cloud agent is installed
  • A current version of MongoDB, configured and reachable.
  • An editor that's capable of syntax highlighting
  • A JSON validator (optional)

Prerequisites

In order to add a MongoDB to Infrastructure Monitoring, you need to first:

  • Install, configure and start a MongoDB per vendor instructions. Note that a MongoDB installation requires root privileges. For more information, see Install MongoDB.
  • Install a Management Could Agent on the a host that has access to the MongoDB you want to monitor. For more information, see Installing Oracle Management Cloud Agents.

section 1Preparing Your MongoDB for Monitoring

In this example you connect to a MongoDB called myDB, as a user with privileges to create another user.

A monitoring user allows the Oracle Management Cloud Agent to connect to the MongoDB database and collect relevant database metrics.

Create a Monitoring User

  1. Using a mongo shell, connect to the myDB MongoDB database and create a monitoring user. In this example, this user is moncs. A read role is sufficient for monitoring: 
    $ /u01/mongodb_install/bin/mongo

[...]

> use myDB
switched to db myDB
>
> db.createUser(
...  {
...    user: "moncs",
...    pwd: "moncs",
...    roles: [  "read" ]
...  }
...)
Successfully added user: { "user" : "moncs", "roles" : [ "read" ] }
  2. Verify that the user moncs was created successfully:
    > show users
{
  "_id" : "myDB.moncs",
  "user" : "moncs",
  "db" : "myDB",
  "roles" : [
    {
      "role" : "read",
      "db" : "myDB"
    }
  ]
}
> exit
bye

Configure MongoDB External Connections

Ensure that your MongoDB listens for connections from external applications by modifying the network interfaces parameter in the mongod.conf configuration file. If allowing publicly accessible interfaces, implement proper authentication and firewall restrictions to protect the integrity of your database.

In this example, MongoDB is configured to listen to all IPs on the system.

  1. Edit the file /etc/mongod.conf with the following:
    # vi /etc/mongod.conf

# network interfaces
net:
  port: 27017
  bindIp: "0.0.0.0"
  2. Test your connection using the following command: 
    $ /u01/mongodb_install/bin/mongo host1.example.com:27017/myDB -u moncs -p moncs

section 2Download and Edit the MongoDB Definition JSON Files

In this step you use the sample JSON files provided by Oracle to create the definition and credentials JSON files needed to define this database in the monitoring framework.

Locate the MongoDB Entity JSON File

JSON files for all entities supported for monitoring are available in a single zip file from the Downloading and Customizing Infrastructure Monitoring JSONs.

  1. Start with downloading the JSON files zip file:
    2. Description of the illustration
  2. Edit and save the omc_mongodb.json as omc_mongodb_myDB.json, with values for your database as shown below:
    3. {
   "entities":[
      {
         "name":"My MongoDB Database",
         "type":"omc_mongodb",
         "displayName":"myDB",
         "timezoneRegion":"MDT",
         "credentialRefs":[
            "NoSQLCreds"
         ],
         "properties":{
            "host_name":{
               "displayName":"host_name",
               "value":"host1.example.com"
            },
            "port":{
               "displayName":"port",
               "value":"27017"
            },
            "database_name":{ "displayName":"database_name","value":"myDB"},
            "capability":{
               "displayName":"capability",
               "value":"monitoring"
            }
         }
      }
   ]
}
  3. Optionally, but highly recommended, use a JSON validator to ensure your newly edited JSON file is valid. For example, copy and paste your edited JSON file content into the JSON validator publicly available at JSONLint - The JSON Validator.

Locate the MongoDB Credentials JSON File

In the same zip file, find the MongoDB credentials file called omc_mongodb_creds.json.

  1. Edit and save the omc_mongodb_creds.json as omc_mongodb_myDB_creds.json, with values for your database as shown below:
    2. {
   "credentials":[
      {
         "id":"NoSQLCreds",
         "name":"NoSQLCreds",
         "credType":"DBCreds",
         "properties":[
            {
               "name":"DBUserName",
               "value":"CLEAR[moncs]"
            },
            {
               "name":"DBPassword",
               "value":"CLEAR[moncs]"
            }
         ]
      }
   ]
}
  2. Optionally, but highly recommended, use a JSON validator to ensure your newly edited JSON file is valid. For example, copy and paste your edited JSON file content into the JSON validator publicly available at JSONLint - The JSON Validator.
    3. Note, for reference, the various entities supported by Infrastructure Monitoring and their associated JSON files are all documented in Downloading and Customizing Infrastructure Monitoring JSONs, organized in a table, by entity.

section 3Download and Edit the MongoDB Definition JSON Files

In this step you use the OMC command line interface, omcli, to add the entity to the monitoring framework. An entity is said to be "added to monitoring" when the OMC Cloud Agent is made aware of its properties. Note that in this example the omcli utility is already in the environment PATH. Typically, omcli is available from $AGENT_BASE_DIR/agent_inst/bin.

An entity is added to the agent using omcli as follows:

  1. First, add the entity:
    $ omcli add_entity agent omc_mongodb_myDB.json \
        -credential_file omc_mongodb_myDB_creds.json

Oracle Management Cloud Agent
Copyright (c) 1996, 2019 Oracle Corporation. All rights reserved.
Operation Succeeded:  Accepted 1 of 1 entities for processing.
  2. Then, verify the entity: 
    $ omcli status_entity agent omc_mongodb_myDB.json 

Oracle Management Cloud Agent
Copyright (c) 1996, 2019 Oracle Corporation. All rights reserved.

omc_mongodb_myDB: AGENT: entity fully monitored

more informationWant to Learn More?