Associating Resources with a Host

Prerequisites

A host must be promoted to full monitoring before you can create associations with the host. See Monitoring Host Servers for more information.

Hosts should be associated with resources that represent an entity fully contained in that host, such a WebLogic Server, a PeopleSoft Application, an Oracle Database, a Concurrent Manager Node from EBS, etc.

Create Associations

The following is the OCI CLI command syntax to create an association between a resource running on a host with the host.

oci stack-monitoring resource associate --association-type uses --compartment-id "<Compartment_OCID>" --source-resource-id "<Source_Resource_OCID>" --destination-resource-id "<Destination_Resource_OCID>"

Where:

1. source-resource-ocid is the Stack Monitoring resource ID for the resource (e.g. database) that is running on the host.
2. destination-resource-ocid is the Stack Monitoring resource ID for the host.

Example

oci stack-monitoring resource associate     --association-type uses     --compartment-id "<Compartment_OCID>"     --source-resource-id "<EBS_OCID>"    --destination-resource-id "<Oracle_Database_OCID>"

The above command can be used to create an association between myHost and myDB resources by specifying source-resource-id as database resource ID and destination-resource-id as host resource ID.

For more information regarding input parameters, see JSON Input Parameters

Best practices for creating associations with all composite resources

In order to have a well organized stack, it is recommended to follow some best practices to associate hosts and other resources.

For example, in the case of a PeopleSoft application that contains a PIA and the PIA lives inside a Host, that PIA should have a uses association with the host in which the PIA was installed.

Refreshing Resources

If there is any change of topology and/or configuration properties, to reflect the changes in the Stack Monitoring service a refresh has to be triggered. This is possible manually by calling the discovery API or, in some cases, through the resource's homepage.

Currently, refresh is supported for the following resource types:

1. EBS Refresh
2. PeopleSoft Refresh
3. WebLogic Domain Refresh
4. Microsoft SQL Server Refresh
5. Oracle Database System Components Refresh
6. Oracle Unified Directory Operations
7. Oracle Golden Gate Refresh

EBS Refresh

EBS instance refresh results in the refresh of the following Stack Monitoring resource types, as well as the underlying Weblogic Domain resources.

ebs_instance
oracle_ebs_app_lsnr
oracle_ebs_conc_mgmt_managers
oracle_ebs_conc_mgmt_service
oracle_ebs_conc_mgmt_service_specialized
oracle_ebs_cp_node
oracle_ebs_forms_system
oracle_ebs_wf_group
oracle_ebs_wf_agent_lsnr
oracle_ebs_wf_bkgd_engine
oracle_ebs_wf_notification_mailer

The EBS instance can be refreshed via UI or OCI CLI:

• Refreshing via UI

  To refresh the EBS instance from the UI it is necessary to enter the homepage of the resource, and click the Refresh Button below the resource name displaying a popup asking for the confirmation. Press the OK to open the Resource Discovery section in a new window where the status of the submitted refresh job is displayed.

• Refreshing via OCI CLI

  To refresh the EBS instance using OCI CLI run the discovery-job create command . In order to allow deletion of resources during the refresh operation add the allow_delete_resources property to the payload along with the resource_id property. The resource_id is the ID of the EBS resource needing to be refreshed.

Examples

ebs_cli_command

oci stack-monitoring discovery-job create  --compartment-id "<Compartment_OCID>" --discovery-type REFRESH --discovery-details file:///tmp/ebs_refresh_dev.json

ebs_refresh_dev.json

{
    "agentId": "<Agent_OCID>",
    "resourceType": "EBS_INSTANCE",
    "resourceName": "ebsTest",
    "properties": {
      "propertiesMap": {
         "allow_delete_resources":"true",
         "resource_id": "<Resource_OCID>"
      }
    }
}

For more information regarding input parameters, see JSON Input Parameters

PeopleSoft Refresh

PeopleSoft application refresh results in the refresh of the following Stack Monitoring resource types:

oracle_psft
oracle_psft_appserv
oracle_psft_prcs
oracle_psft_pia
weblogic_domain (including members) 

The refresh operation will not validate the credentials for new domains found during the refresh process. If during the discovery process there were any failed domains found, these could be stale domains or they might not be accessible for JMX connections from the agent or other reasons. Once the underlying issues are resolved, ensure that the common credentials are valid for each of the new domains that you intend to add by validating via a JMX connection from the agent host and then perform a refresh operation. At the end of a successful refresh operation the new domains will be added and will use the same common crendentials that the already discovered domains are configured with.

The refresh operation will also refresh the existing associated WebLogic domains and their members.

When new PIA instances are added, performing PeopleSoft refresh will discover the newly added PIA resource but it will not discover any underlying new WebLogic domain. You need to discover the WebLogic domain manually using CLI if any and associate that new WebLogic Domain with the newly discovered PIA manually via CLI.

The PeopleSoft instance can be refreshed in two ways:

• Refresh via UI

  To refresh the PeopleSoft instance from the UI it is necessary to enter the homepage of the resource and click the Refresh Button below the resource name. This action will display a popup asking for the confirmation. If the OK button is pressed it will open the Resource Discovery section in a new tab where we can track the status of submitted refresh job.

  Note
  
  Running the Refreshing via UI won't delete the removed resources of the PeopleSoft topology. To remove those resources we will need to delete resources manually or run the Refresh via CLI process.
  Note
  
  A refresh job will not be submitted if there is already a refresh job in progress. This attempt will display a toast notification informing about the current job in progress.

• Refresh via CLI

  To refresh the PeopleSoft instance using OCI CLI it's necessary to run the discovery-job create command. This option involves a JSON file. In order to allow deletion of resources during the refresh operation the allow_delete_resources property must be added to the payload along with the resource_id property and the monitoring agent id property. The resource_id is the ID of the PeopleSoft resource needing to be refreshed.

  Payload JSON file:

  {
      "agentId": <Agent_OCID>,
      "resourceType": "ORACLE_PSFT",
      "resourceName": "<Resource_Name>",
      "properties": {
        "propertiesMap": {
           "allow_delete_resources":"true",
           "resource_id": "<Resource_OCID>"
        }
      }
  }

  Command to Submit the Refresh Job :

  oci stack-monitoring discovery-job create --compartment-id "<Compartment_OCID>" --discovery-type REFRESH --discovery-details file:///tmp/psft_refresh_dev.json

  Note
  
  

  Once the job is submitted, you can check the job status after 30 minutes.

  For more information regarding input parameters, see JSON Input Parameters

Process Monitor

In case process monitor was not discovered at the time of discovery, it is possible to discover it during refresh by appending the propertiesMap with the new property "discover_process_monitor":"true" in the refresh payload JSON file.

Refreshing Elasticsearch JSON File

This is an example of the JSON used to discover Elastic Search along Peoplesoft via CLI during a REFRESH operation.

{
  "discoveryType": "REFRESH",
  "discoveryClient": "APPMGMT",
  "compartmentId": "<Compartment_OCID",
  "discoveryDetails": {
      "agentId": "<Agent_OCID>",
      "resourceType": "ORACLE_PSFT",
      "resourceName": "<Resource name to show up in Stack Monitoring console>",
      "properties": {
          "propertiesMap": {
              "resource_id": "<Resource_OCID>",
              "allow_delete_resources": "true",
              "discover_elastic_search": "true"
          }
      },
      "credentials": {
          "items": [
               {
                   "properties": {
                       "propertiesMap": {
                           "Username": "<ELASTICSEARCH_ENCODED_USERNAME>",
                           "Password": "<ELASTICSEARCH_ENCODED_PASSWORD>",
                           "TrustStorePath": "Location of the trust store containing the certificate_encoded",
                           "TrustStoreType": "Type of the trust store containing the certificate: <JKS>_encoded"
                           "TrustStorePassword": "Trust store containing the certificate password"
                       }
                   },
                   "credentialName": "UmVzdENyZWRz",
                   "credentialType": "SFRUUFNDcmVkcw=="
               }
          ]
      },
      "tags": {
          "map": {}
      }
  }
}

For more information regarding input parameters, see JSON Input Parameters

Command to Submit the Refresh Job

oci stack-monitoring discovery-job create --compartment-id "<Compartment_OCID>" --discovery-type REFRESH --discovery-details file:///path/to/file.json

WebLogic Domain Refresh

WebLogic domain refresh results in the refresh of following Stack Monitoring resource types:

weblogic_domain
weblogic_j2eeserver
weblogic_cluster
oracle_soainfra
oracle_mft
oracle_http_server
oracle_oam
oracle_oam_cluster
oracle_oim
oracle_oim_cluster

The WebLogic Domain can be refreshed using the discovery-job create CLI command. In order to delete a resource during the refresh operation, the allow_delete_resources property must be added in the payload.

Examples

weblogic_cli_command

oci stack-monitoring discovery-job create  --compartment-id "<Compartment_OCID>" --discovery-type REFRESH --discovery-details file:///tmp/weblogic_refresh_dev.json

weblogic_refresh_dev.json

{
    "agentId": "<Agent_OCID>",
    "resourceType": "WEBLOGIC_DOMAIN",
    "resourceName": "weblogicTest",
    "properties": {
      "propertiesMap": {
         "allow_delete_resources":"true",
         "resource_id": "<Resource_OCID>"
      }
    }
}

For more information regarding input parameters, see JSON Input Parameters

Microsoft SQL Server Refresh

Microsoft SQL Server instance refresh results in refresh of the following Stack Monitoring resource type: SQL_SERVER

The Microsoft SQL Server instance can be refreshed using the discovery-job create CLI command. In order to delete a resource during the refresh operation, the allow_delete_resources property must be added in the payload.

Examples

sql_cli_command

oci stack-monitoring discovery-job create  --compartment-id "<Compartment_OCID>" --discovery-type REFRESH --discovery-details file:///tmp/mssql_refresh_dev.json

mssql_refresh_dev.json

{
    "agentId": "<Agent_OCID>",
    "resourceType": "SQL_SERVER",
    "resourceName": "sqlTest",
    "properties": {
      "propertiesMap": {
         "allow_delete_resources":"true",
         "resource_id": "<Resource_OCID>"
      }
    }
}

For more information regarding input parameters, see JSON Input Parameters

JSON Input Parameters

Oracle Database System Components Refresh

The Oracle Database Listener, ASM, cluster components can be added or updated using the discovery-job create CLI command. In order to delete a resource during the refresh operation, the allow_delete_resources property must be added in the payload.

Migrating existing CDB to DB System using CLI refresh

If Oracle Database is already discovered, refresh using CLI to discover the entire DB system. If you are using a remote agent to monitore the DB, install a local agent on each of the DB nodes and add the agent to the additional agents list (Refresh properties / migrate - add additional agents for cluster and listener nodes example). The CLI refresh should run on the database node discovered on the discovery stage - resource_id <Database_OCID>, while the database monitor itself will continue running from the remote agent.

This is an example of the JSON used to refresh properties / migrate existing Database to DB System , with no ASM and no additional agents:

{
  "discoveryType": "REFRESH",
  "discoveryClient": "DISCOVERY_UI",
  "compartmentId": "<COMPARTMENT_OCID>",
  "discoveryDetails": {
    "agentId": "<AGENT_OCID>",
    "resourceType": "ORACLE_DATABASE",
    "resourceName": "<Resource name to display in Stackmonitoring UI>",
    "properties": {
      "propertiesMap": {
          "resource_id":"<DATABASE_OCID>"
      }
    }
  }
}

This is an example of the JSON used to refresh properties / migrate, and add additional agents for cluster and listener nodes:

{
  "discoveryType": "REFRESH",
  "discoveryClient": "DISCOVERY_UI",
  "compartmentId": "<COMPARTMENT_OCID>",
  "discoveryDetails": {
    "agentId": "<OCID of the Management agent>",
    "resourceType": "ORACLE_DATABASE",
    "resourceName": "<Resource name to display in Stackmonitoring UI>",
    "properties": {
      "propertiesMap": {
          "resource_id":"<DATABASE_OCID>",
          "additional_agent_1":"<ADDITIONAL_AGENT1_OCID>",
          "additional_agent_2":"<ADDITIONAL_AGENT2_OCID>"    
      }
    }
  }
}

This is an example of the JSON used to refresh properties / migrate, and add ASM and additional agents:

{
  "discoveryType": "REFRESH",
  "discoveryClient": "APPMGMT",
  "compartmentId": "<COMPARTMENT_OCID>",
  "discoveryDetails": {
    "agentId": "<OCID of the Management agent>",
    "resourceType": "ORACLE_DATABASE",
    "resourceName": "<Resource name to display in Stackmonitoring UI>",
    "properties": {
      "propertiesMap": {
            "resource_id":"<DATABASE_OCID>",
            "asm_host":"<ASM HOSTNAME>",
            "asm_service_name":"+ASM",
            "is_asm_discovery":"true",
            "asm_port":"1521",
            "additional_agent_1":"ADDITIONAL_AGENT1_OCID",
            "additional_agent_2":"ADDITIONAL_AGENT2_OCID"
      }
    },
    "credentials": {
      "items": [
            {
          "credentialName" : "QVNNUGFzc3dvcmRJblZhdWx0",
          "credentialType" : "U1NMX1NFQ1JFVF9JRA==",
          "properties": {
            "propertiesMap": {
              "ASMUserName": "<ASM user name in base64 encoded format>",
              "PasswordSecretId": "<Encoded ASM user secret ocid in BASE64 encoded format>",
              "ASMRole":"<ASM user role in base64 encoded format>"
            }
          }
        }
      ]
    }
  }
}

Oracle Unified Directory Operations

When the OUD instance has a change in its properties, there are two options:

1. Stop the exporter, modify <oud_scripts_dir>/cfg/<instance_name>/exporter.config and start the exporter again.
   Note
   
   Everytime the exporter is started, the monitoring user password will be required.
2. Remove the exporter and set it up again.

./manage_exporter.sh start --pnum <OUD identifier>

./manage_exporter.sh stop --pnum <OUD identifier>

./manage_exporter.sh deinstall exporter --pnum <OUD identifier>

An OUD resource can be deleted through OCI CLI with the following command:

oci stack-monitoring resource delete --resource-id <resource id>

Oracle Golden Gate

Add Golden Gate JSON

{
   "discoveryType": "ADD",
  "compartmentId": "<Compartment OCID>",
  "discoveryClient": "APPMGMT",
  "discoveryDetails": {
    "resourceName": "<Rsource name>",
    "resourceType": "ORACLE_GOLDENGATE",
    "agentId": "<Management Agent OCID>",
    "credentials": {
      "items": [
        {
          "credentialName": "UmVzdENyZWRz",
          "credentialType": "SFRUUFNDcmVkcw==",
          "properties": {
            "propertiesMap": {
              "Username": "<Base64 encoded username>",
              "Password": "<Base64 encoded password>",
              "TrustStorePath": "<Base64 encided Truststore path>",
              "TrustStoreType": "SktT",
              "TrustStorePassword": "<Base64 encoded Truststroe password>"
            }
          }
        }
      ]
    },
    "license": "ENTERPRISE_EDITION",
    "properties": {
      "propertiesMap": {
        "hostname": "<GoldenGate hostname>",
        "port": "<Port>"
      }
    }
  }
}

Refresh Golden Gate JSON

{
  "discoveryType": "REFRESH",
  "compartmentId": "<compartent-id>",
  "discoveryClient": "APPMGMT",
  "discoveryDetails": {
    "resourceName": "<resource_name>",
    "resourceType": "ORACLE_GOLDENGATE",
    "agentId": "<Management Agent Id>",
    "credentials": {
      "items": [
        {
          "credentialName": "UmVzdENyZWRz",
          "credentialType": "SFRUUFNDcmVkcw==",
          "properties": {
            "propertiesMap": {
              "Username": "<Base64 encoded username>",
              "Password": "<Base64 encoded password>",
              "TrustStorePath": "<Base64 encoded "truststore path>",
              "TrustStoreType": "SktT",
              "TrustStorePassword": "<Base64 encoded truststore password>"
            }
          }
        }
      ]
    },
    "license": "ENTERPRISE_EDITION",
    "properties": {
      "propertiesMap": {
        "allow_delete_resources": "true",
        "resource_id": "<resource id>"
      }
    }
  }
}