2 Developing a Management Plug-in

Each Management Plug-in defines a new type of target that can be monitored by Enterprise Manager. A target, or more specifically, a target instance, can be defined as any monitorable entity within an enterprise. A monitorable entity can be an application running on a server, the server itself, the network or any of its constituent parts. Enterprise Manager makes managing target instances simple by allowing you to add new target instances to the management framework from the Enterprise Manager Grid Control console, at which point you can take advantage of Enterprise Manager's monitoring and administrative functionality.

Enterprise Manager relies on a series of XML files that define a new target type to the system. A Management Plug-in consists of all files required to monitor a specific target from within Enterprise Manager.

Important:

Much of Enterprise Manager is built around XML files. For this reason, it is essential that you are familiar with XML and related technologies. This chapter assumes that you have a working knowledge of XML and DTDs.

XML (eXtensible Markup Language) - An XML document is a structured text document that conveys a particular kind of information.
DTD (Document Type Declaration) - A DTD provides the grammar for the XML files, thus describing what content is expected in each of its related XML files. When creating a new XML file, you need to carefully study its DTD to understand what content needs to be present in that file.

Once a Management Plug-in has been defined, you add it to a Management Plug-in Archive that is imported into Enterprise Manager. An archive encapsulates the one or more Management Plug-ins within a single jar file.

Creating a Management Plug-in consists of five stages:

Designing your Management Plug-in.
Developing the requisite target type definition files that make up the Management Plug-in.
Validating the target type definition.
Using the Enterprise Manager Command Line Interface (EM CLI), Package the target type definition files into a portable Management Plug-in Archive file.

Designing Your Management Plug-in

Before creating actual plug-in files, you need to define what parameters of the target type are required to accurately monitor and manage your new component. This involves:

Identifying performance and configuration metrics that should be collected.
Determining how often each metric should be collected. Oracle recommends that the collection frequency for any metric should not be less than once every five minutes.
Based on customer-specific operational practices, specifying default warnings and/or critical thresholds on these metrics. Whenever a threshold is crossed, Enterprise Manager generates an alert, informing administrators of potential problems.

Developing Requisite Management Plug-in Files

Once you have determined how a particular type of target should be monitored, you are ready to begin creating the Management Plug-in files that define this particular target type to Enterprise Manager. To create a target type is to define to Enterprise Manager not only what a target is, but more importantly what should be monitored (metrics), and how monitoring should be performed.

File Locations

The following table lists the key files used by Enterprise Manager for system configuration and extensibility. When a Managment Plug-in is deployed to an Agent, the requisite files are copied to their respective directory locations.

Table 2-1 Configuration File Locations

Name	Directory Location	Purpose
target_type.xml (Required to define a target type.)	AGENT_HOME/sysman/admin/metadata/	Defines metrics to be collected/computed for the target type.
target_collections.xml(Required to define a target type.)	AGENT_HOME/sysman/admin/default_collection/	Defines metric collection parameters such as metric data collection intervals and default alert thresholds. Typically, the name of the metadata (target_type.xml) file and the default collection file are identical.
targets.xml	AGENT_HOME/sysman/emd/	Lists user-added target instances added to the Enterprise Manager framework. This file is generated and updated by Enterprise Manager and/or the Target Instance Installer utility. This file should not be edited manually.

DTD files associated with the XML configuration files can be found at the locations specified in Table 2-2.

Table 2-2 Document Type Declaration Files

Name	Directory Location	Purpose
TargetMetadata.dtd	AGENT_HOME/sysman/admin/dtds/	Documentation Type Declaration (DTD) file associated with the target_type.xml file.
TargetInstance.dtd	AGENT_HOME/sysman/admin/dtds/	DTD associated with the targets.xml file.
TargetCollection.dtd	AGENT_HOME/sysman/admin/dtds/	DTD associated with the target_collections.xml files.

When you deploy a Management Plug-in, Enterprise Manager automatically copies all plug-in files to the appropriate locations. Conversely, when you are ready to update or remove a Management Plug-in, appropriate files are replaced in the case of a plug-in upgrade, or removed if a plug-in is undeployed.

Important:

The Management Plug-in deployment mechanism does not permit overwriting of Oracle-supplied metadata files.

Target Definition Files

Adding a target type to the Enterprise Manager framework makes it possible for any instance of that target type to be monitored by an Oracle Management Agent once the target instance has been added to the framework from the Enterprise Manager Grid Control console. Every target type within the Enterprise Manager Grid Control framework must be unique. Defining a target type and making this information available to an Oracle Management Agent involves creating two XML files:

Target Type Metadata File

The definition of a target type is composed primarily of the metrics you wish to expose. The file contains a list of all metrics collected for a particular target type, along with specifics on how to compute each metric.

Target Type Default Collections File

Whether you want to regularly upload metric values to the Management Repository or check these values against specific conditions, you will need to define default collection intervals for each of the target metrics. This is also the file where you specify alert thresholds for each metric, enabling events to be triggered when violations occur. Users will be allowed to override the defaults, but the original collections file must be provided by the target provider.

The following steps take you through the process of creating the target type metadata and collection files, registering them with the Enterprise Manager framework, and finally adding instances of the new target type to the Enterprise Manager Grid Control console for monitoring.

Creating the target type metadata file.

Target type metadata consists of the metrics you want to expose and the methods used to retrieve and compute those metrics. The target type metadata file tells the Oracle Management Agent what data to retrieve and how to obtain that data for this particular target type. Users can add a new target type by creating a new target metadata XML file and placing it under $AGENT_HOME/sysman/admin/metadata/.

Note:

Manually placing the target metadata XML file in the AGENT_HOME metadata directory is for development purposes only. The target metadata file is automatically placed in the metadata directory when the Management Plug-in is deployed to the Agent.

Target Type Metadata File Naming Conventions

Although you can specify any name for a target type metadata file, Oracle recommends that users adding new target types adhere to Enterprise Manager naming conventions. This naming convention allows for file naming consistency in environments where similar products from multiple vendors are used. The target naming convention follows the form <vendor>_<product category>. For example:

cisco_router.xml
oracle_apache.xml
bea_http.xml
cisco_slb.xml
f5_slb.xml
nortel_slb.xml

To account for cases where one product category contains multiple product offerings from a single vendor, Oracle recommends that you use the following file naming convention:

<vendor>_<category>_<brand name>

For example:

f5_slb_bigip.xml
f5_slb_3dns.xml

Enterprise Manager ships with a wide array of predefined target type metadata files that cover the most common target types. In situations where the predefined target metadata files do not fit exactly the types of targets you wish to monitor, you can either create a new target metadata file from scratch, or use one of the predefined metadata files as a template for defining a new target type, and then repackage them as a new Management Plug-in. The pre-defined metadata files are located in the $AGENT_HOME/sysman/admin/metadata directory.

Anatomy of a Target Type Metadata File.

At the highest definition level, the target type metadata file is composed of four primary XML elements:

TargetMetadata (top level)
- Display (Oracle Internal Use)
- Metric
- InstanceProperties

Although this section briefly introduces XML elements and some of tag options used to define target metadata, for explicit definitions and other important usage information, see the TargetMetadata.dtd file located in the $AGENT_HOME/sysman/admin/dtds directory.

The following example shows the primary XML elements of the Net App Filer target type metadata file.

Example 2-1 Target Type Metadata File

<?xml version="1.0" ?><!DOCTYPE TargetMetadata SYSTEM "../dtds/TargetMetadata.dtd"><TargetMetadata META_VER="2.2" TYPE="netapp_filer" CATEGORY_PROPERTIES="IsClusterEnabled;IsSnapLicensed;Filer_Version"><Display>  <Label NLSID="netapp_filer">Network Appliance Filer</Label></Display> <!-- ************************************************************************************ -->  <Metric NAME="Product" TYPE="TABLE">    <Display>      <Label NLSID="netapp_filer_info">Product Information</Label>    </Display>    <TableDescriptor>      <ColumnDescriptor NAME="productCategory" TYPE="STRING">        <Display>         <Label NLSID="netapp_filer_product_category">Product Category</Label>        </Display>      </ColumnDescriptor>      <ColumnDescriptor NAME="prodVersion" TYPE="STRING">        <Display>          <Label NLSID="netapp_filer_product_version">Version</Label>        </Display>      </ColumnDescriptor>      <ColumnDescriptor NAME="prodId" TYPE="STRING">        <Display>          <Label NLSID="netapp_filer_product_id">Product ID</Label>        </Display>      </ColumnDescriptor>      <ColumnDescriptor NAME="prodVendor" TYPE="STRING">        <Display>          <Label NLSID="netapp_filer_product_vendor">Vendor</Label>        </Display>      </ColumnDescriptor>      <ColumnDescriptor NAME="prodModel" TYPE="STRING">        <Display>          <Label NLSID="netapp_filer_product_model">Model</Label>        </Display>      </ColumnDescriptor>         <ColumnDescriptor NAME="firmwareVersion" TYPE="STRING">            <Display>               <Label NLSID="netapp_filer_firmware_version">Firmware Version</Label>            </Display>      </ColumnDescriptor>      <ColumnDescriptor NAME="prodVersionBucket" TYPE="STRING"  COMPUTE_EXPR="(prodVersion __contains 'NetApp Release 7.') ? '7.X':'6.X'" TRANSIENT="TRUE">        <Display>          <Label NLSID="netapp_filer_prodVersionBucket">Product Version Bucket</Label>        </Display>      </ColumnDescriptor>    </TableDescriptor>    <QueryDescriptor FETCHLET_ID="Snmp">      <Property NAME="NAME" SCOPE="INSTANCE">NAME</Property>      <Property NAME="hostname" SCOPE="INSTANCE">AgentHost</Property>      <Property NAME="COMMUNITY" SCOPE="INSTANCE" OPTIONAL="TRUE">CommunityString</Property>      <Property NAME="TIMEOUT" SCOPE="INSTANCE" OPTIONAL="TRUE">Timeout</Property>      <Property NAME="TABLE"    SCOPE="GLOBAL">FALSE</Property>      <Property NAME="OIDS"     SCOPE="GLOBAL">1.3.6.1.2.1.1.2.0                                               1.3.6.1.4.1.789.1.1.2.0                                               1.3.6.1.4.1.789.1.1.3.0                                               1.3.6.1.4.1.789.1.1.4.0                                               1.3.6.1.4.1.789.1.1.5.0                                               1.3.6.1.4.1.789.1.1.6.0      </Property>    </QueryDescriptor>  </Metric>.
.
.
<InstanceProperties>   <DynamicProperties NAME="ClusterConfig" FORMAT="ROW"                       PROP_LIST="IsClusterEnabled">     <QueryDescriptor FETCHLET_ID="Snmp">       <Property NAME="NAME" SCOPE="INSTANCE">NAME</Property>       <Property NAME="hostname" SCOPE="INSTANCE">AgentHost</Property>       <Property NAME="COMMUNITY" SCOPE="INSTANCE" OPTIONAL="TRUE">CommunityString</Property>       <Property NAME="TIMEOUT" SCOPE="INSTANCE" OPTIONAL="TRUE">Timeout</Property>       <Property NAME="TABLE"    SCOPE="GLOBAL">FALSE</Property>       <Property NAME="OIDS"     SCOPE="GLOBAL">1.3.6.1.4.1.789.1.2.3.1.0</Property>     </QueryDescriptor>   </DynamicProperties>      <DynamicProperties NAME="VersionConfig" FORMAT="ROW"                       PROP_LIST="Filer_Version">    <ExecutionDescriptor>       <GetTable NAME="Product"/>       <GetView NAME="Config" FROM_TABLE="Product">               <Column NAME="prodVersionBucket"/>        </GetView>     </ExecutionDescriptor>   </DynamicProperties>   <DynamicProperties NAME="SnapMirrorConfig" FORMAT="ROW"                       PROP_LIST="IsSnapLicensed">     <QueryDescriptor FETCHLET_ID="Snmp">       <Property NAME="NAME" SCOPE="INSTANCE">NAME</Property>       <Property NAME="hostname" SCOPE="INSTANCE">AgentHost</Property>       <Property NAME="COMMUNITY" SCOPE="INSTANCE" OPTIONAL="TRUE">CommunityString</Property>       <Property NAME="TIMEOUT" SCOPE="INSTANCE" OPTIONAL="TRUE">Timeout</Property>       <Property NAME="TABLE"    SCOPE="GLOBAL">FALSE</Property>       <Property NAME="OIDS"     SCOPE="GLOBAL">1.3.6.1.4.1.789.1.9.19.0</Property>     </QueryDescriptor>   </DynamicProperties>    <InstanceProperty NAME="AgentHost" CREDENTIAL="FALSE" OPTIONAL="FALSE">      <Display>        <Label NLSID="netapp_filer_agent_host">Hostname or IP Address</Label>      </Display>    </InstanceProperty>    <InstanceProperty NAME="CommunityString" CREDENTIAL="TRUE" OPTIONAL="TRUE">      <Display>        <Label NLSID="netapp_filer_community_string">SNMP Read Community String (Default: public)</Label>      </Display>      public    </InstanceProperty>    <InstanceProperty NAME="Timeout" CREDENTIAL="FALSE" OPTIONAL="TRUE">      <Display>        <Label NLSID="netapp_filer_timeout">SNMP Timeout (Default: 5 seconds)</Label>      </Display>      5    </InstanceProperty>
...</InstanceProperties></TargetMetadata>

From the target metadata file excerpt, you can see that the file consists of the following functional areas where you define your target metadata:

TargetMetadata and Display
Metric Name
Instance Properties

TargetMetadata and Display

The first lines after the header of the target definition file identify the target type. The following example is an excerpt from the Net App Filer target definition file.

Example 2-2 TargetMetadata and Display XML Elements

<?xml version="1.0" ?>
<!DOCTYPE TargetMetadata SYSTEM "../dtds/TargetMetadata.dtd">
<TargetMetadata META_VER="2.2" TYPE="netapp_filer" CATEGORY_PROPERTIES="IsClusterEnabled;IsSnapLicensed;Filer_Version">
<Display>
  <Label NLSID="netapp_filer">Network Appliance Filer</Label>
</Display>

These lines define the basic specifications: metadata version (META_VER="2.2"), target type (TYPE="netapp_filer"), the target's NLS Identifier (NLSID="netapp_filer") and display name text ("Network Appliance Filer"). Metadata versioning allows different versions of the same target type metadata to exist concurrently within the managed environment (one metadata version per Management Agent).You should change the metadata version each time you update the target metadata file. Typically a target type consists of the company name followed by the product name. The "Display" element is used internally by Oracle for translation purposes and is not required when defining new target types. "Display" elements are used with various elements in the target metadata for both readability and internationalization.

Metric NAME

The content of the target type metadata file is devoted primarily to metric definitions. As a matter of practice, Oracle recommends that you specify at least two metrics for any target type:

Metric to monitor target availability (Required for all target types.)
Metric to monitor target performance (Optional but recommended.)

For target availability to show up correctly on the default target home page, Oracle requires the target metadata file to define a metric with NAME="Response" that contains a column with NAME="Status" and the default collection file must define a critical condition on the "Status" column that represents the target being up or down.

Shown in the example below, the Response metric, which monitors target availability, is required for all target types. The Load metric is used to determine a target's performance level.

The following example shows the "Response" metric definition for a Network Appliance Filer target type.

Example 2-3 Response Metric

<Metric NAME="Response" TYPE="TABLE">     <Display>       <Label NLSID="netapp_filer_resp">Response</Label>     </Display>     <TableDescriptor>       <ColumnDescriptor NAME="Status" TYPE="NUMBER">         <Display>           <Label NLSID="netapp_filer_resp_status">Status</Label>         </Display>       </ColumnDescriptor>     </TableDescriptor>     <QueryDescriptor FETCHLET_ID="Snmp">       <Property NAME="NAME" SCOPE="INSTANCE">NAME</Property>       <Property NAME="hostname" SCOPE="INSTANCE">AgentHost</Property>       <Property NAME="COMMUNITY" SCOPE="INSTANCE" OPTIONAL="TRUE">CommunityString</Property>       <Property NAME="TIMEOUT" SCOPE="INSTANCE" OPTIONAL="TRUE">Timeout</Property>       <Property NAME="PINGMODE" SCOPE="GLOBAL">TRUE</Property>       <Property NAME="OIDS" SCOPE="GLOBAL">1.3.6.1.4.1.789.1.1.3.0</Property>     </QueryDescriptor>   </Metric>

Because the "Response" metric is of type "TABLE", it requires a "TableDescriptor" and associated "ColumnDescriptor". Note that all levels of the metric, which includes table and column definitions, are given names, types, and display labels. As mentioned earlier, these elements and usage instructions can be found in the TargetMetadata.dtd file.

For each metric, you must also specify how to obtain the data to fill this structure. This is accomplished using fetchlets—mechanisms that take parameters, query a specified target, and then return some values from the target. Enterprise Manager provides a wide array of fetchlets to meet most data retrieval needs. See Chapter 8, "Fetchlets" and Chapter 5, "Management Using Web Services" for more information on fetchlets and available fetchlet types.

A fetchlet associated with the metric is declared through the "QueryDescriptor" tag. The following example shows the QueryDescriptor used for the Microsoft SQL Server Response metric.

Example 2-4 Query Descriptor Usage

<QueryDescriptor FETCHLET_ID="OSLineToken">    <Property NAME="emdRoot" SCOPE="SYSTEMGLOBAL">emdRoot</Property><Property NAME="command" SCOPE="GLOBAL">%emdRoot%/bin/nmefwmi</Property><Property NAME="ENVWBEM_WQL" SCOPE="GLOBAL">select name,pathname,processid,state from win32_service where pathname like '%sqlservr.exe%' or pathname like '%sqlagent%'</Property><Property NAME="ENVWBEM_WQL_COLUMN_ORDER" SCOPE="GLOBAL">name,pathname,processid,state</Property>      <Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>  <Property NAME="delimiter" SCOPE="GLOBAL">|</Property>    <Property NAME="NEED_CONDITION_CONTEXT" SCOPE="GLOBAL">TRUE</Property></QueryDescriptor>

The "FETCHLET_ID" label is used to specify which fetchlet to use for data retrieval. In the example above, the "Response" metric uses the "OSLineToken" fetchlet. What follows are the definition of required system parameters used by the fetchlet.

The "oraTclHome", "perlBin", and "scriptsDir" properties enable the correct bindings in the "command" property. The remaining properties are "OSLineToken" fetchlet input parameters. See Chapter 8, "Fetchlets" for information on parameters used by each fetchlet.

The "scope" property defines where the property value is to be obtained. The following scope options are available:

SCOPE="GLOBAL" Obtain the property value from other variables defined within the current target type metadata file. This includes constants, such as the "|" shown in the QueryDescriptor example.
SCOPE="INSTANCE" Obtain the property value from instance properties.
SCOPE="ENVxxx" Obtain the property value from an environment variable "xxx".
SCOPE="SYSTEMGLOBAL" Obtain the property value from the emd.properties file located in the $AGENT_HOME/sysman/config directory.
SCOPE="USER" Obtain the property value from the collector or user.

Instance Properties

The "InstanceProperties" descriptor is a required top-level specification that defines what properties an administrator must specify in the Enterprise Manager Grid Control console when adding a new target instance of this particular target type.

Although the InstanceProperties section can be defined at various locations within the target type metadata file, Oracle recommends defining this section at the very end of the file for consistency. Instance properties defined in the target type metadata file are resolved to values specified for these instance properties in the targets.xml file. Shown below are some of the instance properties for a Microsoft SQL Server target type.

Example 2-5 Instance Properties

<InstanceProperties>   <InstanceProperty NAME="ms_sqlserver_host" CREDENTIAL="FALSE" OPTIONAL="FALSE">              <Display>            <Label NLSID="ms_sqlserver_host">SQL Server host</Label>          </Display>   </InstanceProperty>  <InstanceProperty NAME="ms_sqlserver_servername" CREDENTIAL="FALSE" OPTIONAL="FALSE">                <Display>                    <Label NLSID="ms_sqlserver_servername">SQL Server name</Label>            </Display>   </InstanceProperty>  <InstanceProperty NAME="url" CREDENTIAL="FALSE" OPTIONAL="FALSE">            <Display>                    <Label NLSID="connectString_iprop">JDBC URL</Label>               </Display>   </InstanceProperty>
.
.
.
</InstanceProperties>

As an example, when an Oracle Database Instance target type is added to the Enterprise Manager framework, specific information about that target instance is added to the targets.xml file. In the example below, we can see that the InstanceProperty labels such as OracleHome, Port, SID defined in the Oracle Database Instance target type metadata file are resolved to instance-specific values in the targets.xml file.

Example 2-6 Target Instance Information for an Oracle Database

<Target TYPE="oracle_database" NAME="emrep.us.oracle.com">
        <Property NAME="OracleHome" VALUE="/scratch/OracleHomes/db10g"/>
        <Property NAME="UserName" VALUE="f8a6d72528517730" ENCRYPTED="TRUE"/>
        <Property NAME="MachineName" VALUE="stacb11.us.oracle.com"/>
        <Property NAME="Port" VALUE="1521"/>
        <Property NAME="SID" VALUE="emrep"/>
        <Property NAME="ServiceName" VALUE="emrep.us.oracle.com"/>
        <Property NAME="password" VALUE="7536910dcf78eaad" ENCRYPTED="TRUE"/>
</Target>

Validate your new target type definitions.

It is always a good idea to test your new target type definitions using the metric browser. The metric browser is a development utility that is an integral part of the Oracle Management Agent. As a subsystem of the Agent, it allows you to quickly access the metric values for targets monitored by the Agent without the overhead of a Management Repository or other components of the Enterprise Manager framework.

Activating the Metric Browser

To configure the Oracle Management Agent's metric browser for debugging metrics without the Enterprise Manager Grid Control console:

Uncomment the enableMetricBrowser line in the

$AGENT_HOME/sysman/config/emd.properties file:
```
#enableMetricBrowser=True
```
change to
```
enableMetricBrowser=True
```
Make sure the Oracle Management Agent is stopped.
```
emctl stop agent
```
Restart the Management Agent.
```
emctl start agent
```
Open the emd.properties file and check the EMD_URL line.

It will have the following format:
```
EMD_URL=http://<host>:<port>/emd/main
```

Adding a Target Instance to the targets.xml File

Before you can view your target metrics in the metric browser, you need to add an actual instance of your new target type to the targets.xml file without re synchronizing the Management Agent with the Management Service. To do this:

Create a new XML file containing the instance information for a specific target. The contents of this XML file must conform to the $AGENT_HOME/sysman/admin/dtds/TargetInstance.dtd file. The content for this file consists of the actual values specified for the instance properties you defined in the target type metadata file. For example, given the instance properties defined in a particular target metadata file, you create an XML file called "target2add.xml" that contains the following:
Example 2-7 target2add.xml File
```
<Target TYPE="oracle_listener" NAME="listener" VERSION="1.0">
```
```
<Property NAME="ListenerOraDir" VALUE="/myOH/oracle/network/admin"/>
        <Property NAME="LsnrName" VALUE="LISTENER"/>
        <Property NAME="Machine" VALUE="mymachine.us.oracle.com"/>
        <Property NAME="OracleHome" VALUE="/myOH/oracle"/>
        <Property NAME="Port" VALUE="15091"/>
```
```
</Target>
```
Use the command line instance installer to add the contents of the instance information file to the Management Agent's targets.xml file and reload the instance data. For the examples below, Management Agent home is located in /em/ and the instance information file is target2add.xml located in the /tmp/ directory.

Add the contents of your new target information file to the targets.xml file.
```
emctl config agent addtarget <file location> <Agent Home location>
```
Example:
```
emctl config agent addtarget /tmp/target2add.xml /em/
```
Verify that your target information was added correctly:
```
emctl config agent listtargets <emloc>
```
Example:
```
emctl config agent listtargets /em/
```
Reload the modified target information.This operation is required in order for the new target instance to appear in the metric browser.
```
emctl reload
```

Looking at Your Metrics

Once the target instance has been added to the targets.xml file and the new information has been reloaded, you can view available targets and metrics through the metric browser. Access the following URL using any web browser

http://<host>:<port>/emd/browser/main

To find the port number used by the Management Agent, open the emd.properties file and search for the EMD_URL line.

Creating a Default Collection File

Defining your target type metrics allows you to view the data belonging to that target instance at any time. However, you may also wish to collect the values of some of your metrics to analyze the variations over some period of time. You set up metric collection intervals for your target instances by defining a default collections file for the specific target type.

Note:

Full definitions and usage instructions for descriptor tags used in the collection file can be found in the $AGENT_HOME/sysman/admin/dtds/TargetCollection.dtd file.

Default Collection File

Located in $AGENT_HOME/sysman/admin/default_collection, the default collection file (XML) for a target type specifies the metrics to be collected and sent to the Management Repository, as well the frequency of these scheduled collections. Although you can use any name for a default collections file, it is recommended that you use a naming convention that makes it easy to associate the collection file with the corresponding target type metadata filename, such as using a filename identical to the target type metadata filename.

The following example is an excerpt from the Microsoft SQL Server default collections file.

Example 2-8 Microsoft SQL Server Default Collections File

<!DOCTYPE TargetCollection SYSTEM "../dtds/TargetCollection.dtd"[]>
<TargetCollection TYPE="microsoft_sqlserver_database">
        <CollectionItem NAME="Response">
                <Schedule>
                        <IntervalSchedule INTERVAL="5" TIME_UNIT="Min" />
                </Schedule>
                <Condition COLUMN_NAME="Status" CRITICAL="Running" OPERATOR="NE" />
        </CollectionItem>
        
        <CollectionItem NAME="SQLServer" UPLOAD_ON_FETCH="TRUE" CONFIG="TRUE">
                <Schedule OFFSET_TYPE="INCREMENTAL">
                        <IntervalSchedule INTERVAL="5" TIME_UNIT="Min" />
                </Schedule>
                <MetricColl NAME="MSSQL_SQLServer" />
                <MetricColl NAME="MSSQL_RegistrySetting" />          
        </CollectionItem>
.
.
.
<!-- Buffer cache hit ratio that is lower than 90% triggers warning and 80%
 triggers alert -->
<!-- Cache hit ratio that is lower than 80% triggers warning and 70% triggers
 alert -->
        <CollectionItem NAME="MSSQL_MemoryStatistics">
                <Schedule>
                        <IntervalSchedule INTERVAL="10" TIME_UNIT="Min" />
                </Schedule>
                <Condition COLUMN_NAME="buffer_cache_hit_ratio" WARNING="90" CRITIAL="80"  OPERATOR="LE" />
                <Condition COLUMN_NAME="cache_hit_ratio" WARNING="80" CRITIAL="70" OPERATOR="LE" />
        </CollectionItem>
        
        <CollectionItem NAME="MSSQL_Alert">
                <Schedule>
                        <IntervalSchedule INTERVAL="20" TIME_UNIT="Min" />
                </Schedule>
        </CollectionItem>
        
        <CollectionItem NAME="MSSQL_LastDatabaseBackup">
                <Schedule>
                        <IntervalSchedule INTERVAL="10" TIME_UNIT="Min" />
                </Schedule>
        </CollectionItem>
        
</TargetCollection>

For every target instance, the data collection intervals for the four metrics would be as follows:

Response: Collected every 5 minutes.
Load: Collected every 15 minutes.
memPool: Collected every 15 minutes.
Interfaces: Collected every 15 minutes.

If the threshold is not set in the collection file, administrators will not be able to edit/add the column threshold value from the Enterprise Manager console at a later point. To allow an administrator to change a threshold that does not have a default value, you can add a "NotDefined" entry for a specific threshold. For example:

<Condition COLUMN_NAME="db_session_osuser" CRITICAL="NotDefined"/>

Target Instance-Specific Collection Schedules

Under certain circumstances, you may not want to have all target instances use the same collection schedule. To specify that different instances of a target type have different collection schedules, you can add additional collections files (for specific target instances) to $AGENT_HOME/sysman/emd/collections.

The following example shows a situation where we want two specific target instances ("Simple Server Alpha" and "Simple Server Beta") to have different "Response" and "Load" collection schedules. The two collection files to be added to the collections directory would contain the following:

Example 2-9 Default Collection File for Simple Server Alpha

<TargetCollection NAME="Simple Server Alpha" TYPE="simple_server">
    <CollectionItem NAME="Response">
        <Schedule>
            <IntervalSchedule INTERVAL="10" TIME_UNIT="Min"/>
        </Schedule>
    </CollectionItem>
</TargetCollection>

Example 2-10 Default Collection File for Simple Server Beta

<TargetCollection NAME="Simple Server Beta" TYPE="simple_server">
    <CollectionItem NAME="Load">
        <Schedule>
            <IntervalSchedule INTERVAL="30" TIME_UNIT="Min"/>
        </Schedule>
    </CollectionItem>
</TargetCollection>

Here we are collecting results from Simple Server Alpha's "Response" every 10 minutes and Simple Server Beta's "Load" every 30 minutes.

Adding SYSTEM Reports (Optional)

Developing a Management Plug-in allows you to add new SYSTEM reports that are associated with the target type(s) defined by your Management Plug-in. SYSTEM reports cannot be edited or deleted from the Enterprise Manager console. All out-of-box reports supplied with Information Publisher are SYSTEM reports.

To add report definitions to your Management Plug-in, you simply create a report definition file for inclusion with the plug-in. A report definition file consists of a conventional PL/SQL block that specifies pertinent information to extract from the Management Repository and the report elements used to format and display that data. You may define multiple reports for a given target type. For more information on the Information Publisher PL/SQL API and creating a plug-in report definition file, see Chapter 4, "Adding Reports".

Adding Related Links to Target Home Pages

If reports are defined as part of a Management Plug-in, and at least one of the reports is registered to be shown in the context of the target default home page (it is registered using the Òadd_reportÓ PL*SQL function) then one or more related links may be added to the target default humped using the process described in this section.

Related Links are defined as dynamic instance properties in the target metadata file using the ÒDynamicPropertiesÓ tag with the following parameters: :

NAME=Ó<any name>Ó

PROP_LIST=ÓRelatedLink_Name_#;RelatedLink_Dest_#[;...]Ó

Where # can be any positive integer (Example: 1, 2, or 3)
PROP_LIST must be EXACTLY in the format specified here (including bumpy case). Otherwise, the related links will not show up on the target default home page.

Also, a ÒQueryDescriptorÓ tag block that retrieves the number of ÒName/DestÓ pairs listed in PROP_LIST is required. The ÒRelatedLink_Name_#Ó appears as the hyperlinked text. The ÒRelatedLink_Dest_#Ó is the link destination (URL or Javascript).

Example 2-11 is an excerpt from a target metadata file that contains a ÒDynamicPropertiesÓ block defining three related links that will appear on the default target home page.

Example 2-11 Related Links

<InstanceProperty NAME="EMPLOYEE_ID" CREDENTIAL="FALSE" OPTIONAL="FALSE">
  <Display>
        <Label NLSID="EMPLOYEE_ID_iprop">Employee ID</Label>
  </Display>
</InstanceProperty>
  <DynamicProperties NAME="Links" PROP_LIST="RelatedLink_Name_1;RelatedLink_Dest_1;RelatedLink_Name_2;RelatedLink_Dest_2;RelatedLink_Name_3;RelatedLink_Dest_3" FORMAT="ROW">
    <QueryDescriptor FETCHLET_ID="OSLineToken">
      <Property NAME="id" SCOPE="INSTANCE">EMPLOYEE_ID</Property>
      <Property NAME="command" SCOPE="GLOBAL">
          %perlBin%/perl %scriptsDir%/emx/oracle/getLinks.pl %id%
      </Property>
      <Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>
      <Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
    </QueryDescriptor>
  </DynamicProperties>
</InstanceProperties>

Note that in Example 2-11 the Perl script ÒgetLinks.plÓ is used to return the three links. The content of this script is shown in Example 2-12.

Example 2-12 Script getLinks.pl

my $id   = $ARGV[0];
 
my $name1 = "Employee: MY-PC";
my $link1 = "javascript:void window.open('http://my-pc.us.oracle.com', 'aria', 'resizable=1,menubar=1,toolbar=1,titlebar=1,status=1,scrollbars=1')";
my $name2 = "Employee: Hierarchy";
my $link2 = "javascript:void window.open('http://employee.us.oracle.com:7777/pls/oracle/f?p=8000:3:7200626882230853285::NO::PERSON_ID:$id', 'employee', 'resizable=1,menubar=1,toolbar=1,titlebar=1,status=1,scrollbars=1')";
my $name3 = "OTN";
my $link3 = "javascript:void window.open('http://otn.oracle.com', 'otn', 'resizable=1,menubar=1,toolbar=1,titlebar=1,status=1,scrollbars=1')";
 
print "em_result=$name1|$link1|$name2|$link2|$name3|$link3\n";

Because "getLinks.pl" is a support script, you add it to the Management Plug-in as a separate file using the EM CLI "add_mp_to_mpa" verb with the argument:

–file=ÓMONITORING_SCRIPT:<path_to>/getLinks.plÓ

Be very careful with the ÒjavascriptÓ syntax you use. Only some of the syntax is common to the popular browsers. For example, the second argument to Òwindow.openÓ is a window name used for internal reference to the window and it must not contain any spaces.

Additional Scripts and Binaries

In addition to the target metadata, collection, and report definition files, you may also include specialized scripts and/or binary files that are used to include obtain status or metric data from your custom targets. An example is the Perl script "getLinks.pl" mentioned in the previous section.

Ensuring Accurate XML

Successfully creating target type metadata and collection files requires valid XML code. To assist with writing valid XML, Enterprise Manager provides ILINT, a development tool you can use to validate the XML used to define your code as you develop your Management Plug-in. For more information on ILINT, see Chapter 3, "Validating XML".

Development Guidelines

When developing target type definition files for new Management Plug-ins, special consideration must be paid to the way in which you want a particular target type to be monitored. How a target type is monitored can greatly affect Enterprise Manger performance. General guidelines for defining target metadata and collections should be followed in order to optimize system performance.

Guidelines for Defining Target Metadata

Metadata is data about data. Generically, the term refers to any data used to aid in the identification, description and location of a network entity. Target metadata for an Enterprise Manager target consists of the metrics a user wants to expose and the methods used to compute those metrics.

Metadata Version

Whenever the target metadata changes, the metadata version (meta_ver) should be incremented.

Real-Time Only Metrics

Performance metrics can be classified into metrics that need to be computed to track performance trends and others that are more useful to drill down to get the details at a particular point in time. Real-time only metrics include those that need contextual information to return detailed information about a particular subset of the system, e.g., a specific tablespace to diagnose further.

Choice of Key Columns

A key column in a metric is used in the management repository to trend performance data on an axis, e.g., the tablespace usage per database tablespace. An inappropriately chosen key column can result in too much collected data within the management repository. For instance, using the process ID in a Processes metric to upload to the repository.

You can have no key columns, but the query descriptor must return a single row.

Transient Columns

In some cases, metric columns can be used to compute the values of other more interesting metric columns. In the cases where the original columns are not interesting for trending, these can be marked transient so that they are not uploaded to the repository and waste space.

Metrics and Microsoft Windows

When creating metrics for custom targets, it is important to take into account the cost (CPU usage) of creating additional operating system (OS) processes. This is especially true for systems running Microsoft Windows where process creation is much more CPU intensive compared to UNIX-based systems such as Linux or Solaris. The percentage CPU utilization increases linearly with creation of child processes. To minimize process creation, avoid executing OS programs or commands from metric collection scripts. For example, when writing Perl scripts, avoid using the system function or backticks (``) to execute an OS command.

Target Properties (Static Versus Dynamic)

Target properties are named values that can be used for computing the metrics of the target, or for display in the home page of the target. The list of target properties is specified in the metadata to allow data driven user interfaces to register targets, and for the Oracle Management Agent to validate that a target instance is complete.

Static Instance Properties: These are properties whose values need to be specified for a target in the targets.xml entry for the target. An instance property can be marked optional if the target declaration is considered complete even without the specification of the property. The metadata specification of a target property can also provide a default value for use in a configuration user interface.
Dynamic Instance Properties: The Oracle Management Agent also allows for target instance properties to be "computed". Such properties are computed using a QueryDescriptor very similar to the ones used in metrics.

Use of dynamic properties reduces the work involved in configuring a target by allowing certain properties to be computed rather than requiring the user to correctly specify their values (for example, the "Version" property of a database can be reliably computed given addressing information).

The Oracle Management Agent allows for the fact that the target needs to be up for the successful computation of these dynamic properties by recomputing the properties each time a target bounce is detected (each time the target status changes to "Up").

Metrics

The metric concept, as it pertains to the Oracle Management Agent, can be used to denote configuration and performance information.

Configuration Metrics: Configuration metrics collect data similar to target properties that denote the configuration of the target. This information is periodically refreshed and can be used to track changes in the setup of a target. The collection interval on such metrics is typically on the order of about 24 hours.
Performance Metrics: Performance metrics are used to track the responsiveness of a target. These metrics are typically collected more often than configuration metrics though the interval of some performance metrics may vary widely from those of others. Also, performance metrics usually ship with thresholds that are the basis of performance alerts for the target.

A required metric for all targets is the "Response" metric consisting of a "Status" column with a condition on it. This metric is used to track the availability of the target.

Metric Naming Conventions

The conventions used in naming your metrics are extremely important because many areas of the Enterprise Manager user-interface are data-driven. For example, actual metric column labels and key values can be part of the page title, instruction text, or column headings. Specifically, these elements would appear on the Metric Details page, Edit Metric Threshold page, Notification Rules page, and other pages of the Enterprise Manager user-interface. For this reason, Oracle recommends the following metric naming conventions.

All metric column names (labels) must be unique within a given target type and version, and easily understood by the user (metric units used as needed).

Example: Tablespace Usage (%)
All metric column names (labels) should be self-explanatory without dependence on the metric name.

Example: Table Space Used (%)
Key Column names should be self-explanatory. Key Column names are used when specifying metric thresholds or setting notifications. The following format should be used: all<key value name> objects

Example: all (tablespace) objects
Short names (up to 20 characters) associated with the metric column should be both clear and translatable.
Across target versions, the same columns should use the same labels. This ensures columns, such as metric columns and short names, have the same NLS IDs across different target versions.

Guidelines for Defining Collections

Collections are the mechanism by which the Oracle Management Agent periodically computes the metrics of a target and uploads the data to the Management Repository. The most important thing to keep in mind when creating the collections for a target type is to avoid overburdening the Management Repository with excess data. In a large enterprise with hundreds of Oracle Management Agents and thousands of targets, the key to scalability is to limit the amount of data collected about a target that is uploaded to the repository. This is especially important since raw data is maintained for 24 hours - rollup benefits only accrue beyond that point.

Alert Message Guidelines

Alert messages tell the user when something is wrong. These messages should also assist the user in solving the problem. We recommend following these content guidelines when writing alert messages:

Alert messages should be meaningful. Avoid using terse, ambiguous messages unless the message is only applicable to the metric.
Target down messages should, in addition to indicating that the target is down, include information indicating possible reasons why the target may be down.
Error codes/messages should be included whenever possible.
When appropriate, include information telling the user how to resolve or diagnose the problem.

Metric Evaluation Order

It is important to pay attention to metric evaluation order so as to avoid metric collection failures. For example, the Response metric should be evaluated first in order to prevent a collection failure when a target is down. The Oracle Management Agent will evaluate metrics based on the order they are listed in the collection XML file.

Note:

Programmatic logic of the Oracle Management Agent distributes the metric evaluations so that each evaluation is separated by approximately 10 seconds.

Collection Frequency

In general, there is almost never a good reason to collect information at intervals smaller than 5 minutes. In the rare case where data variations occur at a smaller granularity and administrators need to be notified sooner, the Oracle Management Agent provides the capability to use a small collection interval to compute the metrics and threshold information while still only uploading data once in every n computation cycles.

Controlling Number of Rows

Some metrics can result in the creation of a large number of rows in a Management Repository table. In some cases, only a subset of these rows may need to be uploaded to the repository. The Oracle Management Agent allows the specification of filter conditions that can be used to find rows to skip uploading. Also, a "limit_to" clause can be used on metrics that return sorted metric data to upload only the first n rows to the repository.

Creating a Management Plug-In Archive

Once you have created the Management Plug-in files, the next step is to create a Management Plug-in Archive (MPA). The MPA plays an important role at various stages of the Management Plug-in lifecycle. It serves the following functions:

As a transport mechanism between your development environment and the Enterprise Manager framework.
As a transport mechanism between different Enterprise Manager installations.
As a container for the Management Plug-in. A MPA may contain multiple Management Plug-ins.

A Management Plug-in is created by adding the files previously discussed to an MPA using the Enterprise Manager Command Line Interface (EM CLI). Each call to the EM CLI adds another unique Management Plug-in to the MPA. For each Management Plug-in, the EM CLI allows you to specify a base version of the Management Agent that the plug-in is expected to work against and a base version that the Oracle Management Service must be for the plug-in to be imported into the Management Repository. To create a MPA, perform the following

Open a terminal window on a machine where the EM CLI client is installed.
At the command prompt issue the add_mp_to_mpa verb. The following example shows the verb parameters that must be supplied. For more information about the add_mp_to_mpa verb, see the command line help.

Example 2-13 Using the EM CLI to Create a Management Plug-in Archive

emcli add_mp_to_mpa
          -mpa="/my_dir/my_new_type.jar"
          -mp_version="2.0"
          -ttd="/my_dir/ttd/new_type.xml"
          -dc="/my_dir/dc/new_type.xml"
          -file="REPORT_DEFINITION:/my_dir/report1.sql
          -file="REPORT_DEFINITION:/my_dir/report2.sql
          -file="MONITORING_SCRIPT:/my_dir/script1.pl
          -file="MONITORING_SCRIPT:/my_dir/script2.pl
          -file="MONITORING_BINARY:/my_dir/bin1
          -func_desc="Management Plug-in to define target type new_type"

Briefly, the verb options are:

mpa

The name of the Management Plug-in Archive where the Management Plug-in is to be added.
mp_version

The version of the Management Plug-in to be created. The Mangagement Plug-in version should be incremented whenever any of the files in the management Plug-in are changed.
tdd

The explicit path of the target type metadata file.
dc

The explicit path of the default collection file.
oms_version

The minimum OMS version that is compatible with this Management Plug-in.
file

The type and path of the other Management Plug-in files to be added. The following types are supported:
- MONITORING_BINARY
- POLICY_DEPLOY
- POLICY_UNDEPLOY
- MONITORING_SCRIPT
- REPORT_DEFINITION
func_desc

The functional description for the Management Plug-in. This description appears in the Enterprise Manager console once the plug-in has been imported.

Adding a Target Instance

After a Management Plug-in has been deployed to an Agent, you are ready to add new target instances of the type defined by your Management Plug-in. When you add a target instance, monitoring and administrative functionality is automatically extended to that target. To add a target instance:

From the Monitored Targets section of the Management Agent home page, choose the target type defined by your plug-in from the Add drop-down menu and click Go. The Add target page appears.
Enter the requisite target properties and click OK. The newly added target appears in the Agent's Monitored Targets list.

A default target home page is provided that supplies requisite information about the target as shown in Figure 2-1.

Viewing Results

From a default target home page, a user can drill down to specific metrics that have been defined for the target type.

The following figure shows a target home page for a Microsoft SQL Server instance.

Figure 2-1 Microsoft Commerce Server Target Home Page

Description of "Figure 2-1 Microsoft Commerce Server Target Home Page"

Because report definitions were included with this Management Plug-in, an additional Reports subtab appears with the home page. As shown in the next figure, adding reports can greatly improve the monitoring capabilities of your Management Plug-in. For more information about creating Management Plug-in report definitions, see Chapter 4, "Adding Reports".

Figure 2-2 Microsoft SQL Server Reports Subtab

Description of "Figure 2-2 Microsoft SQL Server Reports Subtab"

Troubleshooting Management Plug-ins

On occasion, you may encounter errors when when managing Management Plug-ins. The most common problems are as follows:

Deployment fails. "Agent Unreachable"

Ensure that the Management Agent is up and running.

Log in as "root" and execute the root.sh script at the Management Agent.
Undeploy fails. "Agent Unreachable"

Ensure that the Management Agent is up and running.
Unable to delete the Management Plug-in.

The Management Plug-in must be undeployed from ALL Agents to which it was previously deployed. Note that this includes any Agents that are currently down.
Reports do not show any data.

Depending on the collection interval settings, it may take time for the Agent to collect the metric data for the target. Management views used by the reports can also determine when data is available, as would be the case if queries against the Management Repository are performed against rolled up data.