3 Creating Target Metadata Files

This chapter contains the following sections:

Introduction to Creating Target Metadata Files
Overview of Target Definition Files
Creating the Target Type Metadata File
Defining Metrics to Collect from the Target
Creating the Default Collection File
Guidelines for Creating Target Metadata
Testing Your Target Type Definitions
Validating Your Metadata XML
Troubleshooting the Target Creation Process

3.1 Introduction to Creating Target Metadata Files

As a plug-in developer, you are responsible for the following steps within the target metadata files creation process:

Create the target definition file.

The target type metadata file tells the Management Agent what data to retrieve and how to obtain that data for this particular target type.

For more information, see Section 3.3, "Creating the Target Type Metadata File".
Define metrics to collect from the target.

A metric refers to a specific piece of data collected from the target. A set of related metrics collectively comprise a metric group.

For more information, see Section 3.4, "Defining Metrics to Collect from the Target".
Define target configuration data to collect.

You can collect configuration data for a target and save it in the Management Repository as a snapshot representing the target's configuration at a specific point in time. Each configuration snapshot is associated with a specific target instance.

For more information, see Chapter 6, "Collecting Target Configuration Data".
Create the default collection file.

The default collection file defines the metric data to be collected from targets and written to the Management Repository along with information such as the collection frequency.

For more information, see Section 3.5, "Creating the Default Collection File".
Package the various definition files in the plug-in staging directory (plugin_stage):
- Target type metadata file
  - plugin_stage/oms/metadata/targetType/target_type.xml
  - plugin_stage/agent/metadata/target_type.xml
    
    Note:
    An identical copy of this file must be placed in both the /oms and /agent directories.
- Default collection file
  - plugin_stage/oms/metadata/default_collection/target_type.xml
  - plugin_stage/agent/default_collection/target_type.xml
    
    Note:
    An identical copy of this file must be placed in both the /oms and /agent directories.
- Configuration metadata file
  
  plugin_stage/oms/metadata/snapshotlive/target-type_ecmdef.xml
For more information, see Chapter 13, "Validating, Packaging, and Deploying the Plug-in".

3.2 Overview of Target Definition Files

Two XML metadata files are required to define the target type that your plug-in will enable Enterprise Manager Cloud Control to monitor and manage:

Target type metadata file

The definition of a target type primarily consists of the metrics you want the Management Agent to collect for the target. The file contains a list of all metrics that will be collected for the target type, along with specifics on how to compute each metric.

For more information, see Section 3.3, "Creating the Target Type Metadata File".
Default collection file

This file defines the interval at which metric data will be collected or received from the target. It also specifies alert thresholds and optional corresponding warning messages for each metric. Cloud Control users can override the default collection intervals, but the default values must be provided in this file.

For more information, see Section 3.5, "Creating the Default Collection File".

This chapter also describes the metadata definitions required to collect configuration data for plug-in targets. This is an advanced feature but can be useful for many plug-ins. For more information, see Section 6.2, "About the Configuration Definition Files".

The following sections provide the summary of creating the target type and default collection metadata files, as well as an overview of target configuration data collection.

3.3 Creating the Target Type Metadata File

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.

At the highest definition level, the target type metadata file is composed of four key XML elements as described in Table 3-1.

Table 3-1 Key Elements of the Target Type Metadata File

Element	Description
`TargetMetadata`	Specifies information about the plug-in, such as name and version.
`Metric`	Defines a metric group, which in turn contains one or more metrics that each define a specific piece of data collected from the target.
`InstanceProperties`	Defines properties that are populated when a target instance is created.
`CredentialTypes/CredentialSets`	Specifies credentials required to by the plug-in authenticate with a target instance.

Enterprise Manager ships with predefined target type metadata files that cover the most common target types. In situations where the predefined target metadata files do not fit the types of targets you want to monitor, you can either:

Define a new target type by creating a target type metadata file
Use one of the predefined metadata files as a template for defining a new target type, and then repackage the files as a new plug-in

This section briefly introduces the structure of the target type metadata file. A complete example of a target type metadata file is provided with the EDK:

edk/samples/plugins/SampleHost/oms/metadata/targetType/demo_hostsample.xml

In the preceding directory path, edk represents the directory where you expanded the EDK archive. For information about the EDK archive, see Section 1.2, "About the Extensibility Development Kit (EDK)".

For additional information about creating target type metadata files, Section 3.6, "Guidelines for Creating Target Metadata".

3.3.1 Creating a Basic Target Type Metadata File

Example 3-1 shows the minimum required information that a target type file must contain.

Example 3-1 Target Type File

<TargetMetadata META_VER="2.0" TYPE="demo_hostsample"> 
  <Display>
    <Label NLSID="hs_displayname">Demo Plugin Sample Host</Label>
  </Display>
  <Metric NAME="Response" TYPE="TABLE">
    <Display>
      <Label NLSID="hs_response_displayname">Response</Label>
    </Display>
    <TableDescriptor>
      <ColumnDescriptor NAME="Status" TYPE="NUMBER" IS_KEY="FALSE">
        <Display>
          <Label NLSID="hs_response_status">Status (up/down)</Label>
        </Display>
      </ColumnDescriptor>
    </TableDescriptor>
    <QueryDescriptor FETCHLET_ID="OSLineToken">
      <Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property>
      <Property NAME="fake" SCOPE="INSTANCE"
             OPTIONAL="TRUE">USE_FAKE_DATA</Property>
      <Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>
      <Property NAME="script" SCOPE="GLOBAL">%scriptsDir%/emx/demo_hostsample/datacollector.pl --collect Response --fake %fake%</Property>
      <Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>
      <Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
    </QueryDescriptor>
  </Metric>
  <InstanceProperties>
    <InstanceProperty NAME="SAMPLE_DATA" CREDENTIAL="FALSE" OPTIONAL="TRUE">
      <Display>
        <Label NLSID="EMPLOYEE_ID_iprop">Employee ID</Label>
      </Display>
    </InstanceProperty>
 </InstanceProperties>
</TargetMetadata>

The following sections provide information about the XML definitions shown in Example 3-1.

3.3.2 Naming the 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 vendorID_productID_PluginTag.

For example:

acme_demo_targetType.xml

3.3.3 Defining the Target Type Metadata

The first lines after the header of the target definition file identify the target type. The following excerpt defines the metadata version (META_VER="2.0") and target type (TYPE="acme_demo_targetType").

<TargetMetadata META_VER="2.0" TYPE="acme_demo_targetType">

Metadata versioning allows different versions of the same target type metadata to exist concurrently within the managed environment, although only one metadata version is allowed per Management Agent. You should update the metadata version each time you update the target metadata file.

3.3.4 Defining Target Credentials

In most cases, the plug-in will be required to authenticate with each target instance that it will collect data for, or run jobs against. Credential types and credential sets needed to enable authentication are defined in the CredentialInfo element within the target type metadata file.

For more information, see Chapter 14, "Defining Credentials".

Credentials information for the target includes and defines the credentials fields (referred to as columns) and the credentials sets specific to the target type. Enterprise Manager's security framework provides facilities for managing these credentials and using them when performing various management functions.

3.3.5 Defining Type Properties

The extensibility framework uses type properties to internally categorize the target type for framework processing. They are not visible to the end user. Corresponding subsystems use the type properties to enable features for the target type or to perform appropriate validation checks.

The value set at the type property level applies to all targets of that type and across all metaversions, unlike instance properties which only apply to a specific target.

The following example specifies that the target type is a system class of target. The extensibility framework uses this setting to display the target on all system pages.

<TypeProperties>
   <TypeProperty PROPERTY_NAME="is_system" PROPERTY_VALUE="1"/>
</TypeProperties>

Table 3-2 provides a description of the available type properties.

Table 3-2 Type Properties

Property Name	Description
`is_system`	Specifies the type as modelling a system type. You must set this value for all system types. `is_cluster`: Specifies the type as modelling a cluster. Clusters are subsets of systems. `is_end_user`: Set for systems constructed from user-chosen entities; these are subsets of systems. Note: The property value is always set to 1 for all the `is_name` properties.
`is_service`	Specifies the type as modelling a service. Note: The property value is always set to 1 for all the `is_name` properties.
`is_aggregate`	Enterprise Manager sets this value automatically. Do not modify.
`is_group`	Do not use
`is_composite`	Do not use
`is_install`	Set this value for an install home manageable entity (for example, Oracle home)
`is_existence`	Set this value for a discovered entity with an existence-only state, that is, an entity that is discovered but cannot be managed by Oracle yet. Possible value: 1: Indicates a discovered entity with an existence-only state Note: When the entity becomes a managed entity by Oracle, you must remove this entry from the target type metadata file and register the target type again.
`priv_propagation_mode`	This property is used for privilege propagation and specifies the privilege propagation mode. Possible values: 0: No privilege propagation 1: Privilege propagation at instance level 2: All targets are privilege propagating
`disallow_redundancy_group`	Used by the redundancy group feature to disable redundancy groups for certain target types (which have disallow redundancy group set). Specifies whether redundancy group can contain this type as a member Possible value: 1: Do not allow redundancy
`member_target_type`	Used by the redundancy group feature to lock the target type to the specified member_target_type.
`TargetVersion`	Specifies the name of the instance or dynamic property that represents the target version for the target type (for all target pages and plug-in certification)

Example 3-2 Defining Type Properties

<TargetMetadata META_VER="1.1" TYPE="oracle_dbsys" CATEGORY_PROPERTIES="" RESOURCE_BUNDLE_PACKAGE="oracle.sysman.db.rsc">
  <Display>
    <Label NLSID="oracle_dbsys_nlsid">Database System</Label>
  </Display>

  <TypeProperties>
    <TypeProperty PROPERTY_NAME="is_system" PROPERTY_VALUE="1"/>
    <TypeProperty PROPERTY_NAME="priv_propagation_mode" PROPERTY_VALUE="2"/>
  </TypeProperties>

  <MonitoringMode MEDIATOR="Repository"/>
</TargetMetadata>

3.3.6 Defining Instance Properties

Instance properties are populated when a target instance is created. The InstanceProperties descriptor within the target type metadata file defines what properties an administrator must specify in the Enterprise Manager Cloud 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 target type metadata file.

Target instance 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 instance 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.

3.3.6.1 Static Instance Properties

Instance properties are populated when a target instance is created. In this example, the property is required (OPTIONAL="FALSE) and it is a credential property.

<InstanceProperties>
 <InstanceProperty NAME="password" OPTIONAL="FALSE" CREDENTIAL="TRUE">
  <Display>
   <Label NLSID="USER_PASSWORD">User Password</Label>
  </Display>
 </InstanceProperty>
</InstanceProperties>

3.3.6.2 Dynamic Instance Properties

The values for dynamic instance properties are passed back by the Management Agent collecting data from the target instance. They are typically used within a QueryDescriptor to define properties passed to the fetchlet responsible for metric collection. For more information about the QueryDescriptor element, see Table 3-3. For more information about fetchlets, see Chapter 20, "Using Fetchlets".

The properties in the following example are described in Section 3.4.2, "Defining the Basic Response Metric Group".

<InstanceProperties>
 <DynamicProperties NAME="AruidInfo" FORMAT="ROW" OPT_PROP_LIST="ARUID">
  <QueryDescriptor FETCHLET_ID="OSLineToken">
   <Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property>
   <Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>
   <Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl</Property>
   <Property NAME="script" SCOPE="GLOBAL">%scriptsDir%/hostaruid.pl</Property>
   <Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>
   <Property NAME="delimiter" SCOPE="GLOBAL">|</Property>  </QueryDescriptor>
 </DynamicProperties>
</InstanceProperties>

Using 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).

Dynamic properties are computed in the order that they are defined in the XML file so that later dynamic properties can use values from earlier dynamic properties in the XML file if required.

The Management Agent allows for the fact that the target must be up for the successful computation of these dynamic properties by recomputing the properties each time a target restart is detected; that is, each time the target status changes to Up.

Note:

Some properties can be computed without access to the target; therefore there is some support for computing dynamic properties when the target is down.

To compute a dynamic property when the target is down, include the following attribute:

COMPUTE_WHEN_DOWN="TRUE"

3.4 Defining Metrics to Collect from the Target

Metrics are at the core of Cloud Control's target monitoring capabilities. When we speak of Cloud Control's ability to monitor and manage various targets, what we are really talking about is its ability to collect, process, and display target metrics.

A metric refers to a specific piece of data collected from the target.

Note:

Existing metric definitions defined in target-type metadata files are still valid in this release.

Metrics can viewed as being of two basic types:

Pull metrics

In this model, the plug-in polls the target for metric data at the frequency specified in the collections file. This is the most common type of metric utilized by plug-ins.

A metric of this type requires the use of a fetchlet, a parametrized data access mechanism that takes arguments (for example, a script, a SQL statement, a target instance's properties) as input and returns formatted data.

Predefined fetchlets are provided by Oracle for use with plug-ins. For a list of available fetchlets and information about their usage, see Chapter 20, "Using Fetchlets".
Push metrics

In this model, the plug-in receives notifications that are sent asynchronously from the target, without being requested. This type of metric requires a receivelet, which enables the plug-in to receive such notifications. As with fetchlets, predefined receivelets are provided by Oracle. For information about using receivelets, see Chapter 19, "Using Receivelets".

3.4.1 Metric Definition Files

The target metadata must define each type of metric the plug-in will collect, how and when the metric data is to be collected, and what metric thresholds will trigger an incident to be raised within Cloud Control.

The metadata for metric groups and individual metrics is defined in two metadata files packaged with the plug-in:

The target type metadata file

The content of the target type metadata file actually consists primarily of metric definitions. The fetchlet or receivelet that a metric will use is defined in the QueryDescriptor element within the target-type metadata file.

For information about key metric definition elements, see Section 3.4.4, "Overview of Key Metric Metadata Elements".
The default collection metadata file

The frequency at which data is collected for each metric is defined in the default collection metadata file. Metric Alert event conditions for each metric and the messages to display for such alerts are also defined in this file.

For information about the default collection metadata file, see Section 3.5, "Creating the Default Collection File".

3.4.2 Defining the Basic Response Metric Group

As a matter of practice, Oracle recommends that you specify at least a single Response metric group that includes the following metrics for each target type:

A Status metric that indicates target availability (required for all target types)
A metric that reports target performance (optional but recommended)

The corresponding default collection file must define a critical condition on the Status metric that represents the target status as up or down. For more information, see Section 3.5.2, "Defining Basic Metric Collection".

Example 3-3 defines a Status metric. The return value of Status is as follows:

0: Target status is down
1: Target status is up

The process by which the metric data is collected is defined in the QueryDescriptor element. This descriptor specifies that the OSLineToken fetchlet invokes a Perl script (data_collector.pl) to collect the data. The Perl script returns a standard out (stdout) data stream containing the collected data to the fetchlet.

Each property passed to the OSLineToken fetchlet execution is specified in a Property tag within the QueryDescriptor element.

The OSLineToken fetchlet requires that a GLOBAL property called command be set to the command that is to be executed. Different tokens typically have specific required properties. For more information about the OSLineToken fetchlet, see Section 20.2, "OS Command Fetchlets".
When a plug-in is deployed to a Management Agent, any scripts or binaries associated that were packaged within the /agent/scripts directory in the plug-in archive are written to the following directory in the Management Agent, where AGENT_HOME is the Management Agent plug-in home directory and plugin_name is the name of the plug-in:
```
AGENT_HOME/plugins/plugin_name
```
The scriptsDir property is a token that defines this location.

Note:
In previous releases, the scripts bundled with the plug-in were copied to the scripts directory under the Management Agent. However, for this release, the scripts included in the plug-in are used directly.This changes the behavior of the scriptsDir property in the QueryDescriptor element. Previously, it referred to the directory under the Management Agent, but now it refers to the directory under the plug-in.If you want to refer to the scripts directory under the Management Agent, use the sdkScriptsDir property.
The script property specifies the script (data_collector.pl) to be run.

The EDK provides an example of this script:
```
edk/samples/plugins/HostSample/demo_hostsample/stage/agent/scripts/emx/demo_hostsample
```
The startsWith and delimiter properties specify the format of the STDOUT of the script executed. In this case, the script will return a single row that looks like this:

em_result="value for Load|value for Status"

Example 3-3 Response Metric

<Metric NAME="Response" TYPE="TABLE">
 <TableDescriptor>
  <ColumnDescriptor NAME="Status" TYPE="NUMBER" IS_KEY="FALSE">
   <Display>
    <Label NLSID="oracle_emrep_resp_status">Status</Label>
   </Display>
  </ColumnDescriptor>
 </TableDescriptor>
 <QueryDescriptor FETCHLET_ID="OSLineToken">
  <Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>
  <Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property
  <Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl</Property>
  <Property NAME="script" SCOPE="GLOBAL">%scriptsDir%/emrepresp.pl</Property>
  <Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>
  <Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
  <Property NAME="ENVEM_TARGET_NAME" SCOPE="INSTANCE">NAME</Property>
  <Property NAME="ENVEM_REPOS_USER" SCOPE="INSTANCE">UserName</Property>
  <Property NAME="ENVEM_REPOS_PWD" SCOPE="INSTANCE">password</Property>
  <Property NAME="ENVHOST" SCOPE="INSTANCE" OPTIONAL="TRUE">MachineName</Property>
  <Property NAME="ENVPORT" SCOPE="INSTANCE" OPTIONAL="TRUE">Port</Property>
  <Property NAME="ENVSID" SCOPE="INSTANCE" OPTIONAL="TRUE">SID</Property>
  <Property NAME="ENVCONNECTDESCRIPTOR" SCOPE="INSTANCE" OPTIONAL="TRUE">ConnectDescriptor</Property>
  <Property NAME="ENVEM_TARGET_ADDRESS" SCOPE="GLOBAL">
      (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=%ENVHOST%)(Port=%ENVPORT%))
      (CONNECT_DATA=(SID=%ENVSID%)))</Property>
 </QueryDescriptor>
</Metric>

For a description of these elements, see Section 3.4.4, "Overview of Key Metric Metadata Elements".

3.4.3 Defining Advanced Metrics

You can define much more complex metrics, such as metrics that collect CPU performance data or metrics for which values are computed from the values of other metrics. Examples of such advanced or complex metric definitions can be seen in the sample target type metadata file provided with the EDK:

edk/samples/plugins/HostSample/demo_hostsample/stage/oms/metadata/targetType/demo_hostsample.xml

Example 3-4 shows a metric group containing metrics that collect CPU performance data. As in the previous example, the QueryDescriptor element specifies that the OSLineToken fetchlet will invoke the data_collector.pl script to collect the data.

Example 3-4 Defining Advanced Metrics

<Metric NAME="CPUProcessesPerf" TYPE="TABLE">
 <Display>
  <Label NLSID="hs_cpuprocessesperf_displayname">Host Process CPU Performance
   Statistics</Label>
  </Display>
  <TableDescriptor>
   <ColumnDescriptor NAME="ProcPID" TYPE="NUMBER" IS_KEY="TRUE">
    <Display>
     <Label NLSID="hs_cpuprocessesperf_procpid">PID</Label>
    </Display>
   </ColumnDescriptor>
  <ColumnDescriptor NAME="ProcUser" TYPE="STRING" IS_KEY="FALSE">
   <Display>
    <Label NLSID="hs_cpuprocessesperf_procuser">User</Label>
   </Display>
  </ColumnDescriptor>
  <ColumnDescriptor NAME="ProcCPU" TYPE="NUMBER" IS_KEY="FALSE">
   <Display>
    <Label NLSID="hs_cpuprocessesperf_proccpu">CPU Usage (%)</Label>
   </Display>
  </ColumnDescriptor>
  <ColumnDescriptor NAME="ProcCmd" TYPE="STRING" IS_KEY="FALSE">
   <Display>
    <Label NLSID="hs_cpuprocessesperf_proccmd">Command</Label>
   </Display>
  </ColumnDescriptor>
 </TableDescriptor>
 <QueryDescriptor FETCHLET_ID="OSLineToken">
  <Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property>
  <Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>
  <Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl</Property>
  <Property NAME="script" SCOPE="GLOBAL">%scriptsDir%/emx/demo_hostsample/data_
            collector.pl</Property>
  <Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>
  <Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
 </QueryDescriptor>
</Metric>

Example 3-5 shows a test metric. The Management Agent can check some metrics to determine if a target has been specified correctly with valid instance properties. Setting the IS_TEST_METRIC attribute to "TRUE" provides a Test button when adding a target instance.

Example 3-5 Defining a Test Metric

<Metric NAME="Ping" TYPE="TABLE" IS_TEST_METRIC="TRUE" USAGE_TYPE="HIDDEN">
 <Display>
  <Label NLSID="label_metrics_ping">Ping Test</Label>
 </Display>
 <TableDescriptor>
  <ColumnDescriptor NAME="tcpIpPing" TYPE="NUMBER">
   <Display>
    <Label NLSID="test_ping">TCP Ping, Milliseconds</Label>
   </Display>
  </ColumnDescriptor>
 </TableDescriptor>
 <QueryDescriptor FETCHLET_ID="OSLineToken">
  <Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>
  <Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property>
  <Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl
  %sdkScriptsDir%/osresp.pl</Property>
  <Property NAME="ENVEM_TARGET_NAME" SCOPE="INSTANCE">hostName</Property>
  <Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>
  <Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
 </QueryDescriptor>
</Metric>

3.4.4 Overview of Key Metric Metadata Elements

Table 3-3 describes the key elements that define metrics. For additional information about defining metrics, see Section 3.6, "Guidelines for Creating Target Metadata".

Table 3-3 Key Elements Used to Define Metrics

Element	Description
`Metric`	Required. Defines a metric group containing one or more metrics, each defined in a `ColumnDescriptor`. The `Metric` element includes the following attributes: `NAME`: The name of the metric group, up to 64 characters long. `TYPE`: Valid values are "TABLE" or "RAW". Typically set to "TABLE", indicating tabular data. `IS_TEST_METRIC`: The Management Agent can check some metrics to determine if a target has been specified correctly with valid instance properties. This attribute marks this metric as one of the test metrics. By default, the value is set to "FALSE". Setting this value to "TRUE" provides a Test button when adding a target instance. `USAGE_TYPE`: The metric is not viewable and the Management Agent will not upload data collected by the metric to the Management Repository.
`TableDescriptor`	Required when the Metric `TYPE` attribute is set to "TABLE". It contains one or more ColumnDescriptor elements, each defining a metric to collect
`ColumnDescriptor`	Defines a single metric to be collected. It contains the following attributes: `NAME`: The name of the metric, up to 64 characters long. `TYPE`: Describes how the metric data will be stored in the Management Repository. The value is typically either "NUMBER" or "STRING". `IS_KEY`: Indicates if the metric is to be treated as a primary key column in the Management Repository. Values are "TRUE" or "FALSE" (default).
`QueryDescriptor`	Defines a command to run, which returns the set of data described in the `TableDescriptor`. The element contains one or more `Property` elements, each defining a property to pass in with the command invocation. Note: You can refer to earlier defined properties using the `%property_name%` format. For example: <Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property> <Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl</Property> The element includes a `FETCHLET_ID` attribute that identifies the fetchlet mechanism that will be used to process the request. Properties required for the fetchlet invocation are specified in one or more `Property` elements within the `QueryDescriptor`. The following are among the fetchlets commonly used by plug-in developers: `OS`: Executes the given operating system command or script and returns the command's output in a single cell table. `OSLines`: Similar to the fetchlet, but returns the output tokenized by lines. `OSLineToken`: Similar to the fetchlets, but the output is tokenized first by lines; each line is then tokenized by a given delimiter set. `HTTPDataLineToken`: Invokes an HTTP request to the specified URL. `SQL`: Executes the specified SQL script against the specified Oracle Database. `Snmp`: Invokes the specified SNMP call to the specified SNMP agent. `WBEM`: Invokes the specified WBEM call to the specified CIMOM object repository. For a complete list of available fetchlets and information about their usage, see Chapter 20, "Using Fetchlets". 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 Example 3-3. 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.
`ElementDescriptor`	Used to compute aggregation metrics. Specifies the execution plan for evaluating a metric. The Management Agent runs each statement of the plan, in the order it is defined, to produce a Metric Result. The Metric Result generated as result of the evaluation of the last statement of the execution plan will be returned.

3.5 Creating the Default Collection File

The default collection metadata file for a target type defines the following:

The metric data (including configuration collection metric data) to be collected from targets and written to the Management Repository
The frequency of at which this metric data is collected
Thresholds that, when exceeded, will cause a Metric Alert event to be raised
An optional message to display when a threshold is exceeded

Note:

Although you can use any name for a default collection file, Oracle recommends that you use a naming convention that makes it easy to associate the collection file with the corresponding target type metadata file name. For example, using the same file name as the target type metadata file.

For information about naming the target type metadata file, see Section 3.3.2, "Naming the Target Type Metadata File".

Note that the value of the TYPE attribute in the default collection metadata file must match the TYPE value defined in the target type metadata file to create an association between them.

As noted, you can also specify Metric Alert event conditions on each metric that will be raised as Incidents within Enterprise Manager Cloud Control. Such events are generated when a threshold specified in this file is exceeded. For example, you may want to raise a WARNING alert when CPU usage reaches 90% of capacity. You can also specify the message text to be displayed in Enterprise Manager Cloud Control when an alert event is triggered.

The EDK includes an example of a default collection file in the following location:

/samples/plugins/HostSample/stage/oms/metadata/default_collection/demo_hostsample.xml

For information about defining the elements in the default collection file, see Section 3.5.5, "Overview of Key Default Collection Metadata Elements" and Section 3.6, "Guidelines for Creating Target Metadata".

3.5.1 Grouping Similar Metrics For Collection

For efficiency, metrics are typically grouped together for collection, enabling certain metrics to be collected at the same time or same frequency. This is useful because it guarantees the order of execution of the metrics, which is important if some metrics rely on the results of other metrics.

Each group of metrics to be collected together is defined in a CollectionItem within the default collection file. The collection schedule for the group is defined in a Schedule element.

Each metric included in the group is in turn defined within a MetricColl element within the CollectionItem. (Note that if the CollectionItem contains just a single metric, like the Response metric example shown in Section 3.4.2, "Defining the Basic Response Metric Group", it is not necessary to specify the MetricColl tag.)

Note that the UPLOAD value for the CollectionItem is set to 6, meaning that every sixth collection of data will be written to the Management Repository. Because the IntervalSchedule specifies that data will be collected every 5 minutes, the data will be written to the Management Repository every 30 minutes - or every sixth data collection.

<TargetCollection>
...
 <CollectionItem NAME="Perf" UPLOAD="6">
  <Schedule>
   <IntervalSchedule INTERVAL="5" TIME_UNIT="Min"/>
  </Schedule>
  <MetricColl NAME="CPUProcessesPerf">
   ...
  </MetricColl>
  <MetricColl Name="MemoryPerf">
   ...
  </MetricColl>
 </CollectionItem>
...
</TargetCollection>

You should consider grouping metrics into a CollectionItem if:

The metrics are logically related, such as all metrics related to performance
The metrics should be collected at the same frequency, such as all metrics that should be collected every 5 minutes
The metrics should be collected at roughly the same time, such as metrics collected during non-peak times
You want to collect all of the metrics, or none of the metrics, at the same time

Note that if you have metrics that will be collected on demand, grouping them will improve performance and reduce the communications required by the Management Agent and Oracle Management Service to collect and return metric data from the target.

Ideally, you should avoid having too many independent or singleton collections, as changing the collection schedule for multiple independent metrics is a more cumbersome task. Grouping together unrelated metrics just to avoid having such singletons is not advisable either, as you will not have the ability to turn off collection of just a few metrics in the group without disabling the those metrics that you do need.

3.5.2 Defining Basic Metric Collection

The following represents the CollectionItem entry for the basic Response metric group, which includes the Status metric. It specifies that data for this metric should be collected every 5 minutes, which is the standard collection interval for this type of metric.

A condition has been set on the Status metric. For more information about alert conditions, see Section 3.5, "Creating the Default Collection File" and Table 3-4.

Note that because the CollectionItem contains just one metric (Status), it is not necessary to include a MetricColl tag for the single metric.

<TargetCollection META_VER="2.0" TYPE="acme_demo_targetType">
 ...
 <CollectionItem NAME="Response">
  <Schedule>
   <IntervalSchedule INTERVAL="5" TIME_UNIT="Min"/>
  </Schedule>
  <Condition COLUMN_NAME="Status" CRITICAL="0" OPERATOR="EQ" CLEAR_MESSAGE_NLSID="Response_Status_clearalertmessage"
  MESSAGE="Failed to connect to database instance: %oraerr%."MESSAGE_NLSID="Response_Status_alertmessage"/>
 </CollectionItem>
...
</TargetCollection>

3.5.3 Defining Advanced Metric Collection

The next example illustrates collection of a more advanced metric that raises a metric alert when a specified WARNING and/or CRITICAL thresholds are exceeded. These thresholds, and the message to send to Cloud Control when they are exceeded, are defined in the Condition element.

The data for each metric is specified in a MetricColl element within a CollectionItem, as shown in Example 3-6. For a description of the elements in this example, see Table 3-4.

Example 3-6 Defining Advanced Metric Collection

<TargetCollection>
...
 <CollectionItem NAME="Perf" UPLOAD="6">
  <Schedule>
   <IntervalSchedule INTERVAL="5" TIME_UNIT="Min"/>
  </Schedule>
  <MetricColl NAME="CPUProcessesPerf">
   <Condition COLUMN_NAME="ProcCPU" WARNING="75" CRITICAL="90" OPERATOR="GE"
              OCCURRENCES="2"
              MESSAGE="The value for %columnName% is %value%%%, which is above the
              critical (%critical_threshold%%%) or warning (%warning_threshold%%%)
              threshold."
              CLEAR_MESSAGE="The value for %columnName% is %value%%%, which is
              below the critical (%critical_threshold%%%) or warning (%warning_
              threshold%%%) threshold." />
  </MetricColl>   
 </CollectionItem>
...
</TargetCollection>

Note that in addition to a message sent to Enterprise Manager when either the WARNING or CRITICAL thresholds are passed, and “all clear” message to be sent when a alert condition no longer exists has also been defined in the CLEAR_MESSAGE attribute.

3.5.4 Defining Target Configuration Data Collections

As with all other metrics, the frequency at which the configuration metric data is collected is defined default collection file. Given the size of target configuration collections and the infrequent change rate, these metrics should ideally be collected every 24 hours, during off-peak hours.

Note that the value of the TARGET_TYPE attribute of the root METADATA SNAP_TYPE attribute in the configuration metadata file must be identical the TYPE attribute of TargetCollection in the default collection file.

The following example defines the collection frequency for the HostConfig metric

<TargetCollection>
...
<CollectionItem NAME="HostSampleSnap" UPLOAD_ON_FETCH="TRUE" CONFIG="TRUE">
    <Schedule OFFSET_TYPE="INCREMENTAL">
      <IntervalSchedule INTERVAL="24" TIME_UNIT="Hr"/>
    </Schedule>
    <MetricColl NAME="HostConfig" />
     </CollectionItem>
...
</TargetCollection>

3.5.5 Overview of Key Default Collection Metadata Elements

Table 3-4 describes the key elements included in the default collection metadata file.

Table 3-4 Key Elements Within the Default Collection Metadata File

Element	Description
`TargetCollection`	Required. The root element for the file. It includes a `TYPE` attribute and the `META_VER` attribute that must match the `TYPE` attribute and the `META_VER` attribute of the `TargetMetadata` element in the target type metadata file.
`CollectionItem`	Defines a collection frequency and threshold values for a set of metrics. The frequency defined in the included `Schedule` element will apply to all metrics in the collection group. The element includes the following attributes: NAME: Defines the set of metrics to be collected as a group. UPLOAD: Specifies what nth data collection be written to the Management Repository. The default is 1, which means that performance data is uploaded every time it is collected. In Example 3-6, every 6th data collection is uploaded to the Management Repository.
`Schedule`	Contains an `IntervalSchedule` element defining the collection frequency for a CollectionItem. It includes the following attributes: INTERVAL: The collection frequency. TIME_UNIT: The unit of time - such as Min for minutes - that the value of INTERVAL corresponds to.
`MetricColl`	Contains one or more Condition elements corresponding to a single metric group defined in a Metric element in the target type metadata file. The NAME attribute in this element must match the NAME attribute in the corresponding Metric element.
`Condition`	Defines a metric alert condition. It contains the following optional attributes: COLUMN_NAME: The name of a metric defined in a ColumnDescriptor element in the target type metadata file. The value of this attribute must match the NAME attribute of the ColumnDescriptor element. WARNING: Defines the threshold at which a "warning" condition exists. A metric alert will be generated when this value is exceeded, which will include the text specified in the MESSAGE attribute. To allow users to set the threshold value, set this attribute to "NotDefined". CRITICAL: Defines the threshold at which a "critical" condition exists. A metric alert will be generated when this value is exceeded, which will include the text specified in the MESSAGE attribute. To allow users to set the threshold value, set this attribute to "NotDefined". OPERATOR: Determines how to apply the threshold values specified in the CRITICAL and WARNING attributes. In Example 3-6, `GE` specifies that the Warning threshold occurs when `ProcCPU` is greater than or equal to 75 and the Critical threshold occurs when `ProcCPU` is greater than or equal to 90. Other values include: LE: Less than or equals EQ: Equals LT: Less than GT: Greater than NE: Not equal CONTAINS: True if the second argument is a substring of the first string. MATCH: True if the first argument (regular expression) matches the second argument. OCCURENCES: Defines the number of successive metric collections that must be returned with the Warning or Critical threshold exceeded before the warning or critical condition is triggered. MESSAGE: Contains a message to display when the thresholds specified in the WARNING and/or CRITICAL attributes have been exceeded. The built-in message attributes such as %columnName% and %critical_threshold% are embedded in the string; the appropriate value will be substituted when the message is generated at runtime. For example: "The value for %columnName% is %value%%%. It has fallen below the critical (%critical_threshold%%%) or warning (%warning_threshold%%%) threshold." CLEAR_MESSAGE: Contains an "all clear" message that will be displayed when the value of the metric returns to a "non-alert" value; that is, when it drops below the thresholds indicated in WARNING and CRITICAL.

3.6 Guidelines for Creating Target Metadata

When developing target type definition files for new 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 Manager performance. Follow these general guidelines for defining target metadata and collections to optimize system performance.

3.6.1 Defining Target Metadata

Metadata is data about data. Generically, the term refers to any data used to help 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.

3.6.1.1 Metadata Version

Whenever the target metadata changes, increment the metadata version (META_VER).

3.6.1.2 Real-time Only Metrics

Performance metrics can be classified into metrics that must 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, such as a specific tablespace to diagnose further.

3.6.1.3 Choice of Key Columns

A key column in a metric is used in the management repository to trend performance data on an axis, such as 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.

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

3.6.1.5 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 Oracle 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.

3.6.1.6 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 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 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 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).

3.6.1.7 Metrics

The metric concept, as it pertains to the 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.

3.6.1.7.1 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 required).

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

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

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

3.6.2 Defining Collections

Collections are the mechanism by which the 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 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.

3.6.2.1 Alert Message Guidelines

Alert messages tell the user when something is wrong. These messages should also assist the user in solving the problem. Oracle recommends 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.

3.6.2.2 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. When a CollectionItem tag is used to define a collection, then the Management Agent evaluates all metrics with a collection item in order. However, collection items run independent of each other.

Note:

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

3.6.2.3 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 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 nn computation cycles.

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

3.7 Testing Your Target Type Definitions

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

3.7.1 Activate the Metric Browser

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

Check that the _enableMetricBrowser line in the $AGENT_HOME/sysman/config/emd.properties file is enabled, where AGENT_HOME represents the home directory of the Management Agent:
```
_enableMetricBrowser=True
```
Enter the following command to apply the changes that you made to the emd.properties file:
```
emctl reload agent
```
Open the emd.properties file and check the EMD_URL line. It has the following format:
```
EMD_URL=http://host:port/emd/browser/main
```

Alternatively, you can use the emctl command to activate the metric browser as follows:

emctl setproperty agent -name _enableMetricBrowser -value true

3.7.2 View Your Metrics

After 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

Tip:

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

Note:

You must use the Management Agent operating system credentials to log in to the metric browser.

3.8 Validating Your Metadata XML

To verify that your target metadata files are defined correctly, enter the following command from the bin directory of the EDK:

empdk validate_plugin -stage_dir plugin_stage

In the preceding command, plugin_stage represents the plug-in staging directory.

For information about the EDK, see Section 1.2, "About the Extensibility Development Kit (EDK)" and for more information about the empdk command and its usage, see Section 13.3, "Validating the Plug-in".

3.9 Troubleshooting the Target Creation Process

This section provides some troubleshooting tips if you encounter any issues with your targets.

My target is not added to Enterprise Manager

If your target is not added, do the following:

Check the Oracle Management Service trace file (emoms.trc) for exceptions. The OMS trace file is located in the EM_INSTANCE_BASE/em/OMS_NAME/sysman/log/ directory, where EM_INSTANCE_BASE is the OMS Instance Base directory (by default, this directory is under the parent directory of the Oracle Middleware Home).
```
grep –i EntityManager.createEntities *
grep –i EntityUtil *
```
If your target is added to the Management Repository but not to the Management Agent, go to the agentStateDir/sysman/log directory and check the Management Agent log file (gcagent_mdu.log). This log file tracks the metadata updates to the Management Agent.

My target continues to show a pending status

If your target is monitored by the Management Agent and it shows a pending status, then do the following:

Check if the Management Agent is still monitoring the target.

To listing the name and type of each target being monitored by a Management Agent:
1. Change directory to the AGENT_HOME/bin directory (UNIX) or the AGENT_HOME\bin directory (Windows).
2. Enter the following command:
```
emctl config agent listtargets
```
3. Check the output for your target.
Check that the plug-in is deployed on the Management Agent by reviewing the following log file:
```
agent_inst/sysman/registry.xml
```
Check that the Management Agent received the request to add the target. Go to the agentStateDir/sysman/log directory and review the Management Agent log file (gcagent_mdu.log).
From a SQL*Plus session, run the tgtinfo.sql script, similar to:
```
@tgtinfo oracle_database orcl
```
The tgtinfo.sql script includes the following:
```
SELECT type_meta_ver, ':'||category_prop_1||':'||
                           category_prop_2||':'||
                           category_prop_3||':'||
                           category_prop_4||':'||
                           category_prop_5||':' category_prop,
       target_guid,
       TO_CHAR(load_timestamp,'DD_MON-YY HH24:MI:SS'),        
       timezone_region,owner,host_name,emd_url,broken_reason,broken_str,manage_status,
       promote_status,
       dynamic_property_status
  FROM sysman.em_targets
 WHERE target_type='&&1'
   AND target_name='&&2'
/
```
Note:
If you are having issues running the script, edit the script to replace &&1 with the type of the target and replace &&2 with the name of the target.

The output from the script includes the following information:
- TARGET_TYPE
  
  Name of the target, such as oracle_database
- TYPE_META_VER
  
  Metadata version number. Check that the metadata version is correct for the target.
- CATEGORY_PROP_1
  
  Category properties can be used to distinguish different metric definitions based on different configurations. Check that the value is correct for the target.
- BROKEN_REASON
  
  If this value is greater than 0, then target is broken (for example, the target could not be saved or it is missing required properties). The BROKEN_STR value will provide a reason as to why the target is broken.
- MANAGE_STATUS
  
  The manage status of the target. Possible values include:
  - 0: Ignored
  - 1: Not yet managed
  - 2: Managed
  - 3: Managed target component
- PROMOTE_STATUS
  
  The promotion status of the target. Possible values include:
  - 0: Cannot promote (an existence-only entity)
  - 1: Eligable for promotion
  - 2: Promotion in progress
  - 3: Promoted to Management Agent
  - 4: Promotion in progress but target was added to the Management Agent previously
- DYNAMIC_PROPERTY_STATUS
  
  Status of the dynamic properties. Possible values include:
  - 0: Dynamic properties have not been uploaded by the Management Agent
  - 1: Dynamic properties are uploaded by the Management Agent