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:
source-resource-ocid
is the Stack Monitoring resource ID for the resource (e.g. database) that is running on the host.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:
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 theresource_id
property. Theresource_id
is the ID of the EBS resource needing to be refreshed.
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 theallow_delete_resources
property must be added to the payload along with theresource_id
property and the monitoringagent id
property. Theresource_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
- 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:
- 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. - Remove the exporter and set it up again.
./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 ResourceAn 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>"
}
}
}
}