Oracle Management Cloud Common REST API

Monitor Custom Entities Using the Metrics API

This example will go over the fastest way to create custom entities along with custom metrics and associations for them by using the REST API for Oracle Management Cloud.

Background

A system administrator was tasked to manage the company's application consisting of:

An Oracle Database deployed on an Oracle Linux Host that is already being managed in Oracle Management Cloud through a Cloud Agent.
A NanoHTTPD Server deployed on a CoreOS Container that we want to start managing through the REST API.

Figure 1 - Entity Diagram

This image describes the topology of this exercise. There is a Linux host running Oracle Database that is currently managed by an agent and a CoreOS container running a NanoHTTP Server that is going to be managed using the REST API.

NanoHTTPD Servers and CoreOS Containers are some resources that are not supported by Oracle Management Cloud out of the box. The goal for this exercise is to demonstrate the capabilities of the Upload Metrics API. The first to do is look at the design of the entity types and entities we will need for this use case.

Entities

The following are the entities and metrics :

NanoHTTPD-001:

NanoHTTPD Servers are not supported out of the box by Oracle Management Cloud. This is not an issue as this entity can be created and assigned the following custom metrics using the REST API:
- ActiveThreadPoolThreads
- HoggingThreadPoolThreads
- IdleThreadPoolThreads
- JDBCConnectionPoolSize
- JDBCConnectionsInUse
- HeapUsage
- NonHeapMemoryUsage
Core-OS-001:

CoreOS Containers are also not supported out of the box by Oracle Management Cloud. The following metrics are going to be assigned:
- CpuUtilization
- CpuIdle
- MemoryLoad
- MemoryUsage
- MemoryUtilization
- FileSystemName
Oradb-001:

This Oracle Database entity is already being managed by Oracle Management Cloud. This entity will be associated to our CoreOS and NanoHTTPD entities.

Uploading metrics for nanoHTTPD-001

The Upload Metrics call will create the entity type for NanoHTTPD servers and create a new entity called nanoHTTPD-001. Create a new JSON file called nanohttpdmetrics.json which includes the metrics required that need to be uploaded to Oracle Management Cloud:

nanohttpdmetrics.json

[
  {
    "collectionTime": "2018-10-18T16:52:57.810Z",
    "entityName": "nanoHTTPD-001",
    "entityType": "nanoHTTPDServer",
    "metric": "ActiveThreadPoolThreads",
    "value": 15
  },
  {
    "collectionTime": "2018-10-18T16:52:57.810Z",
    "entityName": "nanoHTTPD-001",
    "entityType": "nanoHTTPDServer",
    "metric": "HoggingThreadPoolThreads",
    "value": 99
  },
  {
    "collectionTime": "2018-10-18T16:52:57.810Z",
    "entityName": "nanoHTTPD-001",
    "entityType": "nanoHTTPDServer",
    "metric": "IdleThreadPoolThreads",
    "value": 6
  },
  {
    "collectionTime": "2018-10-18T16:52:57.810Z",
    "entityName": "nanoHTTPD-001",
    "entityType": "nanoHTTPDServer",
    "metric": "JDBCConnectionPoolSize",
    "value": 28
  },
  {
    "collectionTime": "2018-10-18T16:52:57.810Z",
    "entityName": "nanoHTTPD-001",
    "entityType": "nanoHTTPDServer",
    "metric": "JDBCConnectionsInUse",
    "value": 24
  },
  {
    "collectionTime": "2018-10-18T16:52:57.810Z",
    "entityName": "nanoHTTPD-001",
    "entityType": "nanoHTTPDServer",
    "metric": "HeapUsage",
    "value": 83
  },
  {
    "collectionTime": "2018-10-18T16:52:57.810Z",
    "entityName": "nanoHTTPD-001",
    "entityType": "nanoHTTPDServer",
    "metric": "NonHeapMemoryUsage",
    "value": 48
  }
]

Next, make a curl call uploading the metrics:

curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/metrics?async=false -d "@nanohttpdmetrics.json"

Uploading Metrics for CoreOS Container

The CoreOS Container entity type and entity also doesn't exist yet. Oracle Management Cloud will automatically create the entity type CoreOSContainer, entity name core-os-001. Create a new JSON file called coreosmetrics.json that include the metrics in the design:

coreosmetrics.json

[
  {
    "collectionTime": "2018-10-18T16:52:57.924Z",
    "entityName": "core-os-001",
    "entityType": "CoreOSContainer",
    "metric": "CPUUtilization",
    "value": 58
  },
  {
    "collectionTime": "2018-10-18T16:52:57.924Z",
    "entityName": "core-os-001",
    "entityType": "CoreOSContainer",
    "metric": "CPUIdle",
    "value": 18
  },
  {
    "collectionTime": "2018-10-18T16:52:57.924Z",
    "entityName": "core-os-001",
    "entityType": "CoreOSContainer",
    "metric": "MemoryLoad",
    "value": 79
  },
  {
    "collectionTime": "2018-10-18T16:52:57.924Z",
    "entityName": "core-os-001",
    "entityType": "CoreOSContainer",
    "metric": "MemoryUsage",
    "value": 74
  },
  {
    "collectionTime": "2018-10-18T16:52:57.924Z",
    "entityName": "core-os-001",
    "entityType": "CoreOSContainer",
    "metric": " MemoryUtilization",
    "value": 63
  },
  {
    "collectionTime": "2018-10-18T16:52:57.924Z",
    "entityName": "core-os-001",
    "entityType": "CoreOSContainer",
    "metric": "FileSystemName",
    "value": "WEvc"
  }
]

Next, make a curl call with the previous JSON file in order to create the entity type, entity, and metrics for the CoreOS Container:

curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/metrics?async=false -d "@coreosmetrics.json"

Creating Associations between Entities

Oracle Management Cloud allows associations between entities. Associations are defined while creating or updating an entity and are the best way to manage how entities are related to one another.

Figure 2 - Association Diagram

A total of two associations will be created during this exercise. The first association that will be created is from nanoHTTPD-001 to oradb-001 and core-os-001. The second association is from nanoHTTPD-001 to core-os-001.

Our NanoHTTPD entity nanoHTTPD-001 will be associated to core-os-001 and oradb-001 with the use of a entity name, entity type, and tag. For this example, we use a omc_uses tag as our association tag. A tag is a useful way to organize, categorize, and query your entities. Create a new JSON file called associateNano.json with the following information:

{
  "entityType":"nanoHTTPDServer",
  "entityName":"nanoHTTPD-001",
  "associations": [
    {
      "entityName": "oradb-001",
      "entityType": "OracleDatabase",
      "tags": {
        "omc_uses": ""
      }
    },
    {
      "entityName": "core-os-001",
      "entityType": "CoreOSContainer",
      "tags": {
        "omc_uses": ""
      }
    }
  ]
}

The following curl call is used to create new entities or update their definition. Next curl call will update the definition of nanoHTTPD-001 to associate the entity to core-os-001 and oradb-001.

curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@associateNano.json"

Now, create a new JSON called associateCoreOS.json with the following information:

{
  "entityType":"coreOSContainer",
  "entityName":"core-os-001",
  "associations": [
    {
      "entityName": "nanoHTTPD-001",
      "entityType": "HttpWebServer",
      "tags": {
        "omc_uses": ""
      }
    }
  ]
}

Entity core-os-001 was created after the upload metrics call, this next call will update the entity to create an association to nanoHTTPD-001 using the associateCoreOS.json as the payload:

curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@associateCoreOS.json"

Figure 3 - Entity Topology in the UI

This image shows the Oracle Management Cloud UI with the newly created entities and associations during this use case.

The Oracle Management Cloud UI will show the newly created entities and associations when the use case is completed.