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 includes the following Stack Monitoring resource types:

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 to open the refresh slideout.

  • When all resources are monitored, refresh results in the refresh of the existing resource types. It's not necessary to provide any input to refresh existing resources.
  • For EBS 12.2, when Weblogic is missing, whether it wasn't included from the beginning or its discovery failed, a discovery section is available to enable Weblogic discovery and existing EBS resources are refreshed as well.
  • The "Allow delete resources" option is available under Advanced options. This property allows the deletion of monitored resources that no longer exist in the application.

  Press the OK button 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:

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

  This option involves a JSON file. The payload to be sent is according to the desired operation.

  To refresh existing resources, 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.

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

  To discover Weblogic through the refresh of EBS resources, the payload must include the retry_weblogic_discovery and the Weblogic discovery properties.

  {
          "agentId": "<agent OCID>",
          "resourceType": "EBS_INSTANCE",
          "resourceName": "EBS",
          "properties": {
              "propertiesMap": {
                  "resource_id": "<EBS instance resource OCID>",
                  "allow_delete_resources": "true",
                  "retry_weblogic_discovery": "true",
                  "ebs_admin_server_host": "<EBS Weblogic Domain host>",
                  "ebs_admin_server_port": "<EBS Weblogic Domain port>",
                  "ebs_admin_server_protocol": "<t3/t3s>"
              }
          },
          "credentials": {
              "items": [
                  {
                      "properties": {
                          "propertiesMap": {
                              "Username": "<EBS Weblogic Domain username>",
                              "Password": "<EBS Weblogic Domain password>"
                          }
                      },
                      "credentialName": "Sk1YQ3JlZHM=",
                      "credentialType": "Sk1YQ3JlZHM="
                  }
              ]
          }
  }

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
oracle_psft_prcm
search_engine
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 to open the refresh slideout.

  • When all resources are monitored, refresh results in the refresh of the existing resource types. It's not necessary to provide any input to refresh existing resources.
  • When there are missing resources to be monitored, whether they weren't included from the beginning or their discovery failed, a discovery section is available to enable each missing resource type discovery and existing resources are refreshed as well.
  • The "Allow delete resources" option is available under Advanced options. This property allows the deletion of monitored resources that no longer exist in the application.

  Press the OK button to open the Resource Discovery section in a new window where the status of the submitted refresh job is displayed.

  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 application using OCI CLI run the discovery-job create command:

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

  This option involves a JSON file. The payload to be sent is according to the desired operation.

  To refresh existing resources, 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.

  Payload JSON file:

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

  To discover missing resources, a flag to enable each desired resource type is required alongside its encoded credentials.

  • To discover Application Server Domains, use the flag discover_application_server.
  • To discover PIAs, use the flag discover_pia.
  • To discover Process Scheduler Domains, use the flag discover_process_scheduler.
  • To discover the Process Monitor, use the flag discover_process_monitor, this does note require credentials.
  • To discover the Search Engine, use the flag discover_search_engine.

  {
          "agentId": "<agent Id>",
          "resourceType": "ORACLE_PSFT",
          "resourceName": "<resource name>",
          "properties": {
              "propertiesMap": {
                  "peoplesoft_db_host": "<DB host>",
                  "peoplesoft_db_port": "<DB port>",
                  "peoplesoft_db_service_name": "<DB service name>",
                  "database_protocol": "<tcp/tcps>",
                  "discovery_type": "database_based",
                  "discover_application_server": "true",
                  "discover_pia": "true",
                  "discover_process_scheduler": "true",
                  "discover_process_monitor": "true",
                  "discover_search_engine": "true"
              }
          },
          "credentials": {
              "items": [
                  {
                      "properties": {
                          "propertiesMap": {
                            "DBUserName": "<base64 encoded database username>",
                            "DBPassword": "<base64 encoded database password>",
                            "DBRole": "<base64 encoded database role>"
                          }
                      },
                      "credentialName": "U1FMQ3JlZHM=",
                      "credentialType": "REJDcmVkcw=="
                  },
                  {
                      "properties": {
                          "propertiesMap": {
                            "Username": "<base64 encoded AppServer username>",
                            "Password": "<base64 encoded AppServer password>"
                          }
                      },
                      "credentialName": "Sk1YQXBwU2VydmVy",
                      "credentialType": "Sk1YQ3JlZHM="
                  },
                  {
                      "properties": {
                          "propertiesMap": {
                            "Username": "<base64 encoded JMX username>",
                            "Password": "<base64 encoded JMX password>"
                          }
                      },
                      "credentialName": "Sk1YQ3JlZHM=",
                      "credentialType": "Sk1YQ3JlZHM="
                  },
                  {
                      "properties": {
                          "propertiesMap": {
                            "Username": "<base64 encoded Process Scheduler username>",
                            "Password": "<base64 encoded Process Scheduler password>"
                          }
                      },
                      "credentialName": "Sk1YU2NoZWR1bGVy",
                      "credentialType": "Sk1YQ3JlZHM="
                  },
                  {
                      "properties": {
                          "propertiesMap": {
                              "Username": "c2R23w==",
                              "Password": "Y43m",
                              "TrustStorePath": "YXN23g==",
                              "TrustStorePassword": "YXN23Zg==",
                              "TrustStoreType": "S43T"
                          }
                      },
                      "credentialName": "UmVzdENyZWRz",
                      "credentialType": "SFRUUFNDcmVkcw=="
                  }
              ]
          },
          "tags": {
              "map": {}
          }
      }

  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 Search Engine JSON File

This is an example of the JSON used to discover a Search Engine along Peoplesoft via CLI during a REFRESH operation. Supported Search Engines are OpenSearch and Elasticsearch.

{
    "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_search_engine": "true"
        }
    },
    "credentials": {
        "items": [
            {
                "properties": {
                    "propertiesMap": {
                        "Username": "<SEARCHENGINE_ENCODED_USERNAME>",
                        "Password": "<SEARCHENGINE_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>"
      }
    }
  }
}