Application Topology

OCI Command Line Interface (CLI) can be used to discover new resources, create required associations between Stack Monitoring resources, or refresh the entire topology. Specifically, you can use these CLI commands to:

  • Create associations between the resources running on a host to the host. See Associating Resources with a Host.
  • Create associations between the database and the application that uses it such as E-Business Suite or PeopleSoft.

For information about CLI, see Command Line Interface (CLI) and Installing the CLI.

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_conc_mgmt_service
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.

Note

Running the Refreshing via UI won't delete the removed resources of the EBS topology. To remove those resources delete resources manually or refresh via CLI.

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

Input Field Description Notes
<Compartment_OCID> Compartment OCID where the resource resides. Within the Stack Monitoring home page of the resource, Configuration / General OCI Properties / compartmentID
<Agent_OCID> The OCID of the Management Agent monitoring the resource. Within the Stack Monitoring home page of the resource, Configuration / General OCI Properties / managementAgentID
<Host_Name> The fully qualified domain name (FQDN) of the host within Stack Monitoring. Use the same name as the OCI Compute Instance or on-premises host to avoid confusion when navigating between pages or receiving alarms from various namespaces.
<Resource_OCID> The Stack Monitoring OCID Located under Properties within the Stack Monitoring home page.
<Source_Resource_OCID> The Source Stack Monitoring OCID For example, when relating a resource to the host, the source resource OCID is the resource running on the host.
<Destination_Resource_OCID> The Destination Stack Monitoring OCID For example, when relating a resource to the host, the destination OCID is the the host.
<Database_Resource_OCID> The OCID of the database  

Oracle Database System Components Refresh

Note

  • An Oracle Database Refresh, will refresh all components of an Oracle Database system EXCEPT the Oracle Database. For information on updating the Oracle Database, see Update Oracle Database Monitoring Configuration.
  • DB System including its components (Listener, ASM, cluster) is discovered as part of an Oracle Database discovery.
  • DB System discovery & monitoring is supported only in LINUX environments.

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.

CLI Input Variable Description
Compartment_OCID The compartment OCID where the Oracle Database System will be monitored
Resource_Name This is the name of the resource in Stack Monitoring
Agent_OCID Agent of the initial discovery OCID
<Additional_Agent1_OCID> 1st additional node in cluster
<Additional_Agent2_OCID> (etc) 2nd additional node in cluster (continue for each additional node in the cluster)
Database_Port The Oracle Database
DB_Hostname_or_IP The fully qualified domain name or IP address where <AGENT_OCID> above resides.
Database_Service_Name The service name of the CDB or non multi-tenant database
ASM_Hostname This should match the hostname provided as DB_Hostname_or_IP
ASM_Service_Name The service name of the ASM instnace. This is typically +ASM
ASM_Port The typical value is 1521, provide the port to match that of your listener
DB_User_Name / DB_Password Base64 encoded credentials
DB_Role Base64 encoded database user's role
ASM_User_Name / ASM_Password Base64 encoded credentials
ASM_Role Base64 encoded ASM user's role

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.
Start exporter
./manage_exporter.sh start --pnum <OUD identifier>
Stop exporter
./manage_exporter.sh stop --pnum <OUD identifier>
Remove Exporter
./manage_exporter.sh deinstall exporter --pnum <OUD identifier>
Delete Resource

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>"
      }
    }
  }
}