Enterprise Manager 12c EMCLI Target Properties and Metadata

by Seth Miller

This post refers to Enterprise Manager 12c Release 3 specifically but much of the information applies to earlier releases. The EMCLI command examples are using the Jython interactive interface. Examples are sometimes shown on multiple lines for clarity and may need to be on the same line to work properly.

Most of the Enterprise Manager Command Line Interface (EMCLI) verbs have a “properties” parameter that consists of one or more (delimited by a semi-colon by default) name-value pairs (delimited by a colon by default). This “properties” parameter can mean different things depending on what verb you are using.

This post will use the “add_target” verb as an example. The documentation defines the “properties” parameter for the “add_target” verb as:

Name-value pair (that is, prop_name:prop_value) list of properties for the target instance. The “name”(s) are identified in the target-type metadata definition. They must appear exactly as they are defined in this file. Metadata files are located in $AGENT_HOME/sysman/admin/metadata.

The last sentence specifying where the metadata files are located is simply not true but is a rough interpretation of where the files are. Let’s assume the 12c agent was installed in a base directory called “/u01/app/oracle/product/12.1.0/agent12c”. All of the plugins would be installed in the “plugins” subdirectory of the base directory. The “metadata” directory would be a subdirectory of the plugin and the files contained within that directory pertain to the target types.

Base Directory = /u01/app/oracle/product/12.1.0/agent12c
Plugins Directory = /u01/app/oracle/product/12.1.0/agent12c/plugins
Database Plugin Directory = /u01/app/oracle/product/12.1.0/agent12c/plugins/oracle.sysman.oh.agent.plugin_<version>
Database Plugin Metadata Directory = /u01/app/oracle/product/12.1.0/agent12c/plugins/oracle.sysman.oh.agent.plugin_<version>/metadata
Database Instance Metadata File = /u01/app/oracle/product/12.1.0/agent12c/plugins/oracle.sysman.oh.agent.plugin_<version>/metadata/oracle_database.xml

Where the documentation is a little more accurate (but not really) would be for the “host” target type. Since the “host” target type does not use a plugin, it is located in the “core” directory.

Base Directory = /u01/app/oracle/product/12.1.0/agent12c
Core Directory = /u01/app/oracle/product/12.1.0/agent12c/core/<version>
Core Metadata Directory = /u01/app/oracle/product/12.1.0/agent12c/core/<version>/sysman/admin/metadata
Host Metadata File = /u01/app/oracle/product/12.1.0/agent12c/core/<version>/sysman/admin/metadata/host.xml

Many of the verbs (including add_target) requires that the “Oracle Home” be specified in the properties parameter. When adding or modifying targets in the UI, this property appears on the “Monitoring Configuration” page.

target properties 1 Enterprise Manager 12c EMCLI Target Properties and Metadata

However, when specifying the Oracle Home property in the add_target verb, the name of the property is “OracleHome”.

add_target(
name='ORCL1_RAC1',
type='oracle_database',
host='rac1.example.com',
properties='
  SID:ORCL1;
  Port:1521;
  OracleHome:/u01/app/oracle/product/11.2.0/dbhome_1;
  MachineName:rac1.example.com',
credentials='
  Role:normal;
  UserName:dbsnmp;
  password:password') 

To find the correlation between the property in the UI and what is specified in the EMCLI verb, we need to (as the documentation specifies) look into the “metadata” files of the agent. What isn’t clear from the documentation is that there are multiple places in the agent binaries where “metadata” files are found.

The example given above is for an “oracle_database” target type. Since the monitoring of Oracle database targets are now done with a plugin, the “$AGENT_HOME” actually means the Oracle database plugin home in this case.

The metadata files have “.xml” or “.xmlp” file extensions. The target type of “oracle_database” is in the “oracle_database.xml” file. These files are not very well commented so having a basic understanding of XML is required. The relevant information is usually toward the bottom but it is easiest to just search for the opening XML tag called “<InstanceProperties>”. For some target types, the XML elements we are looking for will be nested within the “<InstanceProperties>”. But, for others (like this one), they will be referenced from another location.

  <InstanceProperties>
        &inst_static_props;
        &dynamic_properties;
        &esa_inst_dynamic_properties;
        &esa_db_dynamic_properties;
        &inst_dynamic_props;

  </InstanceProperties>

In this case, the information we are looking for is not directly inside the “<InstanceProperties>” element. When the XML parser finds an ampersand in the XML data, it expects to find a symbol name and a semicolon following it. The symbol name provides a symbolic reference to another entity. A quick search on this symbolic reference finds that the information is actually stored in another file.

<!DOCTYPE TargetMetadata  [
<!ENTITY inst_static_props SYSTEM "./inst_properties.xmlp">
<!ENTITY inst_dynamic_props SYSTEM "./inst_dynamic_props.xmlp">

...

<!ENTITY dynamic_properties SYSTEM "./dyn_props.xmlp">
<!ENTITY esa_inst_dynamic_properties SYSTEM "./esa_instance_dyn_props.xmlp">
<!ENTITY esa_db_dynamic_properties SYSTEM "./esa_database_dyn_props.xmlp">

...

]>

The “inst_properties.xmlp” file contains the elements we are looking for. Each verb property is specified in an “<InstanceProperty>” element. The element uses a combination of tags and nested elements to define the verb property.

<InstanceProperty NAME="OracleHome" CREDENTIAL="FALSE" OPTIONAL="FALSE">
        <Display>
                <Label NLSID="OracleHome_iprop">Oracle home path</Label>
        </Display>
</InstanceProperty>

The first tag called “NAME” is what is used as the property name in the verb. The “CREDENTIAL” tag set to “TRUE” means that the property would be specified in the “credentials” verb parameter, not the “properties” parameter. The “OPTIONAL” tag set to “TRUE” means the property is not necessary and will likely have a default value if not specified. The “IS_COMPUTED” tag set to “TRUE” means that the parameter is dynamically calculated. The “Label” element will give you a good idea what property matches in the UI monitoring configuration page but it usually does not map directly. Not all of the properties specified in the XML file will show up in the UI configuration either.

From the information in this file, we can tell that the “properties” (they are case sensitive) that must to be specified for the “oracle_database” type are:

  • OracleHome
  • MachineName
  • Port
  • SID

The “properties” that can be optionally specified are:

  • PreferredConnectString

The “credentials” that must to be specified are:

  • UserName
  • password

The “credentials” that can be optionally specified are:

  • Role

Much of the configuration information in Oracle’s products (especially Enterprise Manager) is stored in XML. Having a basic understanding of the XML structure helps a lot in identifying the information you are looking for. The information used in the “properties” and “credentials” parameters for many of the verbs in the Enterprise Manager CLI can be found in the metadata files within the agent binaries. Knowing where to look and what to look for is the most important step.