23 Enterprise Manager DTD

A DTD provides the grammar for the XML files, thus describing what content is expected in each of its related XML files. When creating a new XML file, you need to carefully study its DTD to understand what content needs to be present in that file.

This chapter to provides a lookup of DTD elements to facilitate integration with Oracle Server Technology products:

23.1 Terminology

This chapter provides a lookup of DTD elements to facilitate integration with Oracle Server Technology products. Most of the examples in the document are snippets of an XML file.

Target: Target is a managed entity. A managed entity can be a hardware device or a software resource. Examples of a target are: host system, Oracle database, SMTP service etc.

Associated Target: Targets whose data depend on each other.

Metric: Collectable data

Mid Tier: OMS – Oracle Management Server

Container: A container is an entity that houses an Oracle installation. Currently two kinds of containers are possible – Oracle Home (Database, Enterprise Manager, Oracle Application Server installs) and ApplTop (application installs).

Cluster Targets: Cluster targets span across many hosts. All cluster targets represent the same target. The agents monitoring each of the cluster targets will produce the same metric result, severities, and so on.

Cluster Interfaces: Standard interfaces that the agent uses to talk to the cluster target.

23.2 Target Metadata DTD Elements

This section defines DTD elements used by Enterprise Manager.

23.2.1 TargetMetadata

The TargetMetadata describes the metadata for a target type. Metadata for a target describes its measurable characteristics, format of the collected data and the mechanism to collect or compute that data.

<!ELEMENT TargetMetadata (Display*, TypeProperties?, AssocTarget*, DiscoveryHelper?, MonitoringMode*, AltSkipCondition?, MetricClass*, Metric*, CredentialInfo?, InstanceProperties?, SSH_ERROR_MSG?)>

<!ATTLIST TargetMetadata

META_VER CDATA #REQUIRED

TYPE CDATA #REQUIRED

REQUIRED_AGENT_VERSION CDATA #IMPLIED

HELPID CDATA #IMPLIED

HELP CDATA #IMPLIED

CATEGORY_PROPERTIES CDATA #IMPLIED

RESOURCE_BUNDLE_PACKAGE CDATA #IMPLIED

TARGET_TYPE_CATEGORY CDATA #IMPLIED

HOST_BINDING_REQUIRED (TRUE | FALSE) "TRUE"

>

Note:

The maximum length allowed for the various attributes mentioned in the file must be mentioend in tagsize.properties. This will be used to truncate the length of the attributes in the metadata file while loading the metadata information into the repository.

23.2.1.1 Attributes

META_VER: Describes the version of metadata.

TYPE: Specifies the Target type.

HELPID: Not used.

HELP: Not used.

CATEGORY_PROPERTIES: Semicolon separated list of properties, used as properties for ValidIf. Currently, each target type can have up to 5 properties used as category property. EMAgent evaluates the values of the category properties and makes it available within the metadata.

RESOURCE_BUNDLE_PACKAGE:

REQUIRED_AGENT_VERSION: This attribute indicates the minimum agent version for the metadata. TargetMetadata marked with this attribute will be valid on Agent versions greater than or equal to the specified version.

TARGET_TYPE_CATEGORY: Determines the Category to which the target type belongs to. Multiple Target Type Categories can be specified as semicolon seperated list of Categories.

HOST_BINDING_REQUIRED: Indicates whether the target needs a host target.

(TRUE (default) | FALSE)

23.2.1.3 Used In

TargetMetadata is a top-level element.

23.2.1.4 Examples

<TargetMetadata TYPE="example1" META_VER="2.0" REQUIRED_AGENT_VERSION=”10.2.0.1.0”>

. . .

</TargetMetadata>

The Metadata in the above example has REQUIRED_AGENT_VERSION attribute set to ”10.2.0.1.0”. This metadata will be valid only on agent versions 10.2.0.1.0 and higher.

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

<Metric NAME=”prop” TYPE=”TABLE”>

<TableDescriptor>

<ColumnDescriptor NAME="name" TYPE="STRING" IS_KEY="TRUE" />

<ColumnDescriptor NAME="value" TYPE="STRING" />

</TableDescriptor>

<QueryDescriptor FETCHLET_ID="OS">

<Property NAME="hostname" SCOPE="INSTANCE">NAME</Property>

</QueryDescriptor>

</Metric>

</TargetMetadata>

This is a very simple example that describes a Target type, &rsquor;exmaple1' having data (Metric) that needs to be collected in the following format. The quoted values are evaluated by the &rsquor;OS' Fetchlet in accordance with the scoping rules defined in Property.

Table 23-1 Metric Prop

Name

Value

Host Name

NAME


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

<Metric NAME="perf" TYPE=”TABLE”>

<TableDescriptor>

<ColumnDescriptor NAME="char" TYPE="STRING" IS_KEY="TRUE" />

<ColumnDescriptor NAME="value" TYPE="STRING" />

</TableDescriptor>

<QueryDescriptor FETCHLET_ID="OSLineToken" >

<Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl %scriptsDir%/example1/perf.pl %port% </Property>

<Property NAME="delimiter" SCOPE="GLOBAL">=</Property>

<Property NAME="port" SCOPE="INSTANCE">accessPort</Property>

</QueryDescriptor>

</Metric>

<InstanceProperties>

<InstanceProperty NAME="accessPort" />

</InstanceProperties>

</TargetMetadata>

This sample illustrates the use of InstanceProperties. InstanceProperties element associates &rsquor;accessPort' to be associated with the target instance. The metric &rsquor;perf' is collected as shown below. The quoted values are evaluated by the &rsquor;OSLineToken' Fetchlet in accordance with the scoping rules defined in Property.

Table 23-2 Metric: perf

Char Value

Command

&rsquor;%perlBin%/perl %scriptsDir%/example1/perf.pl %port%'

Delimiter

=

Port

'accessPort'


<TargetMetadata TYPE="example3" META_VER="2.0" CATEGORY_PROPERTIES="OS">

<Metric NAME=”prop” TYPE=”TABLE”>

. . .

</Metric>

<InstanceProperties>

<DynamicProperties NAME="VersionAndLocation" FORMAT="ROW" PROP_LIST="OS;OracleHome;Version">

<QueryDescriptor FETCHLET_ID="OSLineToken">

<Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property>

<Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>

<Property NAME="ENVEmdOS" SCOPE="SYSTEMGLOBAL">_emdOS</Property>

<Property NAME="ENVVersion" SCOPE="SYSTEMGLOBAL">_emdVersion</Property>

<Property NAME="ENVORACLE_HOME" SCOPE="SYSTEMGLOBAL">emdRoot</Property>

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

<Property NAME="script" SCOPE="GLOBAL">%scriptsDir%/emdlocandver.pl </Property>

<Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>

<Property NAME="delimiter" SCOPE="GLOBAL">|</Property>

</QueryDescriptor>

</DynamicProperties>

</InstanceProperties>

</TargetMetadata>

This sample uses a DynamicProperties element to return OS, OracleHome and Version properties. The scripts return results that are parsed to return the properties listed in the PROP_LIST attribute.

23.2.2 Display

Specifies the information to be used by the Console UI for displaying the element that has this tag.

<!ELEMENT Display (ValidIf*, Label, ShortName?, Icon?, Description?, Unit?)>

<!ATTLIST Display

FOR_SUMMARY_UI (TRUE | FALSE) "FALSE">

23.2.2.1 Attributes

FOR_SUMMARY_UI: Indicates whether a column is visible in the condensed UI. Condensed view is necessary when all the columns cannot fit in one UI page. In a condensed view, only columns whose FOR_SUMMARY_UI=TRUE will be displayed.

TRUE | FALSE (default)

23.2.2.4 Examples

Display element must contain a Label element. The elements ShortName, Icon, Description and Unit are optional. If ValidIf element(s) are present then all the conditions in the ValidIf elements must be satisfied for the element to be displayed.

<Display FOR_SUMMARY_UI="TRUE">

<Label NLSID="emd_resp_stat">Status</Label>

</Display>

This example describes the display characteristics for the element that includes it. The &rsquor;FOR_SUMMARY_UI' set to TRUE forces the UI to display the element in the condensed view also.

<Display FOR_SUMMARY_UI="TRUE">

<ValidIf>

<CategoryProp NAME="OS" CHOICES="SunOS"/>

</ValidIf>

<Label NLSID="id_name_for_agent">Agent Name</Label>

<ShortName NLSID="id_short_name">Name</ShortName>

<Icon GIF=”a.gif”>Name</Icon>

<Description NLSID=”id_for_description”>Displays the Agent Name</Description>

</Display>

This sample describes the display characteristics for an element that are valid only for &rsquor;SunOS' OS.

23.2.3 SSH_ERROR_MSG

Free form error message to be displayed at the console in case SSH is not available for monitoring a remote target of this type.

<!ELEMENT SSH_ERROR_MSG (#PCDATA)>

<!ATTLIST SSH_ERROR_MSG

NLSID CDATA #REQUIRED

>

23.2.3.1 Attributes

NLSID: The NLSID of the free form error message

23.2.3.2 Elements

None.

23.2.3.3 Used In

TargetMetadata

23.2.3.4 Examples

<SSH_ERROR_MSG NLSID="ssh_error_nlsid">

Target data will not be available until sshd is available

</SSH_ERROR_MSG>

23.2.4 TypeProperties

The TypeProperties holds TypeProperty elements for the target type.

<!ELEMENT TypeProperties (TypeProperty*)>

23.2.4.1 Attributes

None.

23.2.4.2 Elements

TypeProperty

23.2.4.3 Used In

TargetMetadata

23.2.4.4 Examples

<TypeProperties>

<TypeProperty PROPERTY_NAME=”a_name” PROPERTY_VALUE=”a_value”/>

</TypeProperties>

The property name-value pair, a_name,a_value, would apply to the target type.

23.2.5 TypeProperty

TypeProperty element contains the property name-value pair for a target type.

<!ELEMENT TypeProperty EMPTY>

<!ATTLIST TypeProperty

PROPERTY_NAME CDATA #REQUIRED

PROPERTY_VALUE CDATA #IMPLIED

>

23.2.5.1 Attributes

PROPERTY_NAME: Name of the target type property.

PROPERTY_VALUE: Value of the target type property.

23.2.5.2 Elements

None.

23.2.5.3 Used In

TypeProperties

23.2.5.4 Examples

Refer to the example for TypeProperties.

23.2.6 AssocTarget

The AssocTarget describes how two targets are related to each other. Targets may be associated for a number of reasons some of them being: rendering topology maps, root cause analysis, determining availability of targets, minimizing redundancy in data collection and transmission and determining order for data collection or job execution amongst others. For instance, if a fault occurs on a target, its associated target might be affected too. This information would be valuable in root cause analysis.

<!ELEMENT AssocTarget (AssocPropDef*)>

<!ATTLIST AssocTarget

ASSOC_TARGET CDATA #IMPLIED

TYPE CDATA #IMPLIED

ASSOCIATION_NAME CDATA #IMPLIED

NAME_NLSID CDATA #IMPLIED

DESCRIPTION CDATA #IMPLIED

DESCRIPTION_NLSID CDATA #IMPLIED

SOURCE_TARGET_TYPE CDATA #IMPLIED

ASSOC_TARGET_TYPE CDATA #IMPLIED

CARDINALITY (OPTIONAL_SINGLE_CARDINAL |

REQUIRED_SINGLE_CARDINAL |

OPTIONAL_MULTI_CARDINAL |

REQUIRED_MULTI_CARDINAL) #IMPLIED

ASSOC_TYPE (RELATES_TO|DEPENDS_ON | CONNECTS_TO |

SERVICE_ACCESS_POINT|RUNS_ON|

CONTAINS|HOSTED_BY|MONITORED_BY|

OPTIONALLY_CONNECTS_TO) #IMPLIED

COMPUTE_RULE (PARENT | MEMBER | NONE) ”NONE”

>

23.2.6.1 Attributes

ASSOC_TARGET: the name of the associated target.

TYPE: the target type of the associated target.

ASSOCIATION_NAME: deprecates ASSOC_TARGET. Specifies the name of the association

ASSOC_TARGET_TYPE: deprecates TYPE. Specifies the target type that is associated with this target. &rsquor;ANY' can be used to indicate that the association target could be any target type.

NAME_NLSID: NLSID for association name

DESCRIPTION: Description

DESCRIPTION_NLSID: NLSID for description string

SOURCE_TARGET_TYPE: If association starts from a target, other than the target itself, the target type of the source target is specified in this attribute. &rsquor;ANY' can be used to indicate that the source could be any target type.

CARDINALITY: Specifies the cardinality of the associated targets. Supported values are:

  1. OPTIONAL_SINGLE_CARDINAL: zero or one targets as associated

  2. REQUIRED_SINGLE_CARDINAL: exactly one associated target

  3. OPTIONAL_MULTI_CARDINAL: zero or several associated targets

  4. REQUIRED_MULTI_CARDINAL: one or more associated targets

ASSOC_TYPE: Describes the relation of the associated targets. Supported Values are:

  1. RELATES_TO (default): implies "some" generic relationship

  2. DEPENDS_ON: Dependency on associated target

  3. CONNECTS_TO: Source target connects to assoc target

  4. SERVICE_ACCESS_POINT

  5. RUNS_ON: Source target runs on (installed on) assoc target

  6. CONTAINS: Source target contains assoc target

  7. HOSTED_BY: Similar to runs on

  8. MONITORED_BY: Source target is monitored by assoc target (agent)

  9. OPTIONALLY_CONNECTS_TO

COMPUTE_RULE: Describes how the Association is computedIif not already present) for the target instance. Supported values are:

  1. PARENT: will be constructed based on the first parent of the target.

  2. MEMBER: will be construced based on the first child of the target.

  3. NONE (default): Association for the target instance is not automatically computed.

23.2.6.2 Elements

AssocPropDef (Not supported in version 10.2.)

23.2.6.3 Used In

TargetMetadata

23.2.6.4 Examples

AssocTarget element for versions prior to 10.2 MUST have the following attributes:

  1. ASSOC_TARGET

  2. TYPE

AssocTarget element for versions 10.2 and later MUST use the following attributes at least.

  1. ASSOCIATION_NAME instead of ASSOC_TARGET.

  2. ASSOC_TARGET_TYPE instead of TYPE.

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

<AssocTarget ASSOCIATION_NAME="IM"

SOURCE_TARGET_TYPE="oracle_email"

ASSOC_TARGET_TYPE="oracle_im"

ASSOCIATION_TYPE="DEPENDS_ON"

NAME_NLSID=”im_assoc_name”

DESCRIPTION=”This association captures Email-IM dependency”

DESCRIPTION_NLSID=”im_assoc_description” />

. . .

</TargetMetadata>

This element would be defined in &rsquor;oracle_email' and would represent the following relation:

Oracle_email -----DependsOn----à oracle_im

23.2.7 AssocPropDef

The AssocPropDef describe the properties for an association. This element is not supported in version 10.2.

<!ELEMENT AssocPropDef EMPTY>

<!ATTLIST AssocPropDef

NAME CDATA #REQUIRED

REQUIRED (TRUE | FALSE) #REQUIRED>

23.2.7.1 Attributes

NAME: Name of the property.

REQUIRED: Indicates whether the property is required.

TRUE | FALSE

23.2.7.2 Elements

None.

23.2.7.3 Used In

AssocTarget

23.2.7.4 Examples

This element is not supported.

23.2.8 DiscoveryHelper

The DiscoveryHelper helps the agent in its process of discovering the target type.

<!ELEMENT DiscoveryHelper (DiscoveryHint*) >

<!ATTLIST DiscoveryHelper

CATEGORYNAME CDATA #REQUIRED

OUI_BASED (TRUE | FALSE) "TRUE"

>

23.2.8.1 Attributes

CATEGORYNAME: name of the category in discover.lst which discovers targets for a given type.

OUI_BASED: boolean value to indicate if this discovery used OUI inventory info.

TRUE (default) | FALSE

23.2.8.2 Elements

DiscoveryHint

23.2.8.3 Used In

TargetMetadata

23.2.8.4 Examples

23.2.9 DiscoveryHint

The DiscoveryHint allows users to specify any hint which can be a guide to discovery.

<!ELEMENT DiscoveryHint (Display?) >

<!ATTLIST DiscoveryHint

NAME CDATA #REQUIRED

>

23.2.9.1 Attributes

NAME: name of the hint to guide discovery process

23.2.9.2 Elements

Display

23.2.9.3 Used In

DiscoveryHelper

23.2.9.4 Examples

23.2.10 MetricClass

MetricClass provides a means for classifying Metrics into categories. Metrics can be classified into categories based on multiple characteristics such as Function (Perf, Load, Config), EvaluationCost (Cheap, Medium, Expensive) and Applicability (Typical, Esoteric).

<!ELEMENT MetricClass (MetricCategory*)>

<!ATTLIST MetricClass

NAME CDATA #REQUIRED

NLSID CDATA #IMPLIED>

23.2.10.1 Attributes

NAME: Is the name of the class (e.g. Functional)

NLSID: Is the translation ID. The naming convention is metric_class_<classname>

23.2.10.2 Elements

MetricCategory

23.2.10.3 Used In

TargetMetadata

23.2.10.4 Examples

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

<MetricClass NAME=”EvaluationCost” NLSID=”id_for_eval_cost_class”>

<MetricCategory NAME=”CHEAP” NLSID=”id_for_cheap_cat”/>

<MetricCategory NAME=”MEDIUM” NLSID=”id_for_medium_cat”/>

<MetricCategory NAME=”EXPENSIVE” NLSID=”id_for_expensive_cat”/>

</MetricClass>

<Metric NAME=”metric1” TYPE=”TABLE”>

<CategoryValue Class=”EvaluationCost” CATEGORY_NAME=”CHEAP”/>

. . .

</Metric>

. . .

</TargetMetadata>

The example describes adding a &rsquor;EvaluationCost' MetricClass for a Target type &rsquor;example3'. EvaluationCost has 3 categories: CHEAP, MEDIUM, and EXPENSIVE. Metric, &rsquor;metric1' is a CHEAP metric to evaluate.

Refer to the explanations of CategoryValue, Metric for more details.

23.2.11 MetricCategory

A MetricCategory element lists each choice within a classification of metrics.

<!ELEMENT MetricCategory EMPTY>

<!ATTLIST MetricCategory

NAME CDATA #REQUIRED

NLSID CDATA #IMPLIED>

23.2.11.1 Attributes

NAME: The name of the category (e.g. Security)

NLSID: The NLSID of the category. The naming convention here is metric_cat_<category_name>

23.2.11.2 Elements

None.

23.2.11.3 Used In

MetricClass

23.2.11.4 Examples

Refer to the example for MetricClass.

23.2.12 Metric

A metric element is used to declare the different measurable characteristics (performance, load, configuration and so on) of a target. The metric element describes the structure of the collected data as well as how to compute the information.

Note:

Oracle recommends that every target type have a special metric named ”Response”. This metric should have a column called ”Status”. The type creator should also set up a collection of this metric and set up a condition (see TargetCollection.dtd) on the Status column. The availability system (target up/down status over time) uses alerts on this metric column to provide up/down statistics over time.

Note: QueryDescriptor is required for Management Repository metrics.

<!ELEMENT Metric ((ValidIf | ValidMidTierVersions)*, Display?, CategoryValue* ,TableDescriptor?, ((QueryDescriptor | ExecutionDescriptor) | PushDescriptor)* )>

<!ATTLIST Metric

NAME CDATA #REQUIRED

TYPE (NUMBER | STRING | TABLE | RAW | EXTERNAL | REPOSITORY_TABLE | REPOSITORY_NUMBER | REPOSITORY_STRING | REPOSITORY_EVENT) "NUMBER"

REPOSITORY (TRUE|FALSE) "FALSE"

USAGE_TYPE (VIEW_COLLECT | REALTIME_ONLY | HIDDEN | HIDDEN_COLLECT | COLLECT_UPLOAD) "VIEW_COLLECT"

KEYS_FROM_MULT_COLLS (TRUE | FALSE) "FALSE"

IS_TEST_METRIC (TRUE | FALSE) "FALSE"

KEYS_ONLY (TRUE | FALSE) "FALSE"

REMOTE (TRUE | FALSE) "FALSE"

IS_TRANSPOSED (TRUE | FALSE) "FALSE"

HELP CDATA #IMPLIED

IS_METRIC_LONG_RUNNING (TRUE|FALSE) "FALSE"

CONFIG (TRUE|FALSE) "FALSE"

FORCE_CACHE (TRUE | FALSE) "FALSE"

COLLECT_ON_ALL_NODES (TRUE | FALSE) "FALSE"

INCREMENTAL (TRUE|FALSE) "FALSE"

NUM_CACHE_VALUES CDATA "1"

LOCAL_ONLY (TRUE | FALSE) "FALSE"

>

23.2.12.1 Attributes

NAME: Specifies Metric name, it uniquely identifies it within the scope of its target type.

TYPE: Specifies the data type. Supported metric types are:

a) NUMBER (default): Deprecated – Instead use a table with 1 column of type NUMBER.

b) STRING: Deprecated – Instead use a table with 1 column of type STRING

c) TABLE: Tabular data

d) RAW: Tabular data

e) EXTERNAL: Data not parsed/fronted by EMD.

f) REPOSITORY_EVENT

REPOSITORY: This attribute indicates a metric that will be collected by the Management Repository. This is a boolean attribute.

FALSE (default) indicates that the metric is collected by the Management Agent.

TRUE indicates that the metric is collected at the Management Repository. When this attribute is set to TRUE, the query descriptor must be similar to the following:

 <QueryDescriptor FETCHLET_ID="REPOSITORY_SQL">
                     <Property NAME="Type">SQL</Property>
                     <Property NAME="Source">CDATA</Property>
                  </QueryDescriptor>

There must be one query descriptor only. Possible values for Type are:

  • SQL

  • PLSQL

  • BULK_PLSQL

    Note:

    When REPOSITORY is set to TRUE, the Metric TYPE must be TABLE. RAW is not supported for Repository metrics.

USAGE_TYPE: This defines the purpose of the metric. Supported types are:

a) VIEW_COLLECT (default): These are metrics that are both viewable and collected.

b) REALTIME_ONLY: These are metrics that cannot be collected. The rules on key uniqueness are not applied to these metrics.

c) HIDDEN: Metrics are tagged hidden when they shouldn't be collected nor visible from the console. The data is not uploaded either. These are "temporary" metrics used to compute other metrics.

d)HIDDEN_COLLECT: Metric can be collected. It will not be viewable. The data is not uploaded. It is similar to HIDDEN, but collection criteria can be defined for it.

e) COLLECT_UPLOAD: Metric can be collected and uploaded, Metadata is uploaded to MGMT_METRICS but it is not viewable in All Metrics page.

Mapping of old USAGE_TYPE values

DISPLAY_ONLY: REALTIME_ONLY

MULTI_KEY: VIEW_COLLECT

COLLECT_ONLY: VIEW_COLLECT

The metric browser automatically decides which metrics to not display.

KEYS_FROM_MULT_COLLS: If TRUE, the attribute indicates that there are multiple key columns. The combination of key columns uniquely identifies a row. If the value is TRUE only then can the metric be collected in multiple collection items.

TRUE | FALSE (default)

IS_TEST_METRIC: The agent can check some metrics to determine if a target has been correctly specified with valid instance properties. This attribute marks this metric as one of the test metrics.

TRUE or FALSE (default)

HELP: Help text – This attribute is not used.

KEYS_ONLY: It is used to tag special metrics that have only key columns. Note that in general, such metrics are not useful in collections (since no data is uploaded), but there may be special cases where the metric is used to just retrieve a set of keys.

TRUE or FALSE (default)

IS_METRIC_LONG_RUNNING: IF true, the metric is long running. This gives the metric engine, a hint that this query will take relatively longer to finish. A special property EM_IS_METRIC_LONG_RUNNING will be passed to fetchlet automatically.

TRUE or FALSE (default)

CONFIG: This is a special designation for CONFIG metrics that are uploaded differently by the Enterprise Manager framework.

TRUE or FALSE (default)

REMOTE: It is used to tag metrics that can be evaluated from a remote location. These metrics could be evaluated from "beacon" nodes

IS_TRANSPOSED: It is used to tag metrics that generate data as name value pairs and the UI treats the names as "column headers". These are useful when the number of rows (or data categories) is not known at design time.

FORCE_CACHE: For collected metrics, this is a strong hint to the agent to cache the results of a metric collection. In the absence of this hint, the agent may only start caching the result of a metric after it realizes that someone will try to use the cached value.

COLLECT_ON_ALL_NODES: For a clustered target, metrics marked with this attribute set to TRUE, will be collected on all the nodes of the cluster.

TRUE | FALSE (default)

INCREMENTAL: This attribute is used ONLY by the OCM collector. This attribute is TRUE iff the metric is incremental i.e. the rows collected during a collection do not replace the ones collected during the previous collection but rather add to them. This is the case for metric data whose lifespan extend across collections for example the ECM_RUNNING_PRODUCTS metric.

NUM_CACHE_VALUES: Starting with 11, the agent will support the ability to cache multiple collection results in memory for access by the EMDClient getMetricHistory API. The value of this attribute defaults to 1, but the user can set it to a higher value such as 15 or 60

LOCAL_ONLY: Specifies that a metric should be collected for local targets only and skipped for remote targets.

23.2.12.3 Used In

TargetMetadata

23.2.12.4 Examples

<TargetMetadata TYPE="example1" META_VER="2.0" CATEGORY_PROPERTIES=”OS;Version”>

<Metric NAME=”prop” TYPE=”TABLE”>

<Display>

<Label NLSID="example1_metric">Example1 Metric</Label>

</Display>

<TableDescriptor>

<ColumnDescriptor NAME="name" TYPE="STRING" IS_KEY="TRUE" />

<ColumnDescriptor NAME="value" TYPE="STRING" />

</TableDescriptor>

<QueryDescriptor FETCHLET_ID="OS">

<Property NAME="hostname" SCOPE="INSTANCE">NAME</Property>

</QueryDescriptor>

</Metric>

</TargetMetadata>

This is the most common form of a metric definition. The statement declares the metric, &rsquor;example1', to contain tabular data.

If a metric has a ”TABLE” type, the value will be returned as a set of rows each containing a set of values (columns). A list will be a special case of the Table. A Table Metric must have a TableDescriptor defined.

<Metric NAME="Inventory" TYPE="EXTERNAL" >

<ValidIf>

<CategoryProp NAME="OS" CHOICES="SunOS"/>

</ValidIf>

<Display>

<Label NLSID="host_Inventory">Inventory</Label>

</Display>

<QueryDescriptor FETCHLET_ID="OS">

<Property NAME="emdRoot" SCOPE="SYSTEMGLOBAL">emdRoot</Property>

<Property NAME="emHome" SCOPE="SYSTEMGLOBAL">agentStateDir</Property>

<Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property>

<Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>

<Property NAME="hostConfigClasspath" SCOPE="SYSTEMGLOBAL">hostConfigClasspath</Property>

<Property NAME="hostname" SCOPE="INSTANCE">NAME</Property>

<Property NAME="type" SCOPE="INSTANCE">TYPE</Property>

<Property NAME="display_target_name" SCOPE="INSTANCE">DISPLAY_NAME</Property>

<Property NAME="display_target_type" SCOPE="INSTANCE">TYPE_DISPLAY_NAME</Property>

<Property NAME="command" SCOPE="GLOBAL">"%perlBin%/perl" "%scriptsDir%/osm/ecmCollectInventory.pl" "%hostConfigClasspath%" "%perlBin%" "%emdRoot%" "%emHome%" "%hostname%" "%loaderFile%" "%emHome%/sysman/config/OUIinventories.add" "%type%" "%display_target_name%" "%display_target_type%"</Property>

</QueryDescriptor>

</Metric>

This example declares &rsquor;Inventory' as EXTERNAL which implies that the metric will be evaluated in the correct format and will be placed in the upload directory. The EMAgent will not parse the metric result. The ValidIf element ensures that the metric will be evaluated only for &rsquor;SunOS' OS.

<Metric NAME="AddressMap" TYPE="TABLE" FORCE_CACHE="TRUE">

The contents would be similar to a TABLE metric

</Metric>

In this example, the agent is forced to cache the results for the AddressMap metric.

<Metric NAME="ICMPPing" TYPE="TABLE" IS_TEST_METRIC="TRUE" USAGE_TYPE="HIDDEN">

The contents would be similar to a TABLE metric

</Metric>

&rsquor;ICMPPing' is identified as a test metric. The agent will use its value to verify that the target identified by the instance properties is correct. Since the purpose of this metric is for INTERNAL use only, it is marked as &rsquor;HIDDEN'.

USAGE_TYPE Summary:

USAGE_TYPE KEY_UNIQUE_CHECK COLLECTABLE MGMT_METRICS_RAW MGMT_METRICS VIEWABLE
VIEW_COLLECT Y Y Y Y Y
REALTIME_ONLY N N N Y N
HIDDEN Y N N Y N
HIDDEN_COLLECT Y Y N Y N
COLLECT_UPLOAD Y Y Y Y Y

<Metric NAME="http_raw" TYPE="TABLE" KEYS_FROM_MULT_COLLS="TRUE" REMOTE="TRUE">

The contents would be similar to a TABLE metric

</Metric>

&rsquor;http_raw' metric can be evaluated from a remote location and therefore is tagged as &rsquor;REMOTE'.

<Metric NAME="openPorts" TYPE="RAW" CONFIG="TRUE" KEYS_ONLY="TRUE" HELP="NO_HELP">

<ValidIf>

<CategoryProp NAME="OS" CHOICES="SunOS"/>

</ValidIf>

<Display>

<Label NLSID="host_open_ports_ESM">Open Ports</Label>

</Display>

<TableDescriptor TABLE_NAME="esm_collection">

<ColumnDescriptor NAME="property" COLUMN_NAME="property" TYPE="STRING" IS_KEY="TRUE" HELP="NO_HELP"/>

<ColumnDescriptor NAME="value" COLUMN_NAME="value" TYPE="STRING" IS_KEY="TRUE" HELP="NO_HELP"/>

</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%/openports.pl</Property>

<Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>

<Property NAME="delimiter" SCOPE="GLOBAL">=</Property>

</QueryDescriptor>

</Metric>

&rsquor;openPorts' is defined as a CONFIG metric. Since the type is RAW, EMAgent expects the values in the correct format.

<Metric NAME="storage_reporting_data" TYPE="RAW" CONFIG="TRUE" IS_METRIC_LONG_RUNNING="TRUE">

The contents would be similar to a RAW metric

</Metric>

This specifies that storage_reporting_data takes a long time to execute.

23.2.13 ValidIf

The ValidIf element is used to create type definitions that apply to multiple flavors of a target. To do this, certain properties of the target (up to a max of 5) can be marked as category properties, and ValidIf elements can be placed in portions of the metadata to indicate that they are only applicable if the target's property values match the specified values.

The CategoryProp elements within a ValidIf should all match for the containing element to be evaluated. A containing element may include multiple ValidIfs to indicate its applicability for different sets of conditions.

<!ELEMENT ValidIf (CategoryProp+)>

23.2.13.1 Attributes

None.

23.2.13.2 Elements

CategoryProp

23.2.13.4 Examples

<TargetMetadata TYPE="example1" META_VER="2.0" CATEGORY_PROPERTIES=”OS;Version”>

<Metric NAME=”prop” TYPE=”TABLE”>

<ValidIf>

<CategoryProp NAME="OS" CHOICES="SunOS"/>

<CategoryProp NAME="Version" CHOICES="5.9"/>

</ValidIf>

<TableDescriptor>

<ColumnDescriptor NAME="name" TYPE="STRING" IS_KEY="TRUE" />

<ColumnDescriptor NAME="value" TYPE="STRING" />

</TableDescriptor>

<QueryDescriptor FETCHLET_ID="OS">

<Property NAME="hostname" SCOPE="INSTANCE">NAME</Property>

</QueryDescriptor>

</Metric>

</TargetMetadata>

This example indicates that the category properties, &rsquor;OS' and &rsquor;Version' must have values, &rsquor;SunOS' and &rsquor;5.9' for the metric, &rsquor;prop' to be evaluated. EMAgent allows the definition of upto 5 category properties which can be used in ValidIfs elements.

23.2.14 CategoryProp

The CategoryProp element is used to list the allowed values for a property for the ValidIf to match.

<!ELEMENT CategoryProp EMPTY>

<!ATTLIST CategoryProp

NAME CDATA #REQUIRED

CHOICES CDATA #REQUIRED>

23.2.14.1 Attributes

NAME: Specifies the name of the category property.

CHOICES: Specifies the values the property can have. This may contain values separated by ";".

23.2.14.2 Elements

None.

23.2.14.3 Used In

ValidIf

23.2.14.4 Examples

<ValidIf>

<CategoryProp NAME="OS" CHOICES="SunOS"/>

<CategoryProp NAME="Version" CHOICES="5.8;5.9"/>

</ValidIf>

If the example described in the ValidIf statement is modified such that the &rsquor;Version' CategoryProperty now has two choices 5.8 and 5.9, the metric would be evaluated for &rsquor;SunOS' versions 5.8 and 5.9.

<ValidIf>

<CategoryProp NAME="OS" CHOICES="SunOS"/>

</ValidIf>

<ValidIf>

<CategoryProp NAME="OS" CHOICES="AIX"/>

</ValidIf>

A metric that has ValidIfs as shown above, would be evaluated if OS is either SunOS or AIX.

Note: If ValidIfs are used to differentiate between multiple definitions of the same metric, there should be no cases where multiple definitions of the metric get validated.

<Metric NAME=”a_metric” TYPE=”TABLE”>

<ValidIf>

<CategoryProp NAME=”C1” CHOICES=”A;B”>

</ValidIf>

. . .

</Metric>

<Metric NAME=”a_metric” TYPE=”TABLE”>

<ValidIf>

<CategoryProp NAME=”C1” CHOICES=”A;C”>

</ValidIf>

. . .

</Metric>

The above example demonstrates how NOT to use ValidIfs.

23.2.15 ValidMidTierVersions

The ValidMidTierVersions element is used in the mid tier based versioning support in the agent.

This element can be used either under a Metric or within a CustomTableMapper element. When present, it indicates to the agent that a Metric definition or a CustomTableMapper definition only applies for a certain set of mid tier versions.

<!ELEMENT ValidMidTierVersions EMPTY>

<!ATTLIST ValidMidTierVersions

PLUG_IN CDATA #IMPLIED

START_VER CDATA #IMPLIED

END_VER CDATA #IMPLIED>

23.2.15.1 Attributes

PLUG_IN: Optional attribute that allows a particular mid tier plug in to be referenced. If not specified, this tag applies to the core OMS version.

START_VER: Starting version (inclusive, optional) the element is applied from.

END_VER: Ending version (exclusion, optional) that the element is applicable to.

23.2.15.2 Elements

None.

23.2.15.3 Used In

Metric

CustomTableMapper

23.2.15.4 Examples

Every ValidMidTierVersions element needs to have at least one of START_VER or END_VER specified.

<Metric NAME="metric1" TYPE="RAW">

<TableDescriptor>

<CustomTableMapper REP_TABLE_NAME=”table1”>

<ValidMidTierVersions PLUG_IN=”DB” START_VER=”10.1” END_VER=”10.3”/>

<ColumnMapper METRIC_COLUMN=”col1” REP_TABLE_COLUMN=”col1_rep”/>

</CustomTableMapper>

<ColumnDescriptor NAME="c1" COLUMN_NAME="col1" TYPE="STRING"/>

<ColumnDescriptor NAME="c2" COLUMN_NAME="col2" TYPE="STRING"/>

</TableDescriptor>

<QueryDescriptor>

. . .

</QueryDescriptor>

</Metric>

The CustomTableMapper element mapping &rsquor;metric1' to repository table, &rsquor;table1' is applicable only for DB Plugin versions between 10.1 (inclusive) and 10.3 (not inclusive).

<ValidMidTierVersions START_VER=”10.1.0.1”/>

This element if present in a Metric or CustomTableMapper would indicate to the EMAgent that the Metric or the CustomTableMapper is applicable only to OMS versions 10.1.0.1 and higher.

<ValidMidTierVersions END_VER=”10.2”/>

This element if present in a Metric or CustomTableMapper would indicate to the EMAgent that the Metric or the CustomTableMapper is applicable only to OMS versions less than (not including) 10.2.

23.2.16 TableDescriptor

TableDescriptor describes the structure of the data for the metric of type TABLE.

<!ELEMENT TableDescriptor (ColumnDescriptor+, CustomTableMapper*)>

<!ATTLIST TableDescriptor

TABLE_NAME CDATA #IMPLIED

SKIP_TARGET_COLUMN (TRUE | FALSE) "FALSE"

SKIP_METRIC_COLUMN (TRUE | FALSE) "FALSE"

SKIP_COLLTIME_PK (TRUE | FALSE) "FALSE"

SKIP_COLLTIME_COLUMN (TRUE | FALSE) "FALSE">

Note:

SKIP_COLLTIME_PK attribute is deprecated. This attribute specifies that the collection timestamp should not be a part of the primary key. This was used to indicate that the latest row should override any previous rows with the same primary key. Since this can now be done by simply altering the table definition in the repository, SKIP_COLLTIME_PK is not useful any more.

23.2.16.1 Attributes

TABLE_NAME: This attribute specifies the repository database table into which the collected data will be loaded to. Note: Only RAW metrics can define this attribute. If a TableDescriptor contains CustomTableMapper elements, it should not contain a TABLE_NAME attribute.

SKIP_TARGET_COLUMN: This attribute is applicable for a RAW metric only. If set to TRUE, Target GUID column will not be generated.

TRUE | FALSE (default)

SKIP_METRIC_COLUMN: This attribute is applicable for a RAW metric only. If set to TRUE, the Metric Name column will not be generated.

TRUE | FALSE (default)

SKIP_COLLTIME_PK: Deprecated in version 10.2.The SKIP_COLLTIME_PK option can be used if the collection timestamp needs to be generated, but not added as a primary key.

TRUE | FALSE (default)

23.2.16.2 Elements

ColumnDescriptor

CustomTableMapper

23.2.16.3 Used In

Metric

23.2.16.4 Examples

A Table Metric must have a TableDescriptor defined. It describes columns of the table.

<Metric NAME=”prop” TYPE=”TABLE”>

<Display>

<Label NLSID="example1_metric">Example1 Metric</Label>

</Display>

<TableDescriptor>

<ColumnDescriptor NAME="name" TYPE="STRING" IS_KEY="TRUE" />

<ColumnDescriptor NAME="value" TYPE="STRING" />

</TableDescriptor>

<QueryDescriptor FETCHLET_ID="OS">

<Property NAME="hostname" SCOPE="INSTANCE">NAME</Property>

</QueryDescriptor>

</Metric>

This is the most common usage for the TableDescriptor element that represents a metric of TYPE=TABLE. For mid-tier versioning support refer to the Examples for CustomTableMapper.

<TableDescriptor TABLE_NAME="esm_collection">

This declaration is valid only for a RAW metric. This element contains the description of esm_collection table within a RAW metric.

<TableDescriptor TABLE_NAME="mgmt_db_compatibility"

SKIP_COLLTIME_PK="TRUE" SKIP_COLLTIME_COLUMN="TRUE"

SKIP_METRIC_COLUMN="TRUE" SKIP_TARGET_COLUMN="TRUE">

The SKIP attributes may be applied only to RAW metrics. The EMAgent automatically generates TARGET_GUID, METRIC_NAME and COLLECTION_TIMESTAMP columns for a raw metric unless explicitly indicated by setting SKIP attributes to TRUE. The TableDescriptor, in this sample explicitly requests the omission of the default columns.

23.2.17 ColumnDescriptor

The ColumnDescriptor elements describe each column in a table. The agent also supports one level of nesting of tables for RAW metrics. This allows metrics to return a table of data in place of a column which is uploaded in the context of the containing row. For example: In a metric that returns a list of expensive SQL statements in a database, a column that returns the multi-row explain plan for the SQL statement could be returned in a nested raw metric column.

<!ELEMENT ColumnDescriptor (Display?, CategoryValue*, TableDescriptor?)>

<!ATTLIST ColumnDescriptor

NAME CDATA #REQUIRED

TYPE (NUMBER | STRING | RAW | CLOB | BLOB) "NUMBER"

IS_FILENAME (TRUE | FALSE) "FALSE"

IS_KEY (TRUE | FALSE) "FALSE"

TRANSIENT (TRUE | FALSE) "FALSE"

COMPUTE_EXPR CDATA #IMPLIED

REPLACE_FETCHED_VALUE (TRUE | FALSE) "FALSE"

COLUMN_NAME CDATA #IMPLIED

IS_LONG_TEXT (TRUE | FALSE) "FALSE"

IS_DATE (TRUE | FALSE) "FALSE"

STATELESS_ALERTS (TRUE|FALSE) "FALSE"

IS_TIMESTAMP (TRUE | FALSE) "FALSE"

NON_THRESHOLDED_ALERTS (TRUE | FALSE) ”FALSE”

KEYONLY_THRESHOLDS (TRUE | FALSE) ”FALSE”

RENDERABLE (TRUE | FALSE) ”TRUE”

HELP CDATA #IMPLIED>

23.2.17.1 Attributes

NAME: This is the metric column name.

TYPE: Specifies the data type.

Supported types are:

a) NUMBER (default)

b) STRING.

c) RAW: This is for nested table support. A column may be defined as RAW to indicate it is a nested-table. Note: Only 1 level of nested table is allowed.

d) CLOB: CLOB holds large character data such as a log file.

e) BLOB: BLOB holds binary data (.zip files, .tar, files, etc.).

IS_KEY: is set to true if this column is the primary key (uniquely identifies the row in the returned rows). For any two rows returned, the value of the key column cannot be the same, else there will be a primary key violation. Note: Upto 5 columns can be marked with IS_KEY=TRUE. If no column is defined as key, the default value for the key is null (therefore should only return 1 row at a time)

TRUE | FALSE (default)

TRANSIENT: This will not be uploaded to repository. Only used to calculate rate data.

TRUE | FALSE (default)

COMPUTE_EXPR: This attribute specifies the formula for calculating the value of the column. Columns previously defined in the Table descriptor can participate in the calculation. Attaching a &rsquor;_' prefix to a column name denotes previous value of a column. Refer to the Examples for details about the expression grammar and usage.

Predefined special values:

a) __interval: collect interval.

b) __sysdate: current system time.

c) __GMTdate: current GMT time.

d) __contains: tests a given string expression for presence of a string expression.

e) __beginswith: tests whether a given string expression begins with a specified string expression.

f) __endswith: testw whether a given string expression ends with the specified string expression.

g) __matches: tests whether a given string expression matches a specified string expression.

h) __delta: computes the difference between the current value and the previous value.

i) __leadingchars: returns the leading characters in the specified string.

j) __trailingchars: returns the trailing characters in the specified string.

k) __substringpos: returns the position of the occurrence of the pattern within a specified string.

l) __is_null: tests whether the expression is NULL

m) __length: returns the length of the string expression.

n) __to_upper: converts the string to upper case.

o) __to_lower: converst the string to lower_case.

p) __ceil: returns the smallest integral value not less than identifier.

q) __floor: returns the largest integral value not greater than the identifier.

r) __round: rounds to nearest integer, away from zero.

Prior to version 11, columns with COMPUTE_EXPR attributes could only be present after all the fetchlet returned columns. As part of bug 4869048, special compute expr columns will be allowed to be mixed in columns that get values from fetchlets.

COLUMN_NAME: This value will be used if the metric type is RAW to identify the database column.

IS_LONG_TEXT: This value will only be used when the metric is RAW and the column will be in digested form. The agent has support for metrics that expect to return the same long string repeatedly in metric results. If a column is marked with IS_LONG_TEXT=”TRUE”, the agent sends a row mapping the string to a digest into the MGMT_LONG_TEXT table and thereafter only sends the digested value as the data to the repository.

TRUE | FALSE (default)

IS_DATE: This value will only be used when the metric is RAW and the column is date type.

TRUE | FALSE (default)

STATELESS_ALERTS: This attribute if set to TRUE indicates to Enterprise Manager that alerts on this column will not have corresponding clears. This allows the UI to decide whether to allow users to manually clear alerts on this column.

TRUE | FALSE (default)

IS_TIMESTAMP: The value in this column will be used as the collection time for this row. If set to true, the values for this column should be specified in the yyyy-MM-dd HH:mm:ss z format (For example: "2003-07-30 08:41:05 PST"). The list of valid time zones is listed in the $ORACLE_HOME/sysman/emd/supportedtzs.lst file.

HELP: Not used.

IS_FILENAME: When set to TRUE, it indicates that the column value is a file name that contains the real content that needs to be sent. IS_FILENAME attribute is valid only for CLOB/BLOB column types.

NON_THRESHOLDED_ALERTS: This attribute is used to indicate that there might be alerts for the metric column without there being a thresholded condition for it (eg: through server generated alerts).

TRUE | FALSE (default)

KEYONLY_THRESHOLDS: If this attribute is set to TRUE, conditions cannot apply to all metric rows and all Condition elements for the column need a KeyColumn element.

TRUE | FALSE (default)

RENDERABLE: A FALSE value for this attribute indicates that the value for this column maybe generated by the engine and may be cryptic or random enough to be of any use to the user. The UI would not display this value and would not allow the user to set thresholds for this value.

TRUE (default) | FALSE

REPLACE_FETCHED_VALUE: This attribute is only applicable if COMPUTE_EXPR is set, and for inner compute expressions (see above). If set, this tells the agent to use the compute expression value in place of the corresponding column returned by the fetchlet. If not set, the metric engine will right shift all existing fetchlet returned values to make place for the computed value.

TRUE | FALSE (default)

23.2.17.3 Used In

TableDescriptor

23.2.17.4 Examples

Each column must specify the name and the data type for the column. The column can also be tagged as a key column. These column values qualify the value returned in the non-key columns.

For example: In a metric for top 10 processes, the process name will be the key column while the residence memory size, cpu, time used will be the value columns.

<ColumnDescriptor NAME="ciscoMemoryPoolName" TYPE="STRING" IS_KEY="TRUE">

<Display>

<Label NLSID="cisco_mem_pool_name">Memory Pool Name</Label>

</Display>

</ColumnDescriptor>

This is the most common usage of the ColumnDescriptor element. &rsquor;ciscoMemoryPoolName' is a key column in a metric. The values of this column are of type, &rsquor;STRING'. The optional Display element when included in the ColumnDescriptor, associates a UI Label with the Column.

<ColumnDescriptor NAME="pgScan" TYPE="NUMBER" IS_KEY="FALSE" TRANSIENT="TRUE" HELP="NO_HELP"/>

The attribute, &rsquor;TRANSIENT' indicates that the column is used for internal calculations only and should not be uploaded to the repository.

<ColumnDescriptor NAME="property" COLUMN_NAME="property" TYPE="STRING" IS_KEY="TRUE" HELP="NO_HELP"/>

The &rsquor;COLUMN_NAME' attribute will be used in RAW metrics to identify a database column.

<ColumnDescriptor NAME="log_file_message" TYPE="STRING" IS_KEY="FALSE" IS_LONG_TEXT="TRUE"/>

&rsquor;IS_LONG_TEXT' attribute, when set to TRUE, is an indication to the EMAgent to expect long values.

<ColumnDescriptor NAME="load_timestamp" COLUMN_NAME="load_timestamp" TYPE="STRING" IS_DATE="TRUE" IS_KEY="FALSE"/>

This example defines a column &rsquor;load_timestamp' for a RAW metric with values in the date format.

<ColumnDescriptor NAME="log_file_match_count" TYPE="NUMBER" IS_KEY="FALSE" STATELESS_ALERTS="TRUE"/>

This definition indicates that the alerts on the column, &rsquor;log_file_match_count' will not have corresponding clears. The UI can provide the users the option to manually clear alerts for this data.

The example for TableDescriptor describes a table metric with ColumnDescriptor elements.

Note:

It is invalid for a ColumnDescriptor to both be a key and a timestamp column.

CLOB/BLOB is only valid inside RAW metrics. When TYPE is set to CLOB or BLOB, the ColumnDescriptor can also have IS_FILENAME attribute set to TRUE, in which case, the column value is the name of the file whose content should be sent rather than the column value itself. For CLOB/BLOB columns, the destination columns in the repository table should also be of CLOB/BLOB type.

Compute Expression Support:

Supported Grammar:

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 | "\\'" )* '\''

Usage:

<ColumnDescriptor NAME="pgScan" TYPE="NUMBER" />

<ColumnDescriptor NAME="pgScanRate" TYPE="NUMBER" IS_KEY="FALSE" COMPUTE_EXPR="(pgScan-_pgScan)/__interval"/>

The value of the column is calculated using the given compute expression. The value of the column is calculated using the present value of the &rsquor;pgScan' column, the previous value of the same column (&rsquor;_pgScan') and the collect interval. Note: &rsquor;pgScan' column should be defined before any column can use its value in the COMPUTE_EXPR.

<ColumnDescriptor NAME="baseDir" TYPE="STRING" />

<ColumnDescriptor NAME="component" TYPE="STRING" COMPUTE_EXPR="'/httpd'" />

<ColumnDescriptor NAME="full_path" TYPE="STRING" COMPUTE_EXPR="baseDir + component + &rsquor;/egs/log/' "/>

The value of the column, &rsquor;full_path' is ”<baseDir>/httpd/egs/log/” where <baseDir> is the value of the column baseDir.

<ColumnDescriptor NAME="value1" TYPE="NUMBER" COMPUTE_EXPR="Col __contains &rsquor;ay'" />

<ColumnDescriptor NAME="value2" TYPE="NUMBER" COMPUTE_EXPR="Col __beginswith &rsquor;Mon'" />

<ColumnDescriptor NAME="value3" TYPE="NUMBER" COMPUTE_EXPR="Col_ _endswith 'day'" />

<ColumnDescriptor NAME="value4" TYPE="NUMBER" COMPUTE_EXPR="Col __matches 'Sun*'" />

If the value of Col, in the above metric, is ”Sunday”, the outcome of the COMPUTE_EXPR will be as follows:

value1 = 1

value2 = 0

value3 = 1

value4 = 1

<TableDescriptor>

<ColumnDescriptor NAME="parse_str" TYPE="STRING" IS_KEY="TRUE" />

<ColumnDescriptor NAME="startpos" TYPE="NUMBER" COMPUTE_EXPR="parse_str __substringpos &rsquor;#D1'" />

<ColumnDescriptor NAME="num_trailing" TYPE="NUMBER" COMPUTE_EXPR="(__length parse_str) - startpos" />

<ColumnDescriptor NAME="trim_str" TYPE="STRING" COMPUTE_EXPR="parse_str__trailingchars num_trailing" />

<ColumnDescriptor NAME="endpos" TYPE="NUMBER" COMPUTE_EXPR="trim_str __substringpos &rsquor;#E1'" />

<ColumnDescriptor NAME="result_str" TYPE="STRING" COMPUTE_EXPR="trim_str __leadingchars endpos" />

</TableDescriptor>

The sample TableDescriptor describes a simple method for extracting a substring from a given string. If the data represented by ”parse_str” is of the form:

#A1 10

#B1 20

#C1 30

#D1 40

#E1 50

#F1 60

The ”result_str” has the value ”#D1=40”.

23.2.18 CategoryValue

A CategoryValue element indicates the category for a metric, column or condition under a particular classification. If a CategoryValue is defined for a Metric element, it is valid for all the ColumnDescriptors in that Metric. If it is defined for a ColumnDescriptor, that column will have a category value that overrides the union of what it has and what is defined for the Metric.

The following MetricCategories are predefined for the MetricClass, &rsquor;FUNCTIONAL':

a) FAULT: metrics that can be used to indicate a breakdown in a component or occurrence of an error that indicates some component or user is unable to successfully complete processing. Example: AlertLog – Archiver hung

b) WORKLOAD_VOLUME: metrics that capture the workload on a system induced in proportion to the user's or batch jobs running against the system. It usually is an indication of how much work is done. Example: User calls (per second)

c) WORKLOAD_TYPE: metrics that capture the type of workload on a system independent of demand. It usually is an indication of what kind of work is done. Example: Logical Reads (per transaction)

d) PERFORMANCE: metrics that can be classified to measure the performance of a system. It usually is an indication of how well the system is doing. Example: Database response (per second)

e) CAPACITY: metrics that measure the usage of a fixed resource. Example: CPU Usage (per second)

f) CONFIGURATION: metrics that check the configuration of a target against a recommended best-practice configuration.

g) SECURITY: metrics that relate to the security aspects of the system.

<!ELEMENT CategoryValue EMPTY>

<!ATTLIST CategoryValue

CLASS CDATA #REQUIRED

CATEGORY_NAME CDATA #REQUIRED>

23.2.18.1 Attributes

CLASS: Name of the metric class.

CATEGORY_NAME: Name of the metric category.

23.2.18.2 Elements

None.

23.2.18.3 Used In

Metric

ColumnDescriptor

Condition

23.2.18.4 Examples

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

<MetricClass NAME=”EvaluationCost” NLSID=”id_for_eval_cost_class”>

<MetricCategory NAME=”CHEAP” NLSID=”id_for_cheap_cat”/>

<MetricCategory NAME=”MEDIUM” NLSID=”id_for_medium_cat”/>

<MetricCategory NAME=”EXPENSIVE” NLSID=”id_for_expensive_cat”/>

</MetricClass>

<Metric NAME=”metric1” TYPE=”TABLE”>

<CategoryValue Class=”EvaluationCost” CATEGORY_NAME=”CHEAP”/>

. . .

</Metric>

. . .

</TargetMetadata>

This example illustrates the use of CategoryValue for a Metric. ”metric1” is ”CHEAP” to evaluate.

<Metric NAME="FileSystems" TYPE="TABLE" >

<CategoryValue CLASS="FUNCTIONAL" CATEGORY="WORKLOAD_VOLUME" />

<TableDescriptor>

<ColumnDescriptor NAME="FileSystem" TYPE="STRING" IS_KEY="TRUE" />

<ColumnDescriptor NAME="totalSpace" TYPE="NUMBER" >

<CategoryValue CLASS="FUNCTIONAL" CATEGORY="CAPACITY" />

</ColumnDescriptor>

<ColumnDescriptor NAME="diskUsedPct" TYPE="NUMBER />

<TableDescriptor>

....

</Metric>

In this sample, the column, ”totalSpace” has a CategoryValue, ”CAPACITY” which overrides the CategoryValue, ”WORKLOAD_VOLUME” associated with the metric.

23.2.19 CustomTableMapper

The CustomTableMapper element is part of the mid tier based versioning project that allows custom (RAW) metrics to change their destination tables based on the version of the mid tier.

The TableDescriptor for a RAW metric can have multiple CustomTableMapper elements - one per set of mid tier versions - with each CustomTableMapper providing repository table and column mappings for the TableDescriptor's Columns.

<!ELEMENT CustomTableMapper (ValidMidTierVersions*, ColumnMapper*)>

<!ATTLIST CustomTableMapper

REP_TABLE_NAME CDATA #REQUIRED>

23.2.19.1 Attributes

REP_TABLE_NAME: Indicates the table name that the content of the metric should be uploaded to.

23.2.19.2 Elements

ValidMidTierVersions

ColumnMapper

23.2.19.4 Examples

<TableDescriptor>

<ColumnDescriptor NAME="c1" COLUMN_NAME="col1" TYPE="STRING"/>

<ColumnDescriptor NAME="c2" COLUMN_NAME="col2" TYPE="STRING"/>

<CustomTableMapper REP_TABLE_NAME=”table1”>

<ValidMidTierVersions PLUG_IN=”DB” START_VER=”10.1” END_VER=”10.3”/>

<ColumnMapper METRIC_COLUMN=”col1” REP_TABLE_COLUMN=”col1_rep”/>

</CustomTableMapper>

</TableDescriptor>

This sample illustrates Mid-tier based versioning. TableDescriptor element must not contain the TABLE_NAME attribute. The sample describes a mapping of the metric to the repository table, &rsquor;table1' for Mid-tier versions between 10.1 (inclusive) and 10.3 (not inclusive). Metric column, &rsquor;col1' maps to &rsquor;col1_rep' in the repository table, &rsquor;table1'.

Refer to the example for ValidMidTierVersions also.

23.2.20 ColumnMapper

The ColumnMapper element is part of a CustomTableMapper element and describes the mapping between the ColumnDescriptor and the repository column its data should end up in.

The presence of a ColumnMapper provides the mapping for the column in a particular repository table, and indicates that the column is required in the table. To indicate that a column should not be uploaded to a particular version of the repository, there should not be a ColumnMapper for that column

<!ELEMENT ColumnMapper EMPTY>

<!ATTLIST ColumnMapper

METRIC_COLUMN CDATA #REQUIRED

REP_TABLE_COLUMN CDATA #REQUIRED>

23.2.20.1 Attributes

METRIC_COLUMN: Name of the ColumnDescriptor this applies to

REP_TABLE_COLUMN: The database table column name this data should end up in.

23.2.20.2 Elements

None.

23.2.20.3 Used In

CustomTableMapper

23.2.20.4 Examples

Refer to the Examples for CustomTableMapper.

23.2.21 QueryDescriptor

The query descriptor allows the framework to find the fetchlet as well as pass on the query information for obtaining performance data values from the target. The fetchlet can be identified by a well known id that is known to the EMAgent. It may also contain properties that will be passed to the fetchlet.

<!ELEMENT QueryDescriptor (ValidIf*, Property*) >

<!ATTLIST QueryDescriptor

FETCHLET_ID CDATA #REQUIRED

NEED_CHARSET_CONVERT (TRUE | FALSE) "TRUE"

REMOTE (TRUE | FALSE) "FALSE"

ON_TARGET (TRUE | FALSE) "FALSE"

>

23.2.21.1 Attributes

FETCHLET_ID: Specifies the ID of the fetchlet to use that is known to the EMAgent. This attribute must point to an element from the $ORACLE_HOME/lib/fetchlets.reg file.

NEED_CHARSET_CONVERT: If the metric result is in correct "UTF8" encoding, this flag should be set to "FALSE" so that EMAgent will not do any character conversion.

TRUE (default) | FALSE

REMOTE: This attribute enables the agent to select the appropriate QueryDescriptor based on whether the target is local or remote. A single QueryDescriptor with REMOTE=false indicates that the same querydescriptor will be used for local and remote targets. A single QueryDescriptor with REMOTE=true indicates that the querydescriptor will be used ONLY if the target is remote and skipped if the target is remote. If there are 2 QueryDescriptors one with REMOTE=true, the other MUST be REMOTE=false.

TRUE | FALSE (default)

ON_TARGET: A value of TRUE indicates that the metric must be evaluated on the target whereever it may be. For a local target, this attribute is ignored. For a remote target, the metric is evaluated over SSH.

TRUE | FALSE (default)

23.2.21.2 Elements

ValidIf

Property

23.2.21.3 Used In

Metric

DynamicProperties

23.2.21.4 Examples

The query descriptor associated will contain the metadata that can be used to collect the value of the metric. For example: SQL Query.

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

<Metric NAME=”prop” TYPE=”TABLE”>

<TableDescriptor>

<ColumnDescriptor NAME="name" TYPE="STRING" IS_KEY="TRUE" />

<ColumnDescriptor NAME="value" TYPE="STRING" />

</TableDescriptor>

<QueryDescriptor FETCHLET_ID="OS">

<Property NAME="hostname" SCOPE="INSTANCE">NAME</Property>

</QueryDescriptor>

</Metric>

</TargetMetadata>

This simple example describes a query descriptor that is used in a Metric and relies on the &rsquor;OS' fetchlet to return the property &rsquor;hostname'.

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

<Metric NAME=”prop” TYPE=”TABLE”>

. . .

</Metric>

<InstanceProperties>

<DynamicProperties NAME="VersionAndLocation" FORMAT="ROW" PROP_LIST="OS;OracleHome;Version">

<QueryDescriptor FETCHLET_ID="OSLineToken">

<Property NAME="ENVEmdOS" SCOPE="SYSTEMGLOBAL">_emdOS</Property>

<Property NAME="ENVVersion" SCOPE="SYSTEMGLOBAL">_emdVersion</Property>

<Property NAME="ENVORACLE_HOME" SCOPE="SYSTEMGLOBAL">emdRoot</Property>

</QueryDescriptor>

</DynamicProperties>

</InstanceProperties>

</TargetMetadata>

This example illustrates the use of a QueryDescriptor to evaluate a DynamicProperties element.

23.2.22 Property

Describes the information to be passed to the fetchlets.

<!ELEMENT Property (#PCDATA)>

<!ATTLIST Property

NAME CDATA #REQUIRED

SCOPE (GLOBAL | INSTANCE | USER | SYSTEMGLOBAL | ENV | HOST | CACHE) "GLOBAL"

OPTIONAL (TRUE | FALSE) "FALSE">

Property values are resolved as follows:

1. The value is looked up in the specified scope

2. For each potential instantiation (ie %<varname>%) in the looked up value, varname is looked up as follows:

a. In the property values itself (ie in one of the earlier properties).

b. In the instance properties

c. In the systemglobal scope (emd.properties)

d. The value is checked for automatic property.

The following Automatic Properties are defined for a target:

1. NAME - substitutes Target Name

2. TYPE - substitutes Target type

3. DISPLAY_NAME – substitutes display name for the target

4. TYPE_DISPLAY_NAME – substitutes display name for the type

5. GUID – substitutes the guid

Note:

All lookups are case-sensitive.

23.2.22.1 Attributes

NAME: Name of the property.

SCOPE: Defines how the value of the property is to be resolved.

Supported values for Scope are:

a) GLOBAL (default): The property needs to be resolved in the Target Type Definition XML file.

b) INSTANCE: The property will be resolved by discovery. The PCDATA in that case should be the NAME of the property set in the discovery XML file.

c) USER: The property will be resolved by the caller(collector or the interactive end-user). The PCDATA in that case should be the name of the Property to be used when prompting the caller (in the case of interactive user).

d) SYSTEMGLOBAL: Use emd.properties to resolve the property.

e) ENV: Use environment variable to resolve the property.

f) HOST: The property must be resolved as an instance variable of the 'host' target on that EMAgent. For example, the OS property

g) CACHE: The value must be obtained from the previous evaluation of the metric. Any column returned in the previous evaluation can be specified, and this is only applicable to single row OR non-key metrics.

OPTIONAL: is meant to call out those properties that need NOT be available when provided to the fetchlet. The EMAgent will validate that it can find valid values for all non-optional properties before calling through to a fetchlet.

TRUE | FALSE (default)

23.2.22.2 Elements

Contains character data representing the value for the property.

23.2.22.3 Used In

QueryDescriptor

PushDescription

23.2.22.4 Examples

<Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>

&rsquor;perlBin' Property has &rsquor;SYSTEMGLOBAL' scope which implies that emd.properties file is used to resolve the property

<Property NAME="delimiter" SCOPE="GLOBAL">|</Property>

&rsquor;delimiter' property has &rsquor;GLOBAL' scope.

<Property NAME="hostname" SCOPE="INSTANCE">NAME</Property>

&rsquor;hostname' has &rsquor;INSTANCE' scope which implies that the value will be resolved by discovery. The value &rsquor;NAME' must match the field in the discovery XML file.

<Property NAME="SNAPSHOT_TYPE" SCOPE="USER">SNAPSHOT_TYPE</Property>

This property will be resolved by the caller. &rsquor;SNAPSHOT_TYPE' is the name of the property when prompting the caller.

<Property NAME="ENVNMUPM_TIMEOUT" OPTIONAL="TRUE" SCOPE="SYSTEMGLOBAL">NMUPM_TIMEOUT</Property>

The property, &rsquor;ENVNMUPM_TIMEOUT' is identified as an OPTIONAL property. All properties that are not OPTIONAL have to be validated by the EMAgent before the fetchlet is called.

Use of the property elements is illustrated in the following examples:

QueryDescriptor, ValidIf, TargetMetadata.

23.2.23 Label

This represents the Label that will be displayed in UI.

<!ELEMENT Label (#PCDATA)>

<!ATTLIST Label

NLSID CDATA #REQUIRED>

23.2.23.1 Attributes

NLSID: Will contain the ID used to lookup the string in to the resource bundle

23.2.23.2 Elements

Character data.

23.2.23.3 Used In

Display

23.2.23.4 Examples

This element must be present in the Display element.

<Label NLSID="host_load_cpuLoad">Run Queue Length (5 minute average)</Label>

This element is defined in a Display element and represents the label to display.

Refer to the example for Display.

23.2.24 ShortName

ShortName is the short representation of the Metric Display name it should be less than 12 characters in length.

<!ELEMENT ShortName (#PCDATA)>

<!ATTLIST ShortName

NLSID CDATA #REQUIRED>

23.2.24.1 Attributes

NLSID: Will contain the ID used to lookup the string in to the resource bundle

23.2.24.2 Elements

Character data.

23.2.24.3 Used In

Display

23.2.24.4 Examples

<ShortName NLSID="host_load_cpuLoad_short">CPU Load (5min)</ShortName>

This element is defined in a Display element and represents the short name to display.

Refer to the example for Display.

23.2.25 Icon

This represents the icon to be used.

<!ELEMENT Icon (#PCDATA)>

<!ATTLIST Icon

GIF CDATA #IMPLIED>

23.2.25.1 Attributes

GIF: Will contain the name and the filepath for the image to be displayed.

23.2.25.2 Elements

Character data.

23.2.25.3 Used In

Display

23.2.25.4 Examples

Refer to the example for Display.

23.2.26 Description

This holds the description of the displayed entity.

<!ELEMENT Description (#PCDATA)>

<!ATTLIST Description

NLSID CDATA #IMPLIED>

23.2.26.1 Attributes

NLSID: Will contain the ID used to lookup the string in to the resource bundle.

23.2.26.2 Elements

Character data.

23.2.26.3 Used In

Display

23.2.26.4 Examples

Refer to the example for Display.

23.2.27 Unit

This holds the Unit information for the displayed data.

There are some standard units and unit nls ids that are supported. Use the appropriate nls ids and display names for these standard units mentioned below. The translation for these system supported units (nls ids that start with "em__sys__"), is done at the system level and does not need to be translated on a per target type basis.

Supported Units:

Standard Percent: used for metrics who values are between 0 and 100%

NLSID: "em__sys__standard_percent"

Display: "%"

Usage: <Unit NLSID="em__sys__standard_percent">%</Unit>

Generic Percent: used for metrics who values can be in +ve and -ve percentages as well - like -50% or 200%

NLSID: "em__sys__generic_percent"

Display: "%"

Usage: <Unit NLSID="em__sys__generic_percent">%</Unit>

<!ELEMENT Unit (#PCDATA)>

<!ATTLIST Unit

NLSID CDATA #IMPLIED>

23.2.27.1 Attributes

NLSID: Will contain the ID used to lookup the string in to the resource bundle.

23.2.27.2 Elements

Character data.

23.2.27.3 Used In

Display

23.2.27.4 Examples

Refer to the example for Display.

23.2.28 MonitoringMode

MonitoringMode element indicates the mediator for data collection. Presence of this element in TargetMetadata element, indicates that the target is of cluster type. Mediation is required for a cluster type target to provide data collection consistency across all cluster type target agents. Cluster targets can be OMS mediated, Agent mediated or Repository mediated. MEDIATOR attribute specifies the mediation. CLUSTERDESCRIPTOR attribute points to the shared library that implements the cluster interfaces needed by the agent. This is applicable only for AgentMediated clusters.

<!ELEMENT MonitoringMode (ValidIf*)>

<!ATTLIST MonitoringMode

MEDIATOR (AgentMediated|OMSMediated) #REQUIRED

CLUSTERDESCRIPTOR CDATA #IMPLIED>

23.2.28.1 Attributes

MEDIATOR: Specifies the mediator to use.

Supported values are:

a) AgentMediated

b) OMSMediated

CLUSTERDESCRIPTOR: Describes the type of the cluster. This is applicable for Agent mediation only.

23.2.28.2 Elements

ValidIf

23.2.28.3 Used In

TargetMetadata

23.2.28.4 Examples

<TargetMetadata META_VER=”2.0” TYPE=”example1” CATEGORY_PROPERTIES=”OS;OSVersion”>

. . .

<MonitoringMode MEDIATOR=”OMSMediated”>

<ValidIf>

<CategoryProp NAME=”OSVersion” CHOICES=”5.8”/>

<CategoryProp NAME=”OSVersion” CHOICES=”5.9”/>

</ValidIf

</MonitoringMode>

. . .

</TargetMetadata>

This example indicates the target, &rsquor;example1' is of cluster type and is OMS Mediated only for the OSVersions 5.8 and 5.9. For the other versions it acts like a normal target. All the Management Agents would monitor the target. Absence of this element makes the target a normal target.

23.2.29 AltSkipCondition

The agent has logic to skip evaluation of metrics for targets that are known to be down to reduce generation of metric errors due to connection failures. Metrics are skipped whenever there is an error in evaluating the Response metric or there is a non-clear severity on the Response, Status condition. If a target needs to have its metric evaluation stop on a condition other than the Response, Status column, this can be specified by creating an AltSkipCondition element.

<!ELEMENT AltSkipCondition EMPTY >

<!ATTLIST AltSkipCondition

METRIC CDATA #REQUIRED

COLUMN CDATA #REQUIRED

ASSOC_TARGET CDATA #IMPLIED>

23.2.29.1 Attributes

METRIC: Name of the result metric

COLUMN: Name of the column

ASSOC_TARGET: may be used to point to the conditions in an associated target.

23.2.29.2 Elements

None.

23.2.29.3 Used In

TargetMetadata

23.2.29.4 Examples

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

<AltSkipCondition METRIC=”metric1” COLUMN=”Status”/>

<Metric NAME=”Response” TYPE=”TABLE”>

<TableDescriptor>

<ColumnDescriptor NAME="Status" TYPE="NUMBER" IS_KEY="FALSE"/>

</TableDescriptor>

<QueryDescriptor FETCHLET_ID="OS">

<Property NAME="hostname" SCOPE="INSTANCE">NAME</Property>

</QueryDescriptor>

</Metric>

<Metric NAME=”metric1” TYPE=”TABLE”>

<TableDescriptor>

<ColumnDescriptor NAME="Status" TYPE="NUMBER" IS_KEY="FALSE"/>

</TableDescriptor>

<QueryDescriptor FETCHLET_ID="OS">

<Property NAME="homedir" SCOPE="INSTANCE">home</Property>

</QueryDescriptor>

</Metric>

</TargetMetadata>

This example describes a target whose metric evaluation will be skipped whenever there is an error in evaluating the Response metric or there is a non-clear severity on the Response Status column. In addition to that, metric evaluation will be skipped if errors or non-clear severity are encountered on the Status column of the &rsquor;metric1' metric as well.

<AltSkipCondition METRIC=”Response” COLUMN=”State” ASSOC_TARGET=”t2”/>

If the &rsquor;example1' target type in the above example was associated with another target type. The AltSkipCondition can be used to skip evaluating example1's metric based on Response metric's &rsquor;State' column in the other target type.

The association &rsquor;t2' has to be defined in the targets.xml file for example1.

23.2.30 CredentialInfo

Credential types are metadata for sets of credentials. They describes the components of the credential (CredentialTypeColumns), which is the key etc. In some cases, CredentialTypes may be composed of existing CredentialTypes (in this or other target types)

CredentialSets are the instances of CredentialTypes that apply to a particular target. Of particular importance are the monitoring credential sets whose values are mapped to the instance properties of the target.

<!ELEMENT CredentialInfo (CredentialType*, CredentialSet*)>

23.2.30.1 Attributes

None.

23.2.30.2 Elements

CredentialType

CredentialSet

23.2.30.3 Used In

TargetMetadata

23.2.30.4 Examples

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

. . .

<CredentialInfo>

<CredentialType NAME="DBCreds" >

<CredentialTypeColumn NAME="DBUsername" IS_KEY="true" />

<CredentialTypeColumn NAME="DBPassword" />

<CredentialTypeColumn NAME="DBRole" />

</CredentialType>

<CredentialSet NAME="DBCredsMonitoring" CREDENTIAL_TYPE="DBCreds" USAGE="monitoring">

<CredentialSetColumn TYPE_COLUMN="DBUsername" SET_COLUMN="UserName" />

<CredentialSetColumn TYPE_COLUMN="DBPassword" SET_COLUMN="password" />

<CredentialSetColumn TYPE_COLUMN="DBRole" SET_COLUMN="role" />

</CredentialSet>

<CredentialSet NAME="DBCredsSysdba" CREDENTIAL_TYPE="DBCreds" USAGE="monitoring">

<CredentialSetColumn TYPE_COLUMN="DBUsername" SET_COLUMN="SYSDBAUserName" />

<CredentialSetColumn TYPE_COLUMN="DBPassword" SET_COLUMN="SYSDBApassword" />

<CredentialSetColumn TYPE_COLUMN="DBRole" SET_COLUMN="SYSDBArole" />

</CredentialSet>

</CredentialInfo>

. . .

</TargetMetadata>

CredentialInfo may have CredentialType and CredentialSet elements. This is illustrated in this example. Target type, &rsquor;example1' is associated with &rsquor;DBCreds', &rsquor;DBCredsMonitoring' and &rsquor;DBCredsSysdba' credentials.

23.2.31 CredentialType

CredentialType elements contain the description of a type as composed of component columns (one of which may be the key) or as a composite of other predefined credential types.

<!ELEMENT CredentialType (Display?, (CredentialTypeColumn|CredentialTypeRef)+)>

<!ATTLIST CredentialType

NAME CDATA #REQUIRED>

23.2.31.1 Attributes

NAME: Unique Name of the CredentialType

23.2.31.3 Used In

CredentialInfo

23.2.31.4 Examples

CredentialType may contain an optional Display element specifying the display characteristics for the CrendentialType and one or more of either the CredentialTypeColumn or the CredentialTypeRef.

<CredentialType NAME="HostCreds" >

<CredentialTypeColumn NAME="HostUserName" IS_KEY="TRUE">

<CredentialTypeColumn NAME="HostPassword">

</CredentialType>

In this sample &rsquor;HostCreds' is declared as a CredentialType. Refer to a more detailed example in CredentialInfo.

23.2.32 CredentialTypeColumn

CredentialType is defined as a set of Credential Columns. Each CredentialTypeColumn may provide a list of values that are the only allowed values for this column.

<!ELEMENT CredentialTypeColumn (Display?, CredentialTypeColumnValue*)>

<!ATTLIST CredentialTypeColumn

NAME CDATA #REQUIRED

IS_KEY (TRUE|FALSE) "FALSE">

23.2.32.1 Attributes

NAME: Name of the column

IS_KEY: If multiple sets are created of this credential type, is this the column by which one set is differentiated from another.

TRUE | FALSE (default)

23.2.32.2 Elements

Display

CredentialTypeColumnValue

23.2.32.3 Used In

CredentialType

23.2.32.4 Examples

CredentialTypeColumn may contain an optional Display element specifying the display characteristics for the CredentialTypeColumn and optional CredentialTypeColumnValue element(s).

<CredentialTypeColumn NAME="HostUserName" IS_KEY="TRUE">

<Display FOR_SUMMARY_UI="TRUE">

<Label NLSID="host_username">UserName</Label>

</Display>

</CredentialTypeColumn>

The HostUserName column is the key in a (username,password) credential type. This column would be displayed in a condensed version of the UI and the label associated with this is &rsquor;UserName'. Refer to a more detailed example in CredentialInfo.

23.2.33 CredentialTypeColumnValue

CredentialTypeColumnValue holds the allowed values for a CredentialTypeColumn.

<!ELEMENT CredentialTypeColumnValue (#PCDATA)>

<!ATTLIST CredentialTypeColumnValue

IS_DEFAULT (TRUE|FALSE) "FALSE">

23.2.33.1 Attributes

IS_DEFAULT: Is set to true if this is the default value in the list.

TRUE | FALSE (default)

23.2.33.2 Elements

Character data representing the value

23.2.33.3 Used In

CredentialTypeColumn

23.2.33.4 Examples

<CredentialType NAME="DBCreds" >

<CredentialTypeColumn NAME="DBUsername" IS_KEY="true" />

<CredentialTypeColumn NAME="DBPassword" />

<CredentialTypeColumn NAME="DBRole">

<CredentialTypeColumnValue IS_DEFAULT="true">normal</CredentialTypeColumnValue>

<CredentialTypeColumnValue>sysdba</CredentialTypeColumnValue>

</CredentialTypeColumn>

</CredentialType>

The &rsquor;DBRole' column in &rsquor;DBCreds' credential type may have the following values:

1. normal (default value)

2. sysdba

Refer to the example in CredentialInfo. The example shows the context for the CredentialType element

23.2.34 CredentialTypeRef

This element allows a credential type to refer to other predefined credential types. It contains mapping of the columns in the original credential type to columns of the credential type being defined.

<!ELEMENT CredentialTypeRef (CredentialTypeRefColumn*)>
<!ATTLIST CredentialTypeRef
REF_NAME        CDATA #REQUIRED
REF_TYPE        CDATA #REQUIRED
REF_TARGETTYPE  CDATA #IMPLIED
ASSOCIATION     CDATA #IMPLIED>

23.2.34.1 Attributes

REF_NAME: Specifies the name for this CredentialTypeRef.

REF_TYPE: Credential type referred to.

REF_TARGETTYPE: The target type that contains the original credential type. Specify Null if this is the same target type.

ASSOCIATION: Refers to the association of this target with the other target for whom credentials are maintained here. Note that this value needs to be one of the AssocTarget elements above.

23.2.34.2 Elements

CredentialTypeRefColumn

23.2.34.3 Used In

CredentialType

23.2.34.4 Examples

<CredentialType NAME="FMCreds" >
<CredentialTypeRef NAME="FMDBCreds1" REF_TYPE="DBCreds" REF_TARGET_TYPE="oracle_database" ASSOCIATION="firstDB">       
<CredentialTypeRefColumn NAME="FMUserName1" REF_TYPECOLUMN="DBUsername" />
<CredentialTypeRefColumn NAME="FMpassword1" REF_TYPECOLUMN="DBPassword" />
<CredentialTypeRefColumn NAME="FMRole1" REF_TYPECOLUMN="DBRole" />
                        </CredentialTypeRef>
</CredentialType>

FMCreds defines a credential type whose columns FMUserName1, Fmpassword1 and FMRole are mapped to DBCred's DBUsername, DBPassword and DBRole columns respectively.

Refer to the example in CredentialInfo. The example shows the context for the CredentialType element

23.2.35 CredentialTypeRefColumn

This element maps the columns in the referred credential type to this credential type's columns.

<!ELEMENT CredentialTypeRefColumn EMPTY>
<!ATTLIST CredentialTypeRefColumn
          NAME            CDATA #REQUIRED
          REF_TYPECOLUMN  CDATA #REQUIRED>

23.2.35.1 Attributes

NAME: Name of column in this credential type.

REF_TYPECOLUMN: Name of the column in the referred credential type

23.2.35.2 Elements

None

23.2.35.3 Used In

CredentialTypeRef

23.2.35.4 Examples

Refer to the examples for CredentialTypeRef.

23.2.36 CredentialSet

This element defines a set of elements that form a named credential set for this target type. A credential set provides values for one of the credential types defined for this target type. The credential set may contain credentials for one of 3 usages: monitoring, preferred credentials or app specific functionality.

<!ELEMENT CredentialSet (Display?, CredentialSetColumn+)>
<!ATTLIST CredentialSet
          NAME             CDATA  #REQUIRED
          CREDENTIAL_TYPE  CDATA  #REQUIRED
          USAGE    (MONITORING|PREFERRED_CRED|SYSTEM) "MONITORING"
          CONTEXT_TYPE     (TARGET|CONTAINER|COLLECTION) "TARGET"
          CONTEXT          CDATA  #IMPLIED>

23.2.36.1 Attributes

NAME: Name of the credential set

CREDENTIAL_TYPE: The credential type that this set provides values for.

USAGE: Is this credential set used for monitoring, as preferred credentials or for app specific stuff?Supported values are:

  • MONITORING (default): Specifies credentials that management applications can use to connect directly to the target.

  • PREFERRED_CRED: Specifies a user's preferred credentials.

  • SYSTEM: Specifies a fixed set of credentials that are used by certain specialized applications (patching, cloning etc.)

  • CONTEXT_TYPE: Specifies what kind of entity, the set pertains to.

    Supported values are:

    • TARGET (default): These are the stored credentials for a target that could be used by applications such as job system, patch etc.

    • CONTAINER: These are the stored credentials for a container. These are always host credentials.

    • COLLECTION: These are credentials associated with user-defined metrics.

  • CONTEXT: Specifies the metric that this set is for. Refers to collection credentials only.

23.2.36.2 Elements

Display

CredentialSetColumn

23.2.36.3 Used In

CredentialInfo

23.2.36.4 Examples

CredentialSet contains an optional Display element that specifies the display characteristics for the CredentialSet element and at least 1 CredentialSetColumn.

<CredentialSet NAME="HostPrefCreds" CREDENTIAL_TYPE="HostCreds" USAGE="PREFERRED_CRED">
     <CredentialSetColumn TYPE_COLUMN="HostUsername" SET_COLUMN="HostPrefUserName" />\
     <CredentialSetColumn TYPE_COLUMN="HostPassword" SET_COLUMN="HostPrefPassword" />
</CredentialSet>

This sample illustrates usage of a user credential set.

<CredentialSet NAME="DBCredsMonitoring" CREDENTIAL_TYPE="DBCreds" USAGE="monitoring">
     <CredentialSetColumn TYPE_COLUMN="DBUsername" SET_COLUMN="UserName"/>
     <CredentialSetColumn TYPE_COLUMN="DBPassword" SET_COLUMN="password"/>
     <CredentialSetColumn TYPE_COLUMN="DBRole" SET_COLUMN="role"/>
</CredentialSet>

DBCredsMonitoring defines a credential set that may be used by the agent for monitoring a database.

<CredentialSet NAME="HostSystemCreds" CREDENTIAL_TYPE="HostCreds" USAGE="SYSTEM">
    <CredentialSetColumn TYPE_COLUMN="HostUsername" SET_COLUMN="HostPrefUserName"/>
    <CredentialSetColumn TYPE_COLUMN="HostPassword" SET_COLUMN="HostPrefPassword"/>
</CredentialSet>

HostSystemCreds is an example of a System credential type.

Refer to the example in CredentialInfo. The example shows the context for the CredentialType element.

23.2.37 CredentialSetColumn

Credential set columns map the columns of a credential type to the source of their values. In the case of monitoring credential sets, the source is instance properties of the target.

<!ELEMENT CredentialSetColumn (Display?, CredentialSetColumnValue*) >
<!ATTLIST CredentialSetColumn
          TYPE_COLUMN CDATA #REQUIRED
          SET_COLUMN  CDATA #REQUIRED>

23.2.37.1 Attributes

TYPE_COLUMN: Name of the column in the CredentialType.

SET_COLUMN

23.2.37.2 Elements

Display

CredentialSetColumnValue

23.2.37.3 Used In

CredentialSet

23.2.37.4 Examples

CredentialSetColumn contains an optional Display element that specifies the display characteristics for the CredentialSetColumn element and optional CredentialSetColumnValue element(s).

Refer to the example for CredentialSet

23.2.38 CredentialSetColumnValue

This element holds the allowed values for a CredentialSetColumn.

<!ELEMENT CredentialSetColumnValue (#PCDATA)>
<!ATTLIST CredentialSetColumnValue
          IS_DEFAULT (TRUE|FALSE) "FALSE">

23.2.38.1 Attributes

IS_DEFAULT: Set this attribute to true if the element represents the default value in the list.

23.2.38.2 Elements

Character data representing the value.

23.2.38.3 Used In

CredentialSetColumn

23.2.38.4 Examples

Refer to the example for CredentialSet.

23.2.39 InstanceProperties

The InstanceProperties element declares the "properties" of a target type. Some properties are obtained from the targets.xml file, and may be optional or required, and others can be computed using DynamicProperties elements using the values of other properties.

The Agent uses the information in the InstanceProperties element to determine when a target has not been sufficiently configured, and to compute the dynamic properties for the target. The console UIs use the information about the properties to create UIs where a target can be created from scratch or an existing target's properties are modified.

InstanceProperties holds target InstanceProperty(s) and DynamicProperties elements.

<!ELEMENT InstanceProperties ((InstanceProperty | DynamicProperties)*)>

23.2.39.1 Attributes

None

23.2.39.2 Elements

InstanceProperty

DynamicProperties

23.2.39.3 Used In

TargetMetadata

23.2.39.4 Examples

Refer to the example for QueryDescriptor and TargetMetadata.

23.2.40 InstanceProperty

An InstanceProperty element contains the definition of an instance property.

<!ELEMENT InstanceProperty (ValidIf*, (PCDATA | Display)*)>
<!ATTLIST InstanceProperty
NAME CDATA #REQUIRED
OPTIONAL (TRUE | FALSE) "FALSE"
IN_PRIMARY_KEY (TRUE | FALSE) "FALSE"
CHECK_FOR_MODIFIABLE (TRUE | FALSE) "FALSE"
CREDENTIAL (TRUE | FALSE) "FALSE"
READONLY (TRUE | FALSE) "FALSE"
NEED_REENTER ( TRUE | FALSE) "FALSE"
HIDE_ENTRY ( TRUE | FALSE) "TRUE"
CHECK_ORIGINAL ( TRUE | FALSE) "FALSE"
IS_COMPUTED (TRUE|FALSE) "FALSE"
WAS_REQUIRED (FALSE|TRUE) "FALSE"
>

23.2.40.1 Attributes

NAME: Name of the property

OPTIONAL: Is a value for the property required

TRUE | FALSE (default)

CREDENTIAL: Is the property sensitive in nature. Such properties are usually saved obfuscated in targets.xml

TRUE | FALSE (default)

READONLY: Marks this element as ReadOnly.

TRUE | FALSE (default)

NEED_REENTER: If TRUE, will require user to enter the value twice at command line.

TRUE | FALSE (default)

HIDE_ENTRY: If TRUE, will show the character user typed as '*'.

TRUE (default) | FALSE

CHECK_ORIGINAL: If TRUE, before modify, user need to type the original value.

IS_COMPUTED: If TRUE, indicates that it describes a dynamic property.

WAS_REQUIRED: This was an instance property that was required prior to 10.2 but is now a dynamic property. This property would be sent to 10.1 OMS if set to TRUE. Default value is FALSE (See bug/ER 4631553 for more details).

23.2.40.2 Elements

ValidIf

Display

23.2.40.3 Used In

TargetMetadata

23.2.40.4 Examples

If InstanceProperty element contains ValidIf elements, all the conditions must be met for the property to be evaluated. InstanceProperty also optionally contains either Display elements or character data.

<InstanceProperty NAME="password" OPTIONAL="FALSE" CREDENTIAL="TRUE">

Example: for an oracle_database target one InstanceProperty has the NAME "password", which is not OPTIONAL and which is a "CREDENTIAL".

Refer to additional examples for InstanceProperty described in TargetMetadata

23.2.41 DynamicProperties

DynamicProperties elements allow a target to specify a query that will return a set of values corresponding to the instance properties of the target. The values are turned into target properties and are accessible to other query descriptors from the INSTANCE scope.

<!ELEMENT DynamicProperties (ValidIf*, (QueryDescriptor | ExecutionDescriptor)+) >
<!ATTLIST DynamicProperties
NAME CDATA #REQUIRED
PROP_LIST CDATA #IMPLIED
OPT_PROP_LIST CDATA #IMPLIED
FORMAT (TABLE | ROW) "TABLE"
IS_CRITICAL (TRUE | FALSE) "FALSE"
>

Note:

If CategoryProperties are instantiated through DynamicProperty evaluation, such a failed DynamicProperty evaluation would cause the agent to reject the target unless the value of the category property is available in targets.xml.

23.2.41.1 Attributes

NAME: attribute simply identifies the property collector, for error tracing etc.

PROP_LIST: Contains &rsquor;;' separated values that specify a list of names of properties that can be returned by the query descriptor. The result MUST contain the properties listed here.

OPT_PROP_LIST: Contains &rsquor;;' separated values that specify a list of names of properties that can be returned by the query descriptor. The result MAY contain the properties listed here.

FORMAT: Specifies the format for the return data.

Supported values are:

  • TABLE (default): If the FORMAT is "TABLE" (the default), the return value must be a table of instance property values. The table returned must be a two-column (NAME, VALUE) table.

  • ROW: If the FORMAT is "ROW", the contents of the one row are taken as the values of the properties in the same order they are listed in the PROP_LIST, and then in the OPT_PROP_LIST lists.

IS_CRITICAL: To denote that a dynamic property is cirtical for the target one can specify the IS_CRITICAL flag attribute. The default value of this flag is FALSE and is assumed if this attribute is not present. When the value of this attribute is specified as TRUE, then on failure / timeout during computation of that dynamic property, we reschedule the computation of all dynamic / instance properties of that target as per the values of parameters given in the emd.properties file.

23.2.41.3 Used In

InstanceProperties

23.2.41.4 Examples

If DynamicProperties element contains ValidIf elements, all the conditions must be met for the property to be evaluated. In addition to this it must also include at least 1 instance of either QueryDescriptor or ExecutionDescriptor.

The property names in the PROP_LIST and OPT_PROP_LIST are used in conjunction with InstanceProperty declarations while validating target type metadata.

<DynamicProperties NAME="VersionAndLocation" FORMAT="ROW" PROP_LIST="OS;OracleHome;Version">

DynamicProperties, &rsquor;VersionAndLocation' has a ROW format and returns &rsquor;OS', &rsquor;OracleHome', &rsquor;Version' as properties.

Note that if a query descriptor returns a property value that is already available, the property is ignored. If multiple DynamicProperties queries return a property, the value from the first one is used.

The example in TargetMetadata includes the context for DynamicProperties element.

23.2.42 ExecutionDescriptor

ExecutionDescriptor specifies the execution plan for evaluating a metric. MAgent executes 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.

<!ELEMENT ExecutionDescriptor (ValidIf*, (GetTable | GetView | GroupBy | Union | JoinTables)*)>

23.2.42.1 Attributes

None

23.2.42.3 Used In

Metric

DynamicProperties

23.2.42.4 Examples

If ExecutionDescriptor element contains ValidIf elements, all the conditions must be met for the element to be evaluated. In addition to this it must also include 0 or more instances of either 1 of the following elements: GetTable, GetView, GroupBy, Union, JoinTables

ExecutionDescriptor is used to compute aggregation metric.

<TargetMetadata META_VER=”3.0” TYPE=”host”>
. . .
<Metric NAME=”Load” TYPE=”TABLE”>
. . .
 
<ExecutionDescriptor>
<GetTable NAME="DiskActivity"/>
<GetView NAME="AvgSrvcTimeView" FROM_TABLE="DiskActivity">
   <Column NAME="DiskActivityavserv"/>
</GetView>
<GroupBy NAME="DA_MaxAvServ" FROM_TABLE="AvgSrvcTimeView">
<AggregateColumn NAME="longestServ" COLUMN_NAME="DiskActivityavserv" OPERATOR="MAX" />
</GroupBy>
<GetTable NAME="_LoadInternal"/>
<JoinTables NAME="Load">
<Table NAME="_LoadInternal"/>
<Table NAME="DA_MaxAvServ"/>
</JoinTables>
</ExecutionDescriptor>
</Metric>
 
<Metric NAME="_LoadInternal" TYPE="TABLE" USAGE_TYPE="HIDDEN">
   . . .
</Metric>
 
<Metric NAME="DiskActivity" TYPE="TABLE">
   . . .
</Metric>
 
                  </TargetMetadata>
 
This ExecutionDescriptor in this sample generates the following intermediate Metric results after executing each statement:
§         GetTable: The metric result, &rsquor;DiskActivity' contains all the columns of &rsquor;DiskActivity' metric.  The result of this operation is similar to the SQL statement,
”Select * from DiskActivity”
§         GetView: The metric result, &rsquor;AvgSrvcTimeView' contains only &rsquor;DiskActivityavserv' column of &rsquor;DiskActivity' metric.
§         GroupBy: Metric result, &rsquor;DA_MaxAvServ' is a grouping of the &rsquor;AvgSrvcTimeView' based on the &rsquor;longestServ' which is the max value of the &rsquor;DiskActivityavserv' column.
§         GetTable: Metric result, &rsquor;_LoadInternal' contains all the columns of the &rsquor;_LoadInternal' metric.
§         JoinTable: &rsquor;Load' metric contains a join of the &rsquor;_LoadInternal' and &rsquor;DA_MaxAvServ' metrics.

The last metric is returned as the result for the &rsquor;Load' metric.

23.2.43 GetTable

This element is used within an ExecutionDescriptor element and is equivalent to the following SQL operation:

Select * from T.

T is a metric.

<!ELEMENT GetTable EMPTY>
<!ATTLIST GetTable
      NAME CDATA #REQUIRED
      ASSOC_TARGET CDATA #IMPLIED
      METRIC_NAME CDATA #IMPLIED
      USE_CACHE (TRUE | FALSE | TRUE_IF_COLLECT) "FALSE">

23.2.43.1 Attributes

NAME: Name of the metric.

ASSOC_TARGET: Target from which data is collected. This attribute is optional and when omitted, the METRIC_NAME points at a metric in the same target.

METRIC_NAME: Name of the metric that originates the request. If omitted, attribute NAME is used as METRIC_NAME.

USE_CACHE: Specifies whether the data can be fetched from the cache.

TRUE | FALSE (default) | TRUE_IF_COLLECT

23.2.43.2 Elements

None

23.2.43.3 Used In

ExecutionDescriptor

23.2.43.4 Examples

<GetTable NAME="DiskActivity"/>

This statement gets all the columns of the &rsquor;DiskActivity' metric.

Refer to the example in ExecutionDescriptor.

23.2.44 GetView

GetView creates a sub-table from a table. The newly created table is identified by the NAME attribute. It must be unique in the ExecutionDescriptor. This element is equivalent to the following SQL statement:

Select column1, column2,. . . from T

T is a metric.

<!ELEMENT GetView ((ComputeColumn | Column)*, (Filter | In)*)>
<!ATTLIST GetView
      NAME CDATA #REQUIRED
      FROM_TABLE CDATA #REQUIRED>

23.2.44.1 Attributes

NAME: Name of the view.

FROM_TABLE: Table from which to generate the view.

23.2.44.2 Elements

ComputeColumn

Column

Filter

In

23.2.44.3 Used In

ExecutionDescriptor

23.2.44.4 Examples

GetView may contain 0 or more instances of either &rsquor;ComputeColumn' or &rsquor;Column' elements and 0 or more instances of either &rsquor;Filter' or &rsquor;In' elements.

<GetView NAME="AvgSrvcTimeView" FROM_TABLE="DiskActivity">
                        <Column NAME="DiskActivityavserv"/>
      </GetView>

This is equivalent to the following SQL statement:

create view AvgSrvcTimeView as
select DiskActivityavserv from DiskActivity.

If no Column elements are present in GetView, all columns in the table are included.

Refer to the example in ExecutionDescriptor.

23.2.45 Filter

Specifies the filter criteria. Filter is used to determine whether a row will be included in the new table. If a row does not satisfy any Filter criteria, it will be excluded.

<!ELEMENT Filter (#PCDATA)>
<!ATTLIST Filter
      COLUMN_NAME CDATA #REQUIRED
      SCOPE (GLOBAL | INSTANCE | SYSTEMGLOBAL) "GLOBAL"
OPERATOR (EQ | LT | GT | LE | GE | NE | CONTAINS | MATCH | ISNULL | ISNOTNULL) "EQ">

23.2.45.1 Attributes

COLUMN_NAME: Column name on which the filter criteria is to be applied.

SCOPE:

Supported values are:

  • GLOBAL (default)

  • INSTANCE

  • SYSTEMGLOBAL

  • OPERATOR: Specifies the operation to perform.

Supported operators are:

  • EQ (default): Equal

  • LT: Less than

  • GT: Greater than

  • LE: Less than or equal to

  • GE: Greater than or equal to

  • NE: Not equals

  • CONTAINS: contains

  • MATCH: matches

  • ISNULL: is NULL

  • SNOTNULL: is not NULL

23.2.45.2 Elements

Character data representing the filter criteria.

23.2.45.3 Used In

GetView

23.2.45.4 Examples

<ExecutionDescriptor>
    <GetTable NAME="Servlet_raw" USE_CACHE="TRUE_IF_COLLECT"/>
    <GetView  NAME="result" FROM_TABLE="Servlet_raw">
        <Filter COLUMN_NAME="totalRequests1" OPERATOR="GT">0</Filter>
    </GetView>
</ExecutionDescriptor>

The result of the ExecutionDescriptor is the metric &rsquor;result' that has totalRequests1 > 0.

23.2.46 Column

Represents a column to include in the new table.

<!ELEMENT Column EMPTY>
<!ATTLIST Column
      NAME CDATA #REQUIRED
      COLUMN_NAME CDATA #IMPLIED
      TABLE_NAME CDATA #IMPLIED>

23.2.46.1 Attributes

NAME: Specifies the name of the column of a metric.

COLUMN_NAME: Specifies the name of the column. It can be omitted if it is same as NAME.

TABLE_NAME: Specifies the name of the metric. If Column is a part of the GetView element, this attribute must be excluded.

23.2.46.2 Elements

None

23.2.46.3 Used In

GetView

JoinTables

23.2.46.4 Examples

<Column NAME="DiskActivityavserv"/>

&rsquor;DiskActivityavserv' is the metric column that is selected for the operation.

<Column NAME="responseTime" TABLE_NAME="groupbyapps"/>

Column, &rsquor;responseTime' from &rsquor;groupbyapps' metric is selected for the operation.

Refer to the example in ExecutionDescriptor

23.2.47 ComputeColumn

This element describes how to compute the values of a column.

<!ELEMENT ComputeColumn EMPTY>
<!ATTLIST ComputeColumn
      NAME               CDATA #REQUIRED
      EXPR               CDATA #REQUIRED
      IS_VALUE           (TRUE | FALSE) "FALSE"
DEFAULT_WHEN_EMPTY (TRUE | FALSE) "FALSE"
DEFAULT_VALUE      CDATA #IMPLIED>

23.2.47.1 Attributes

NAME: Name of the column.

EXPR: Expression that is evaluated to calculate the value. Refer to the Examples of ColumnDescriptor for details about the expression grammar and usage.

IS_VALUE: If set to TRUE, the EXPR points to the actual string value else EXPR is the expression used to calculate the column.

TRUE | FALSE (default)

DEFAULT_WHEN_EMPTY:

TRUE | FALSE (default)

DEFAULT_VALUE: Default value for the column. If not specified the default value will be set to ”0”.

23.2.47.2 Elements

None

23.2.47.3 Used In

GetView

GroupBy

23.2.47.4 Examples

<GetView NAME="NEW_TABLE" FROM_TABLE="ORIG_TABLE">
<Column NAME="cn1" COLUMN_NAME="A" />
<Column NAME="cn2" COLUMN_NAME="B" />
<ComputeColumn NAME="cn3" EXPR="cn1+cn2" />
<ComputeColumn NAME="cn4" EXPR="cn1/cn2" DEFAULT_WHEN_EMPTY="TRUE" DEFAULT_VALUE="1"/>
<ComputeColumn NAME="isMultiThreaded.value" IS_VALUE="TRUE" EXPR="true" />
<Filter COLUMN_NAME="C" OPERATOR="EQ">3</Filter>
                  </GetView>

Refer to the Examples of ColumnDescriptor for details about the expression grammar and additional examples of expressions that are acceptable in the EXPR attribute.

23.2.48 In

This element is equivalent of the SQL Statement select * from from_table where column_name in ( select in_column_name from in_table_name)

<!ELEMENT In EMPTY>
<!ATTLIST In
      COLUMN_NAME CDATA #REQUIRED
      IN_TABLE_NAME CDATA #REQUIRED
      IN_COLUMN_NAME CDATA #REQUIRED>

23.2.48.1 Attributes

COLUMN_NAME: Column name to search for.

IN_TABLE_NAME: Table in which to search for.

IN_COLUMN_NAME: Column name of the table specified in IN_TABLE_NAME attribute.

23.2.48.2 Elements

None

23.2.48.3 Used In

GetView

23.2.49 GroupBy

GroupBy will perform aggregation operation on a table/view to create a new table. This element is equivalent to the SQL statement: Select sum(column_name) from table_name

<!ELEMENT GroupBy (By*, (AggregateColumn | ComputeColumn)*)>
<!ATTLIST GroupBy
      NAME CDATA #REQUIRED
      FROM_TABLE CDATA #REQUIRED>

23.2.49.1 Attributes

NAME: Specifies the name of the grouping.

FROM_TABLE: Specifies the name of the metric.

23.2.49.2 Elements

By

AggregateColumn

ComputeColumn

23.2.49.3 Used In

GetView

23.2.49.4 Examples

This element may include 0 or more elements of &rsquor;By' and 0 or more elements of either AggregateColumn or ComputeColumn.

<GroupBy NAME="DA_MaxAvServ" FROM_TABLE="AvgSrvcTimeView">

This statement results in DA_MaxAvServ containing the result of the groupby operation applied to the AvgSrvcTimeView metric.

Refer to the example in ExecutionDescriptor.

23.2.50 By

'By' element defines a column that constitutes a GroupBy clause. Each &rsquor;By' element will be added to the result table as a column.

<!ELEMENT By EMPTY>
<!ATTLIST By
      NAME CDATA #REQUIRED
      COLUMN_NAME CDATA #IMPLIED>

23.2.50.1 Attributes

NAME: Name of the new column.

COLUMN_NAME: name for the new column.

23.2.50.2 Elements

None

23.2.50.3 Used In

GroupBy

23.2.50.4 Examples

NAME must be unique within the new table. If COLUMN_NAME is not given, will be the same as NAME

23.2.51 AggregateColumn

This element describes an operation to be performed on a column.

<!ELEMENT AggregateColumn EMPTY>
<!ATTLIST AggregateColumn
      NAME CDATA #REQUIRED
      COLUMN_NAME CDATA #REQUIRED
      OPERATOR (MAX | MIN | SUM | AVG | COUNT) "SUM">

23.2.51.1 Attributes

NAME: Specifies the name of the AggregateColumn

COLUMN_NAME: Specifies the column name of the metric on which the operation is to be performed.

OPERATOR: Specifies the operation to be performed.

Supported operators are:

  • MAX

  • MIN

  • SUM (default)

  • AVG

  • COUNT

23.2.51.2 Elements

None

23.2.51.3 Used In

GroupBy

23.2.51.4 Examples

<AggregateColumn NAME="longestServ" COLUMN_NAME="DiskActivityavserv" OPERATOR="MAX" />

This operation results in the calculation of the Maximum value from the &rsquor;DiskActivityavserv' column.

Refer to the example in ExecutionDescriptor.

23.2.52 Union

Union element describes an operation to combine/merge two or more tables. Only tables with the same number of columns can be unioned together. This element is equivalent of the SQL statement:

Select * from T1 Union
Select * from T2
 
<!ELEMENT Union (Table+)>
<!ATTLIST Union
      NAME CDATA #REQUIRED
      DISTINCT (TRUE | FALSE) "FALSE">

23.2.52.1 Attributes

NAME: Specifies the name for the union.

DISTINCT: If TRUE, any row that is exactly the same as previous row will be discarded.

TRUE | FALSE (default)

23.2.52.2 Elements

Table

23.2.52.3 Used In

ExecutionDescriptor

23.2.52.4 Examples

Union element must include atleast 1 Table element.

<Union NAME="result4">
            <Table NAME="result" />
            <Table NAME="result1" />
            <Table NAME="result2" />
            <Table NAME="result3" />
       </Union> 

&rsquor;result4' will be a union of the 4 Tables. The resulting table will have the same column name list as first table.

Note:

Only tables with the same number of columns can be unioned together. The newly created table is identified by NAME. It must be unique in the ExecutionDescriptor.

23.2.53 Table

This element describes the metrics that can take part in Table operations like Union and JoinTables.

<!ELEMENT Table EMPTY>
<!ATTLIST Table
      NAME CDATA #REQUIRED>

23.2.53.1 Attributes

NAME: Specifies the name of the metric.

23.2.53.2 Elements

None

23.2.53.3 Used In

Union

JoinTables

23.2.53.4 Examples

<Table NAME="result" />

This example describes &rsquor;result' as a metric that can participate in Table operations.

Refer to the example of Union.

23.2.54 JoinTables

This element describes the join operation. It is equivalent of the SQL statement:

Select C1, C2 where . . .

<!ELEMENT JoinTables (Table, Table+, (Column | ComputeColumn)*, Where*)>
<!ATTLIST JoinTables
      NAME CDATA #REQUIRED
      OUTER (TRUE | FALSE) "FALSE"
      BOTH_SIDE (TRUE | FALSE) "FALSE">

23.2.54.1 Attributes

NAME: Specifies the name of the join.

OUTER: If true, specifies an OUTER join.

TRUE | FALSE (default).

BOTH_SIDE: If true, specifies BOTH_SIDE. The results would contain the same number of rows as a UNION.

TRUE | FALSE (default)

23.2.54.2 Elements

Table

Column

ComputeColumn

Where

23.2.54.3 Used In

ExecutionDescriptor

23.2.54.4 Examples

JoinTables must include atleast 2 &rsquor;Table' elements, 0 or more elements of either &rsquor;Column' or &rsquor;ComputeColumn' and 0 ore more elements of &rsquor;Where' element.

<JoinTables NAME="Load">
        <Table NAME="_LoadInternal"/>
        <Table NAME="DA_MaxAvServ"/>
      </JoinTables>

This example defines &rsquor;Load' as a join of &rsquor;_LoadInterval' and &rsquor;DA_MaxAvServ' metrics.

Refer to the example in ExecutionDescriptor.

23.2.55 Where

<!ELEMENT Where EMPTY>
<!ATTLIST Where
      FROM_TABLE CDATA #REQUIRED
      FROM_KEY CDATA #REQUIRED
      OPERATOR (EQ | GT | GE | LE | LT | NE | CONTAINS | MATCH) "EQ"
      JOIN_TABLE CDATA #REQUIRED
      JOIN_KEY CDATA #REQUIRED>

23.2.55.1 Attributes

FROM_TABLE:

FROM_KEY:

OPERATOR: Specifies the operator in the where clause.

Supported operators are:

  • EQ (default): Equals

  • GT: Greater than

  • GE: Greater than or equal to

  • LE: Less than or equal to

  • LT: Less than

  • NE: Not equals

  • CONTAINS: Contains

  • MATCH: matches

JOIN_TABLE:

JOIN_KEY:

23.2.55.2 Elements

None

23.2.55.3 Used In

JoinTables

23.2.55.4 Examples

<JoinTables NAME="all" OUTER="TRUE">
          <Table NAME="groupbyapps" />
          <Table NAME="groupbyappsejb" />
          <Column NAME="Application" TABLE_NAME="groupbyapps"/>
          <Column NAME="activeRequests" TABLE_NAME="groupbyapps"/>
          <Column NAME="responseTime" TABLE_NAME="groupbyapps"/>
          <Column NAME="activeMethods" TABLE_NAME="groupbyappsejb"/>
          <Column NAME="avgMethodExecTime" TABLE_NAME="groupbyappsejb"/>
                      <Where  FROM_TABLE="groupbyapps" JOIN_TABLE="groupbyappsejb"
                              FROM_KEY="Application"  JOIN_KEY="ApplicationName"/>
</JoinTables>

23.2.56 PushDescription

The push descriptor identifies a recvlet that is responsible for supplying data and/or events for a metric, and specifies data to be passed to that recvlet for each target. The name used for the recvlet here should match the recvlet name used in recvlets.reg.

<!ELEMENT PushDescriptor (ValidIf*, Property*) >
<!ATTLIST PushDescriptor
      RECVLET_ID CDATA #REQUIRED>

23.2.56.1 Attributes

RECVLET_ID: Specifies the ID of the recvlet to use that is known to the EMAgent. This attribute must point to an element from the $ORACLE_HOME/lib/recvlets.reg file.

23.2.56.2 Elements

ValidIf

Property

23.2.56.3 Used In

Metric

23.2.56.4 Examples

PushDescriptor may include 0 or more elements of &rsquor;ValidIf' and &rsquor;Property'.

<Metric . . .>
. . .
<PushDescriptor RECVLET_ID=”AQMetrics”>
<Property NAME=”QueueName” SCOPE=”GLOBAL”>ALERT_QUE</Property>
<Property NAME=”MachineName” SCOPE=”INSTANCE”>MachineName</Property>
<Property NAME=”Port” SCOPE=”INSTANCE”>Port</Property>
<Property NAME=”SID” SCOPE=”INSTANCE”>SID</Property>
<Property NAME=”UserName” SCOPE=”INSTANCE”>UserName</Property>
<Property NAME=”password” SCOPE=”INSTANCE”>password</Property>
<Property NAME=”Role” SCOPE=”INSTANCE”>Role</Property>
<Property NAME=”InstanceName” SCOPE=”INSTANCE”>InstanceName</Property>
<Property NAME=”KeyField” SCOPE=”GLOBAL”>OBJECT_NAME</Property>
<Property NAME=”KeyColumn” SCOPE=”GLOBAL”>name</Property>
</PushDescriptor>
                  </Metric>

The properties included in the PushDescriptor are passed to the &rsquor;AQMetrics' recvlet. This recvlet provides data and/or events for the metric.

23.3 Target Collection DTD Elements

Target Collection drives the background collection of metrics for the purposes of uploading their values in a central repository and/or the check of their values against specified conditions.

Note that the XML files conforming to this DTD will be generated by the system (Could be generated from Servlet Frontend or collector).

EMAgent can have more than one collection files each containing metrics that need to be collected for a particular target.

23.3.1 TargetCollection

A TargetCollection describes the metric that needs to be collected for a particular target. This element applies to both default collections (type level) and instance specific collections. NAME, LEVEL and INCLUDE_DEFAULT attributes apply only to instance specific collections.

It can have 0 or more CollectionItem and CollectionLevel elements. The CollectionLevel element applies only to the default collections.

<!ELEMENT TargetCollection  ( CollectionLevel*, CollectionItem* ) >
<!ATTLIST TargetCollection
  TYPE CDATA #REQUIRED
  NAME CDATA #IMPLIED
  LEVEL CDATA #IMPLIED
  INCLUDE_DEFAULT (TRUE|FALSE)  "TRUE">

23.3.1.1 Attributes

TYPE: Specifies the target type.

NAME: Specifies the name of the target. If this is the top-level element, NAME must not be null. If this file is included, it could be null. This attribute applies only to instance specific collections.

LEVEL: Specifies the collection level. The default will be the minimum. This attribute applies only to instance specific collections.

INCLUDE_DEFAULT: If set to TRUE, will include default collection with the same target TYPE. This attribute applies only to instance specific collections.

TRUE (default) | FALSE

23.3.1.2 Elements

CollectionLevel

CollectionItem

23.3.1.3 Used In

TargetCollection is a top-level element.

23.3.1.4 Examples

<TargetCollection TYPE="preferred" >
 
<CollectionItem NAME = "Load" UPLOAD_ON_FETCH="TRUE">
 
<Schedule OFFSET_TYPE="INCREMENTAL">
<IntervalSchedule INTERVAL = "15" TIME_UNIT = "Min"/>
</Schedule>
 
<MetricColl NAME = "NfsOperations">
<Filter COLUMN_NAME="NfsCallsRate" OPERATOR="LE">100000</Filter>
<Condition COLUMN_NAME="NfsServPercentBadCalls" CRITICAL="10" WARNING="5" OPERATOR="GT" OCCURRENCES="3" MESSAGE="NFS Bad Calls are %value%%%." MESSAGE_NLSID="netapp_filer_nfs_operations_nfs_per_bad_calls"/>
</MetricColl>
 
<MetricColl NAME = "CifsOperations">
<Filter COLUMN_NAME="CifsCallsRate" OPERATOR="LE">100000</Filter>
<Condition COLUMN_NAME="CifsPercentBadCalls" CRITICAL="10" WARNING="5" OPERATOR="GT" OCCURRENCES="3" MESSAGE="CIFS Bad Calls %value%%%." MESSAGE_NLSID="netapp_filer_cifs_operations_cifs_per_bad_calls"/>
</MetricColl>
 
<MetricColl NAME = "SystemLoad" />
 
</CollectionItem>
</TargetCollection>
 
This example illustrates the preferred method of declaring CollectionItems.  One collection item specifies multiple metrics with their own filter criteria and Condition elements defined.
 
<TargetCollection TYPE="network" >
 
  <CollectionItem NAME = "Response">
 
    <Schedule>
 
      <IntervalSchedule INTERVAL = "300" TIME_UNIT = "Sec"/>
 
    </Schedule>
 
    <Condition COLUMN_NAME="Status"
               CRITICAL="ok"
               OPERATOR="NE"
               OCCURRENCES="3"
               MESSAGE="%target% adaptor is inaccesible or is connected."
               MESSAGE_NLSID="network_response_status"/>
  </CollectionItem>
 
</TargetCollection>

This example describes a default collection for &rsquor;network' target type. The metric is provided as the NAME attribute for the CollectionItem. This method of providing metric NAME in the CollectionItem is for backward compatibility only. Use the example with MetricColls instead.

TargetCollection includes optional &rsquor;CollectionLevel' element(s) and &rsquor;CollectionItem' element(s)

<TargetCollection TYPE="oracle_beacon" >

This is a typical usage for TargetCollection element. It describes TargetCollection for &rsquor;oracle_beacon'.

<TargetCollection TYPE="oracle_csa_collector" NAME="CSA_collector">

NAME attribute implies that this might not be in the default_collections.

23.3.2 CollectionLevel

This element represents Collection Level List. It applies only to the default collections. The order implies the &rsquor;contains' relationship.

<!ELEMENT CollectionLevel EMPTY>
<!ATTLIST CollectionLevel
      NAME CDATA #REQUIRED>

23.3.2.1 Attributes

NAME: the name of the collection level

23.3.2.2 Elements

None

23.3.2.3 Used In

TargetCollection

23.3.2.4 Examples

<TargetCollection TYPE=”example2”> <CollectionLevel NAME=”LEVEL1”/> <CollectionLevel NAME=”LEVEL2”/> <CollectionLevel NAME=”LEVEL3”/> . . . <MetricColl NAME=”metric1”> <ItemProperty NAME=”prop1”>foo</ItemProperty> <Condition COLUMN_NAME=”value” CRITICAL=”bar” OPERATOR=”EQ”/> </MetricColl></TargetCollection>

The order for the collection level implies that LEVEL2 contains LEVEL1 collection items and LEVEL3 would include both LEVEL2 and LEVEL1 items.

Once the levels are declared using this element, the LEVEL attributes would refer to these levels.

23.3.3 CollectionItem

A CollectionItem defines the collection of one or more metrics. It has a schedule.

<!ELEMENT CollectionItem (ValidIf*, Schedule?, (MetricColl+ | (ItemProperty*, Filter*, LimitRows?, Condition*)  ) )>
<!ATTLIST CollectionItem
  NAME CDATA #REQUIRED
  LEVEL CDATA #IMPLIED
  UPLOAD CDATA "YES"
  UPLOAD_ON_FETCH (TRUE | FALSE) "FALSE"
  ATOMIC_UPLOAD (TRUE | FALSE) ”FALSE”
  POSTLOAD_PROC CDATA #IMPLIED
  PRELOAD_PROC CDATA #IMPLIED
  CONFIG       (TRUE | FALSE) "FALSE"
  CONFIG_METADATA_VERSION CDATA #IMPLIED
  TIMEOUT  CDATA  #IMPLIED
  COLLECT_WHEN_DOWN (TRUE | FALSE) "FALSE"
  COLLECT_WHEN_ALTSKIP (TRUE | FALSE) "FALSE"
  COMBINE_WITH_OTHER_COLLECTION (TRUE | FALSE) "TRUE"
  PROXY_TARGET_NAME CDATA #IMPLIED
  PROXY_TARGET_TYPE CDATA #IMPLIED
  PROXY_TARGET_TZ   CDATA #IMPLIED
  PROXY_TARGET_TZ_REGION   CDATA #IMPLIED
  INITIAL_UPLOADS CDATA #IMPLIED
  DISABLED (TRUE | FALSE) "FALSE"
 REQUIRED (TRUE | FALSE) "FALSE">

23.3.3.1 Attributes

NAME: Specifies the name of the collection.

LEVEL: The collection level.

UPLOAD: This attribute, if not specified, will be deemed as YES. NUMBER indicates how often the CollectionItem is uploaded. (Upload every 'n' collections).

YES (default) | NO | NUMERIC

UPLOAD_ON_FETCH: Collection Items marked as UPLOAD_ON_FETCH will have the same behavior as ATOMIC_UPLOAD with 1 difference – the upload occurs immediately.

TRUE | FALSE (default)

COLLECT_WHEN_DOWN: The default behavior is that the collection stops if the Response metric (if present for the target) indicates that the status of the target is down. The exception being the Response metric itself. But the behavior of not collecting when target is down can be overridden by setting this attribute to TRUE.

TRUE | FALSE (default)

COLLECT_WHEN_ALTSKIP: The default behavior is that the collection of metrics stops if an AltSkipCondition has been defined and there is a severity on the condition. Setting this attribute to TRUE allows collections to proceed even when this is the case. Note that a severity on the Response/Status condition is only overcome by using the COLLECT_WHEN_DOWN attribute.

TRUE | FALSE (default)

PROXY_TARGET_NAME: Used for proxy collection support, specifies Name of target data and severities should be uploaded for

PROXY_TARGET_TYPE: Used for proxy collection support, specifies Type.

PROXY_TARGET_TZ_REGION: Used for proxy collection support, specifies Timezone Region String (Eg "US/Pacific")

PROXY_TARGET_TZ: Used for proxy collection support, specifies Timezone (minutes from GMT: eg -420)

TIMEOUT: This is the time by which the metric evaluation is expected to finish. The time is provided in seconds. If the evaluation takes more than this time, the agent aborts the metric evaluation and returns a TIMEOUT exception. If this attribute is not provided or a value of zero, the agent defaults to twice the frequency of this metric evaluation in the collection file. Users can provide a time of less than zero to avoid any sort of timeout. A value less than 0 will force the agent to wait until the metric is evaluated completely.

POSTLOAD_PROC: Only applicable in UPLOAD_ON_FETCH situations. This attribute specifies an optional pl/sql procedures that the receiver should invoke when it receives the file with the contents of this collection.

PRELOAD_PROC: Only applicable in UPLOAD_ON_FETCH situations. This attribute specifies an optional pl/sql procedures that the receiver should invoke when it receives the file with the contents of this collection.

CONFIG: This attribute is used to tag collections of CONFIG metrics - these are handled specially by the Enterprise Manager framework. Note: Collection Items for CONFIG Metrics cannot specify ATOMIC_UPLOAD as FALSE. TRUE | FALSE (default)

INITIAL_UPLOADS: Defaults to 2, but can be set to a different number if more initial uploads need to be sent up before skipping uploads based on the UPLOAD parameter.

ATOMIC_UPLOAD: Collection Items marked as ATOMIC_UPLOAD will be bundled into a single file which will be uploaded in the regular upload interval (5 minutes).

TRUE | FALSE (default)

CONFIG_METADATA_VERSION: This attribute is used to specify version of CONFIG metrics.

COMBINE_WITH_OTHER_COLLECTION: Agent typically combines collections and executes them in a single thread sequentially to save on threads based on the interval. This can cause some delay in the metric execution if a previous one is taking some time. However some metrics would require to be executed on time. Setting this flag to FALSE would ensure that this metric is executed in its own thread.

TRUE (default) | FALSE

DISABLED: If set to TRUE, the agent will ignore this collection item.

REQUIRED: If set to TRUE, the console will disallow users from disabling this item.

23.3.3.3 Used In

TargetCollection

23.3.3.4 Examples

CollectionItem may contain &rsquor;ValidIf' element(s) which must all be satisfied for the CollectionItem to be evaluated. It may contain an optional &rsquor;Schedule' element and either a &rsquor;MetricColl' element or either &rsquor;ItemProperty', &rsquor;Filter', &rsquor;LimitRows' or &rsquor;Condition' elements.

For backward compatibility, a single metric can be specified using the NAME attribute, and its properties, filters and conditions can be provided as child elements.

The NEW preferred DTD has one or more Metric elements within a CollectionItem each indicating a metric to collect, and the filters, thresholds, etc. to associate with it.

<CollectionItem NAME="ProgramResourceUtilization">

This is an example of a simplest form of this element. &rsquor;ProgramResourceUtilization is a CollectionItem.

<CollectionItem NAME = "general_collection" UPLOAD="12" INITIAL_UPLOADS="4">

In this sample, &rsquor;general_collection' will be uploaded 4 times (number dictated by INITIAL_UPLOADS) initially and after that it will be uploaded once every 12 times (number dictated by UPLOAD attribute).

<CollectionItem NAME = "Inventory" UPLOAD_ON_FETCH = "TRUE" TIMEOUT = "3600">

&rsquor;Inventory' collection item will be uploaded when the metrics are collected. Timeout specified is 1 hour.

<CollectionItem NAME = "oracle_security" UPLOAD_ON_FETCH = "TRUE" CONFIG = "TRUE">

&rsquor;oracle_security' in this sample, involves collecting CONFIG metrics and should be indicated as such to the EMAgent.

<CollectionItem NAME = "UserResourceUsage" UPLOAD="YES" UPLOAD_ON_FETCH="FALSE" COLLECT_WHEN_DOWN="FALSE">

The UPLOAD attribute can take a &rsquor;Yes', &rsquor;No' or a numeric value. &rsquor;UserResourceUsage' collection will be attempted even when the response metric indicates that the target is down.

The PROXY_TARGET_TZ_REGION takes precedence over PROXY_TARGET_TZ if both are specified

Refer to the example in TargetCollection.

23.3.4 MetricColl

The MetricColl element refers to a metric that is being collected within a collection item.

<!ELEMENT MetricColl (ItemProperty*, Filter*, LimitRows?, Condition*)>
<!ATTLIST MetricColl
  NAME CDATA #REQUIRED
  TRANSIENT (TRUE|FALSE) ”FALSE”
  UPLOAD_IF_SEVERITY (WARNING|CRITICAL|CHANGE_ONLY) "CHANGE_ONLY">

23.3.4.1 Attributes

NAME: This is the name of the metric to collect.

TRANSIENT: If this attribute is set to TRUE would indicate that the data of this metric should be uploaded or is collected to refresh the cache used in the evaluation of other metrics.UPLOAD_IF_SEVERITY: Only effective when UPLOAD=NO and UPLOAD=N>1.

Supported values are:

  • CHANGE_ONLY (default): Upload data when there is severity change

  • WARNING: Upload data when there is severity change and when any condition is in WARNING or CRITICAL

  • CRITICAL: Upload data when there is severity change and when any condition is in CRITICAL

23.3.4.3 Used In

CollectionItem

23.3.4.4 Examples

MetricColl may include optional ItemProperty element(s), Filter element(s), a single optional LimitRows element and optional Condition element(s).

<MetricColl NAME = "WebServicesService"/>

This is the typical usage for MetricColl. &rsquor;WebServicesService' metric is associated with a CollectionItem.

Refer to the example in TargetCollection.

23.3.5 LimitRows

LimitRows is a filtering mechanism that can be applied to the collected data, before the data is sent to the repository via the Upload Manager. It limits the number of rows hat are uploaded.

<!ELEMENT LimitRows EMPTY>
<!ATTLIST LimitRows
          COLUMN_NAME CDATA #IMPLIED
          SORT_ORDER (ASCEND|DESCEND|NO_ORDER) "NO_ORDER"
          LIMIT_TO    CDATA   #REQUIRED>

23.3.5.1 Attributes

COLUMN_NAME:

SORT_ORDER:

Supported values are:

  • ASCEND:

  • DESCEND:

  • NO ORDER (default):

LIMIT_TO: Specifies the limit for the number of rows in the collection.

23.3.5.2 Elements

None

23.3.5.3 Used In

CollectionItem

MetricColl

23.3.5.4 Examples

<LimitRows LIMIT_TO="16" />

This example limits the collection results to 16 rows.

23.3.6 ItemProperty

This element describes a name value pair for a property.

<!ELEMENT ItemProperty (#PCDATA)>
<!ATTLIST ItemProperty
  NAME CDATA #REQUIRED
ENCRYPTED (NA|FALSE|TRUE) ”NA”
>

23.3.6.1 Attributes

NAME: Name of the Item property

ENCRYPTED: Indicates whether the property value will be encrypted.

The following values are defined for the attribute:

NA (default): Encryption is not available. The agent will not attempt to encrypt the value.

FALSE: Encryption is available. The agent will attempt to encrypt the value.

TRUE: Encryption is available. The agent has encrypted the value.

23.3.6.2 Elements

Character data

23.3.6.3 Used In

CollectionItem

MetricColl

23.3.6.4 Examples

<TargetCollection TYPE=”example2”>
   . . .
 
   <MetricColl NAME=”metric1”>
      <ItemProperty NAME=”prop1”>foo</ItemProperty>
      <Condition COLUMN_NAME=”value” CRITICAL=”bar” OPERATOR=”EQ”/>
   </MetricColl>
</TargetCollection>

&rsquor;prop1', ItemProperty will be utilized to compute the value of &rsquor;prop1' property defined in &rsquor;USER' scope in &rsquor;metric1' in TargetMetadata for target type &rsquor;example2'.

23.3.7 Filter (for Target Collection)

Filter defines a filtering mechanism that can be applied to the collected data before the data is sent to the repository via the Upload manager. If filtering is not applied, all the data that is collected through a Fetchlet is sent to the repository. As a result the repository can get filled quickly when uploading certain metrics. To alleviate this problem, filtering mechanism is applied to the data before uploading. The filter criteria are specified in collection xml.

<!ELEMENT Filter (#PCDATA)>
<!ATTLIST Filter
     COLUMN_NAME CDATA #REQUIRED
     OPERATOR  (EQ|LT|GT|LE|GE|NE|CONTAINS|MATCH) "EQ"
     AFTER_SEVERITY_CHECKING (TRUE|FALSE)  "FALSE" > 

Note:

Filter elements for TargetCollection and TargetMetadata are different.

23.3.7.1 Attributes

COLUMN_NAME: Name of the column in the metric to filter on.

OPERATOR: Specifies the operation

EQ (default): Equals

LT: Less than

GT: Greater than

LE: Less than or equal to

GE: Greater than or equal to

NE: Not equals

CONTAINS: Contains

MATCH: Matches

AFTER_SECURITY_CHECKING: If TRUE, filter will be applied after severity checking.

TRUE | FALSE (default)

23.3.7.2 Elements

Character data

23.3.7.3 Used In

CollectionItem

MetricColl

23.3.7.4 Examples

<Filter COLUMN_NAME="total_connections" OPERATOR="NE">0</Filter>

The result will include only those rows where &rsquor;total_connections' not equal to 0.

23.3.8 Condition

Condition element defines when a severity will be triggered.

<!ELEMENT Condition (CategoryValue*, KeyColumn*, FixitJob? )>
<!ATTLIST Condition
  CRITICAL CDATA #IMPLIED
  WARNING CDATA #IMPLIED
  OPERATOR (EQ | LT | GT | LE | GE | NE | CONTAINS | MATCH ) "GT"
  OCCURRENCES CDATA "1"
  NO_CLEAR_ON_NULL (TRUE | FALSE) "FALSE"
  MESSAGE CDATA #IMPLIED
  MESSAGE_NLSID CDATA #IMPLIED
  COLUMN_NAME CDATA #REQUIRED
  PUSH (TRUE | FALSE) "FALSE"
  GENERATE_INIT_CLEAR (TRUE | FALSE) "FALSE"
  ALERT_CONTEXT CDATA #IMPLIED
  CLEAR_MESSAGE CDATA #IMPLIED
  CLEAR_MESSAGE_NLSID CDATA #IMPLIED>

If it is Table Metric, MetricColumn is used to define which column and key to use to identify the row and column.

If KEYONLY_THRESHOLDS is set to TRUE for a Metric column, the Condition element must include a KeyColumn element.

23.3.8.1 Attributes

CRITICAL: Threshold. A special value, ”NotDefined” for the threshold ensures that the result of the operation specified by the OPERATOR will fail.

WARNING: Threshold. ”NotDefined” may also be applied to WARNING.

OPERATOR: Specifies the operation to evaluate the condition.

EQ: Equals

LT: Less than

GT (default): Greater than

LE: Less than or equal to

GE: Greater than or equal to

NE: Not equals

CONTAINS: Contains

MATCH: Matches

OCCURRENCES: The default value is 1.

NO_CLEAR_ON_NULL: This attribute is used to control severity clearing when a null value is returned for a metric column. It defaults to FALSE with the behavior that a null value ends up clearing previous alert severities. With a TRUE value for this attribute, null values will be skipped in severity evaluations without clearing the severity.

MESSAGE: The message attribute is a message template that will be used to generate message(s)to be sent along with the event occurrence. This message can contain the following place holders.

  • %value%: The value of the metric (or column of metric)

  • %target%: name of the target

  • %metric_id%: metric id

  • %column_name% This will be the value of any column this can include value columns as well as key columns

  • %warning_threshold%: the warning threshold of the condition

  • %critical_threshold%: the critical threshold of the condition

  • %num_of_occur%: number of occurrences

MESSAGE_NLSID: Specifies the String ID of the ResourceBundle for the message.

*COLUMN_NAME: For table metric, COLUMN_NAME defines which column will be checked. KeyColumn will be used to identify a row.

PUSH: This attribute is used to distinguish conditions created for push-based alerts from conditions that are evaluated over the collected data. The agent does not evaluate PUSH="TRUE" conditions.

TRUE | FALSE (default)

GENERATE_INIT_CLEAR: This attribute can be used to override the agent's behavior of not generating a severity the very first time a CLEAR is generated. Set this to TRUE if you do want the initial CLEAR.

TRUE | FALSE (default)

ALERT_CONTEXT: This attribute will be used to pass the related alert context. This new attribute may contain a list of column names separated by ";".

CLEAR_MESSAGE: Specifies a different message when an alert is cleared. If this attribute is missing then the MESSAGE attribute is used when alerts are cleared.

CLEAR_MESSAGE_NLSID: Specifies the NLSID for the clear message. If absent, the MESSAGE_NLSID is used when alerts are cleared.

23.3.8.2 Elements

CategoryValue

KeyColumn

FixitJob

23.3.8.3 Used In

CollectionItem

MetricColl

23.3.8.4 Examples

Condition element may include optional CategoryValue element(s), KeyColumn element(s) and an optional FixitJob element.

If the result after the keys are applied contains more than one row, the event occurrence generated will have content/message for each row that has crossed the threshold.

MATCH is used for regular expression.

For example:

OPERATIOR="MATCH" CRITICAL=".*ORA.*ERR.*"

This statement will match a string containing both ORA and ERR such as "ORA-ERR 345".

CategoryValue sub tags are used to classify the Condition along two axis, CLASS and CATEGORY. For e.g. CLASS=Fruits, CATEGORY=RedFruits Categorization of Conditions is useful for Root Cause Analysis among other things.

<Condition COLUMN_NAME="alertSeverity"
            CRITICAL="NotDefined"
WARNING="NotDefined"
OPERATOR="LE"
            OCCURRENCES="1"
            MESSAGE="%alertConcatString%"
NO_CLEAR_ON_NULL="TRUE"
            MESSAGE_NLSID="host_alertLog_alertSeverity_cond"/>
 
<Condition COLUMN_NAME="State"
CRITICAL="open"
            OPERATOR="EQ"
            MESSAGE="%Description%"
            ALERT_CONTEXT="In-contextLaunchURL"
            NO_CLEAR_ON_NULL="TRUE" />

These are examples of the Condition element.

<TargetCollection TYPE="examplec1" >
<CollectionItem NAME = "Response">
    <Schedule>
      <IntervalSchedule INTERVAL = "300" TIME_UNIT = "Sec"/>
    </Schedule>
    <Condition COLUMN_NAME="Status"
               CRITICAL="ok"
               OPERATOR="NE"
               OCCURRENCES="3"
               MESSAGE="%target% adaptor is inaccesible or is connected."
               MESSAGE_NLSID="network_response_status"/>
</CollectionItem>
 
</TargetCollection>

This sample gives the context for the Condition element.

For additional examples refer to TargetCollection example.

23.3.9 KeyColumn

The KeyColumn element is used to specify the key column for a table. It identifies a row of a table. This element must be present in a Condition element if KEYONLY_THRESHOLDS attribute is set for a Metric column.

<!ELEMENT KeyColumn (#PCDATA)>
<!ATTLIST KeyColumn
  COLUMN_NAME CDATA #REQUIRED
  OPERATOR    (EQ | LIKE) "EQ">

23.3.9.1 Attributes

COLUMN_NAME: Specifies name of the key column

OPERATOR:

Supported values are:

  • EQ (default) : Equals

  • LIKE: like

23.3.9.2 Elements

Character data

23.3.9.3 Used In

Condition

23.3.9.4 Examples

<Condition COLUMN_NAME="col3" WARNING="def" OPERATOR="CONTAINS">
      <KeyColumn COLUMN_NAME=”col1”>keyA</KeyColumn>
</Condition>

23.3.10 FixitJob

This element describes the action to be taken in response to an alert.

<!ELEMENT  FixitJob  (Property*) >
<!ATTLIST  FixitJob 
      TYPE    CDATA  #IMPLIED >

23.3.10.1 Attributes

TYPE: Specifies the type of the job.

23.3.10.2 Elements

Property

23.3.10.3 Used In

Condition

23.3.10.4 Examples

<TargetCollection TYPE="examplec1" >
 
  <CollectionItem NAME = "FixitExample" UPLOAD_ON_FETCH="TRUE">
    <Schedule>
      <IntervalSchedule INTERVAL="60" TIME_UNIT="Sec" />
    </Schedule>
 
     <MetricColl NAME=”metric1”/>
 
<Condition COLUMN_NAME="col2" CRITICAL="0" OPERATOR="GT" OCCURRENCES="1">
        <FixitJob TYPE=”OSCommand”>
 
           <Property NAME=”prop_env” SCOPE=”ENV”>EMDROOT</Property>
           <Property NAME=”prop_loc” SCOPE=”INSTANCE”>FILE_LOC</Property>
           <Property NAME=”COMMAND” SCOPE=”GLOBAL”>rm %prop_loc %</Property>
        </FixitJob>
     </Condition>
  </CollectionItem>
</TargetCollection>

This example illustrates a simple FixitJob that deletes files in response to a condition. The COMMAND property specifies the command that is executed when the value in col2 of the metric triggers the condition.