The following example shows the minimum required information that a target type file must contain.

Example: 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">
        <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 the previous example.

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:

test_demo_targetType.xml

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="test_demo_targetType").

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

The TYPE attribute and the META_VER attribute of the TargetMetadata element must match the TYPE attribute and the META_VER attribute of the TargetCollection element of the default collection metadata file. For more information about the default collection metadata file, see Creating the Default Collection File.

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.

The syntax for the meta value is MajorNumber.MinorNumber. The value for MinorNumber can be either one or two digits. It is important that you choose to use either one or two digits for MinorNumber, and continue to use that syntax throughout the plug-in's lifecycle.

A one-digit MinorNumber can be updated up to nine times, after which the MajorNumber value must be increased. For example:

1.0, 1.1, 1.2, ...,1.9, 2.0, 2.1

A two-digit MinorNumber can be revised up to 99 times. For example:

1.01, 1.02, 1.09, ..., 1.10, 1.11, ..., 1.99, 2.01

Note that you cannot combine single-digit and two-digit formats. For example, increasing the version from 1.9 to 1.10 is not valid.

If you modify the metadata for one or more metrics, or change credentials, or update the target property file during plug-in development, be sure to increment the value of the META_VER attribute of the TargetMetadata element to the next digit value. For example, if the current version is "1.0", set the value to "1.1" if you modify the metric metadata:

<TargetMetadata META_VER="1.1" TYPE="demo_hostsample"> 

Continue to increment the version each time you modify your metrics. Otherwise, NullPointerException errors may occur if the plug-in is deployed to the same development or test installation that the previous version was deployed to.

Once plug-in development is complete, the META_VER value can safely be set to the actual production version.

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

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.

Example: 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>

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

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 Enterprise Manager.

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 consists primarily of metric definitions, along with credential information and target properties. The fetchlet or receivelet that a metric will use is defined in the QueryDescriptor or PushDescriptor element within the target type metadata file.

  For information about key metric definition elements, see 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 Creating the Default Collection File.

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

• A Status metric that indicates target availability (required for all target types)

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 Defining Basic Metric Collection.

The following example (Response Metric) 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 (emrepresp.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 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 Enterprise Manager 11g and earlier, 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: Response Metric

<Metric NAME="Response" TYPE="TABLE">
 <TableDescriptor>
  <ColumnDescriptor NAME="Status" TYPE="NUMBER">
   <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>
 </QueryDescriptor>
</Metric>

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

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

The following example 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: 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>

The following example 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: 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>

The following examples show how to set UnitCategory and Unit NLSID on metric columns.

Example 1: Setting UnitCategory and Unit NLSID

<TableDescriptor>
<ColumnDescriptor NAME="cpuutil" TYPE="NUMBER" IS_KEY="FALSE" TRANSIENT="FALSE" HELP="NO_HELP">
<Display>
<Label NLSID="olv_server_load_cpuutil">CPU Utilization (%)</Label>
<Description NLSID="olv_server_load_cpuutil_desc">CPU Utilization (%)</Description>
<Unit NLSID="EM_SYS_STANDARD_UTILIZATION_PERCENTAGE">PERCENTAGE</Unit>
<UnitCategory>UTILIZATION</UnitCategory>
</Display>

Example 2: Setting UnitCategory and Unit NLSID

<ColumnDescriptor NAME="mem_avail" TYPE="NUMBER" IS_KEY="FALSE" TRANSIENT="FALSE" HELP="NO_HELP">
<Display>
<Label NLSID="olv_server_load_mem_available">Memory Available (GB)</Label>
<Description NLSID="olv_server_load_mem_available_desc">Memory Available (GB)</Description>
<Unit NLSID="EM_SYS_STANDARD_DATASIZE_GB">GB</Unit>
<UnitCategory>DATA_SIZE</UnitCategory>
</Display>

Example 3: Setting UnitCategory and Unit NLSID

<ColumnDescriptor NAME="guest_vm_count" TYPE="NUMBER" IS_KEY="FALSE" TRANSIENT="FALSE" HELP="NO_HELP">
<Display>
<Label NLSID="olv_server_guest_vms">Number of Guest VMs</Label>
<Description NLSID="olv_server_guest_vms_desc">Number of Guest VMs</Description>
<Unit NLSID="EM_SYS_STANDARD_COUNT_NA">NA</Unit>
<UnitCategory>COUNT</UnitCategory>
</Display>
</ColumnDescriptor>

By default, the Management Agent collects metrics but you can define repository metrics. Repository metrics are collected at the Management Repository.

To define a repostitory metric, you must use the REPOSITORY attribute when defining the Metric element. For more information about the Metric element, see Table 3-4.

The following example provides an extract from a target metadata XML file where a repository metric is defined.

Example: Defining Repository Metrics

  <Metric NAME="Response"
          TYPE="TABLE" 
          REPOSITORY="TRUE">
    <Display>
      <Label NLSID="REPOS_SQL">REPOS_SQL</Label>
    </Display>
    <TableDescriptor>
      <ColumnDescriptor NAME="Status" TYPE="NUMBER">
        <Display>
          <Label NLSID="Status">Status</Label>
        </Display>
      </ColumnDescriptor>
    </TableDescriptor>
    <QueryDescriptor FETCHLET_ID="REPOSITORY_SQL">
       <Property NAME="Type">SQL</Property>
       <Property NAME="Source">SELECT target_guid, 1 as Status from mgmt_targets where target_type='tvmrtm200'</Property>
    </QueryDescriptor>
  </Metric>

The purpose of the categorization of metrics is to define the nature of the data that is being collected. This is only for metrics that are visible in the All Metrics pages in the Enterprise Manager console.

Oracle recommends using the following guidelines when defining metric categories:

• Categorize all Metrics and Metric Groups visible to the user in the All Metrics page of the Enterprise Manager console.

• Use the published category values only as listed in Table 3-3.

• If all metrics in a metric group belong to the same category, then you can set the category at the metric group level and leave the category empty at the metric level. All metrics in the group will inherit this category. You can set one category only at the metric group level. For an example, see Defining a Category at Metric Group Level.

• If the metrics in the metric group have different categories, do not set a category at the metric group level. In such cases, set the category at the metric level. Each metric can have one category only. For an example, see the Defining a Category at Metric Level example.

The Metric framework has a Default metric class and a set of metric categories within this class. Table 3-3 provides a list of the available metric categories. You can categorize your metrics into the appropriate category within the Default metric class

The following example categorizes all metrics within MyMetricGroup with a metric class of Default and a metric category of Load.

Example: Defining a Category at Metric Group Level

<Metric NAME="MyMetricGroup" TYPE="TABLE">
  <Display>    <Label>MyMetricGroup</Label>  </Display>  
  <CategoryValue CLASS="Default" CATEGORY_NAME="Load"/>
  <TableDescriptor>    
     <ColumnDescriptor NAME="MyMetric1" TYPE="NUMBER">    </ColumnDescriptor>
     <ColumnDescriptor NAME="MyMetric2" TYPE="NUMBER">    </ColumnDescriptor>  
  </TableDescriptor> </Metric>  

The following example categorizes the MyMetric1 metric with a metric class of Default and a metric category of Load, and the MyMetric2 metric with a metric class of Default and a metric category of Load Type.

Example: Defining a Category at Metric Level

<<Metric NAME="MyMetricGroup" TYPE="TABLE">  
  <Display>    
    <Label>MyMetricGroup</Label>  
  </Display>  <TableDescriptor>    
  <TableDescriptor> 
    <ColumnDescriptor NAME="MyMetric1" TYPE="NUMBER">      
      <Display>        
        <Label>MyMetric1</Label>      
      </Display>      
      <CategoryValue CLASS="Default" CATEGORY_NAME="Load"/>
    </ColumnDescriptor>    
    <ColumnDescriptor NAME="MyMetric2" TYPE="NUMBER">      
      <Display>        
        <Label>MyMetric2</Label>      
      </Display>      
      <CategoryValue CLASS="Default" CATEGORY_NAME="Load Type"/>
    </ColumnDescriptor>  
  </TableDescriptor> 
</Metric> 

Enterprise Manager provides the option to statistically compute metric thresholds that are adaptive in nature and this is available for all targets.

For more information about Adaptive Thresholds, see Oracle Enterprise Manager Administrator's Guide.

You can provide a named configuration for your target type. This quick configuration contains preconfigured metrics values and a computation mechanism.

To define a quick configuration:

<Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>
<Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl</Property>

<Property NAME="MatchSpecificTrap" SCOPE="GLOBAL">50</Property>
<Property NAME="MatchAgentAddr" SCOPE="INSTANCE">AdminAddress</Property>

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

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

• To list metrics for a given target type, from a SQL*Plus session, enter the following:

  select * from mgmt_metrics where target_type=target_type and type_meta_ver=max_type_meta
  

• To check if there are any metric load issues, from a SQL*Plus session, enter the following:

  select * from sysman.mgmt_system_error_log where module_name='METRIC_LOAD' 
  

• To check if there are any collection issues during the metadata load, from a SQL*Plus session, enter the following:

  select * from sysman.mgmt_system_error_log where module_name='MGMT_COLLECTION.Collection Subsystem' 
  

• To check what is being collect for a specific target, from a SQL*Plus session, enter the following:

  select * from sysman.gc_metric_values where entity_type=target_type and entity_name=target_name
  

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. The CollectionItem provides the end user with the most control to enable or disable metrics and to change the collection schedule.

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 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 any of the following applies:

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

Providing different collection intervals will provide the best flexibility to users to schedule each metric independently. Grouping together unrelated metrics is not advisable, as you will not have the ability to turn off collection of just a few metrics in the group without disabling those metrics that you do need.

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 Creating the Default Collection File and Table 3-5.

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="test_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>

The following example illustrates the collection of a more advanced metric that raises a metric alert when specified WARNING and CRITICAL thresholds are exceeded. These thresholds, and the message to send to Enterprise Manager 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 this example. For a description of the elements in this example, see Table 3-5.

Example: 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 an alert condition no longer exists has also been defined in the CLEAR_MESSAGE attribute.

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" CONFIG="TRUE">
    <Schedule OFFSET_TYPE="INCREMENTAL">
      <IntervalSchedule INTERVAL="24" TIME_UNIT="Hr"/>
    </Schedule>
    <MetricColl NAME="HostConfig" />
     </CollectionItem>
...
</TargetCollection>

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

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

To check if the collection is disabled for a specific target, from a SQL*Plus session, enter the following:

select * from sysman.mgmt_collections where object_type=2 and object_guid=target_guid and is_enabled=1 

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.

• Metadata Version

  Whenever the target metadata changes, increment the metadata version (META_VER). For more information, see Defining the Target Type Metadata.

• 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 the resource utilization for specific processes, 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, such as the tablespace usage per database tablespace. Key-based metrics should be used to model sub-components of the target for which meaningful metric data should be collected, either for target monitoring or target diagnostic purposes. As such, only key columns that are the logical identifiers of the target sub-components should be included in the metric.

  Note that including key columns for which the number of distinct values collected across a large number of targets could result in an excessive number of key values being stored in the management repository. For example, using a timestamp (or equivalent, like database SCN or UNIX ctime) as a key value will result in a new value for every collection for every target, and is therefore not advisable.

  Including a combination of key columns can also be problematic. For example, if you include three key columns in a metric, in which each key can take one of 10 target-specific values (10X10x10) multiplied by the number of targets, you would be collecting data for 1000 keys per target. This could be considered excessive if more than a handful of targets are being managed.

  Do not define metrics that have nonsharable and durable keys across targets and time.

  You do not have to have key columns, but the query descriptor must return a single row.

  Note:

  Do not modify key columns, that is, order, data type, or number after creating a metric.

• Transient Columns

  In some cases, metric columns can be used to compute the values of other more interesting metric columns. When the original columns are not required, then you can mark these columns as transient so that they are not uploaded to the Management Repository, therefore saving space.

  Metrics that are dependent on a duration of time must not be uploaded. Mark these types of metrics as transient. This includes delta metrics such as Request Process (last collection interval).

• Rate Metrics

  Metrics should contain data values for recent activity. In many cases, to do this, you must create rate metrics out of existing metrics. The COMPUTE_EXPR attribute (defined in Table 3-4) specifies the formula for calculating the value of a column. The following list provides the supported grammar for Compute Expression:

  expression := (cond_expr | (cond_expr ? cond_expr : cond_expr)
  cond_expr := (string_expr |
  (string_expr == string_expr) |
  (string_expr < string_expr) |
  (string_expr > string_expr) |
  (string_expr <= string_expr) |
  (string_expr >= string_expr) |
  (string_expr __contains string_expr) |
  (string_expr __beginswith string_expr) |
  (string_expr __endswith string_expr) |
  (string_expr __matches string_expr) |
  (string_expr __delta string_expr))
  string_expr := (simple_expr |
  (simple_expr __leadingchars simple_expr) |
  (simple_expr __trailingchars simple_expr) |
  (simple_expr __substringpos simple_expr))
  simple_expr := (term |
  (simple_expr + term ) |
  (simple_expr - term) )
  term := (unary_expr |
  (term * unary_expr ) |
  (term / unary_expr ) )
  unary_expr := (factor |
  (__is_null factor) |
  (__length factor) |
  (__to_upper factor) |
  (__to_lower factor) |
  (__ceil factor) |
  (__floor factor) |
  (__round factor) )
  factor := ( identifier |
  string_literal |
  number |
  '(' expression ')' )
  string_literal := '\'' (character | "\\'" )* '\''
  

  To create rate metrics from existing metrics, define the following metrics:

  • Calculating Delta

    requests.completed.delta = (requests.completed > _requests.completed) ? (requests.completed - _requests.completed) : 0
    

    If the current value of requests.completed is more than the previous value, then obtain delta by getting the difference between the current value and the last value. Otherwise return 0.

  • Calculating Rate

    requests.completed (per minute) = (requests.completed > _requests.completed) ? (requests.completed - _requests.completed) *60 /__interval: 0
    

    If the current value of requests.completed is more than the previous value, then obtain delta by getting the difference between the current value and the last value and then multiplying by 60 and dividing by the interval between 2 collections. Otherwise, return 0.

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

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

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

  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 appear on the All Metrics page, Metric and Collections Settings page, Event Rules page, Group Charts page, and other pages within the Enterprise Manager user interface. For this reason, Oracle recommends the following metric naming conventions.

  • Ensure that metric column names are as explicit as possible. Do not include count in the column name because it adds to the length of the name and does not provide value to the end user. For example:

    Errors (per minute)

    Note: Do not use Error Count (per minute).

  • 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). If the metric refers to a unit of measure, include the unit in the metric label inside a parenthesis. For example:

    Network Interface Total I/O Rate (MB/sec)

    Requests Processed (per minute)

    Transactions Committed (%)

  • Metrics that are increasing values which reset at startup should not be uploaded. Mark these metrics as transient and include since startup in the metric label inside a parenthesis. For example:

    Processing Time (since startup)

    Errors (since startup)

    Requests (since startup)

    Average Execution Time (ms - since startup)

  • All metric column names (labels) should be self-explanatory without dependence on the metric name. For example:

    Tablespace Space Used (%)

  • Key column names must be self-explanatory. Enterprise Manager uses these names when specifying metric thresholds or configuring notifications. For readability, the name of the key column name must fit easily within the phrase "all key column name objects". For example:

    all tablespace objects

  • Across target versions, the same columns must use the same labels. This ensures columns, such as metric columns and short names, have the same NLS IDs across different target versions.

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.

Target metadata can optionally support localized strings, including target type display name and metric and metric column labels, enabling Enterprise Manager to display labels in the language and locale of each Enterprise Manager user. To support this feature, the target metadata file must include the RESOURCE_BUNDLE_PACKAGE property in the TargetMetadata tag. The RESOURCE_BUNDLE_PACKAGE property specifies the location of the resource properties files that contains the localized target strings. For information about the TargetMetadata tag, see Creating the Target Type Metadata File.

Use the three-part plug-in id, followed by the package selected for the resource bundles. For example, if the plug-in ID is test.group.domain, then define the resource bundle package as follows:

RESOURCE_BUNDLE_PACKAGE=test.group.domain.rsc

In the previous example, rsc is the package selected for the resource bundles. You can use any alphanumeric string for the package name but you cannot include special characters.

The strings included in the target metadata that can be externalized to the resource properties file are the Label tags associated with the target type, metric and column items.

You must place all of the strings defined for your target metadata in a resource properties file, named target_typeMsg.properties. Include this file in the corresponding directory in the resource deployment. For more information, see Package Resource Bundles.

In the following example, the plug-in ID is test.group.domain and the target type is domain_widget.

Example: Defining a Resource Bundle Package for Target Metadata Localization

<TargetMetadata META_VER="1.0" TYPE="domain_widget" RESOURCE_BUNDLE_PACKGE="test.group.domain.rsc">
<Display>
<Label NLSID="dom_widget">Domain Widget</Label>
</Display>

For this plug-in deployment, you must have a resource properties file named test.group.domain.rsc.domain_widgetMsg.properties. This file contains all the strings for the target metadata and includes the following:

# Strings for the domain_widget target type within the test.group.domain plug-in
dom_widget = Domain Widget

In the default collection metadata file, metric collection conditions can specify the following properties for the message alert and cleared message:

The following example provides an example of a metric definition that includes the resource identifier for the alert message and cleared message.

Example: Defining a Metric to Include Localization Properties

<MetricColl NAME="CPUPerf">
  <Condition COLUMN_NAME="non_nice" WARNING="NotDefined" CRITICAL="NotDefined" 
     OPERATOR="GE" 
     MESSAGE="The value for %columnName% is %value%%%.  It has risen above the critical (%critical_threshold%%%) or warning (%warning_threshold%%%) threshold."
     MESSAGE_NLS_ID="dhs_non_nice_cond_msg"
     CLEAR_MESSAGE="The value for %columnName% is %value%%%.  It has fallen below the critical (%critical_threshold%%%) or warning (%warning_threshold%%%) threshold." 
     CLEAR_MESSAGE_NLS_ID="dhs_non_nice_clear_msg" />

Before you package the resource bundle, check the About Resource Property Bundle Content to ensure the contents of your package are formatted correctly.

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

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

emctl setproperty agent -name _enableMetricBrowser -value true

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