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:
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.
This section defines DTD elements used by Enterprise Manager.
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.
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)
<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, ‘exmaple1' having data (Metric) that needs to be collected in the following format. The quoted values are evaluated by the ‘OS' Fetchlet in accordance with the scoping rules defined in Property.
Table 21-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 ‘accessPort' to be associated with the target instance. The metric ‘perf' is collected as shown below. The quoted values are evaluated by the ‘OSLineToken' Fetchlet in accordance with the scoping rules defined in Property.
Table 21-2 Metric: perf
| Char | Value |
|---|---|
|
Command |
‘%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.
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">
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)
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 ‘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 ‘SunOS' OS.
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
>
The TypeProperties holds TypeProperty elements for the target type.
<!ELEMENT TypeProperties (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
>
PROPERTY_NAME: Name of the target type property.
PROPERTY_VALUE: Value of the target type property.
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"
>
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. ‘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. ‘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:
OPTIONAL_SINGLE_CARDINAL: zero or one targets as associated
REQUIRED_SINGLE_CARDINAL: exactly one associated target
OPTIONAL_MULTI_CARDINAL: zero or several associated targets
REQUIRED_MULTI_CARDINAL: one or more associated targets
ASSOC_TYPE: Describes the relation of the associated targets. Supported Values are:
RELATES_TO (default): implies "some" generic relationship
DEPENDS_ON: Dependency on associated target
CONNECTS_TO: Source target connects to assoc target
SERVICE_ACCESS_POINT
RUNS_ON: Source target runs on (installed on) assoc target
CONTAINS: Source target contains assoc target
HOSTED_BY: Similar to runs on
MONITORED_BY: Source target is monitored by assoc target (agent)
OPTIONALLY_CONNECTS_TO
COMPUTE_RULE: Describes how the Association is computedIif not already present) for the target instance. Supported values are:
PARENT: will be constructed based on the first parent of the target.
MEMBER: will be construced based on the first child of the target.
NONE (default): Association for the target instance is not automatically computed.
AssocTarget element for versions prior to 10.2 MUST have the following attributes:
ASSOC_TARGET
TYPE
AssocTarget element for versions 10.2 and later MUST use the following attributes at least.
ASSOCIATION_NAME instead of ASSOC_TARGET.
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 ‘oracle_email' and would represent the following relation:
Oracle_email -----DependsOn----à oracle_im
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>
NAME: Name of the property.
REQUIRED: Indicates whether the property is required.
TRUE | FALSE
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"
>
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
The DiscoveryHint allows users to specify any hint which can be a guide to discovery.
<!ELEMENT DiscoveryHint (Display?) >
<!ATTLIST DiscoveryHint
NAME CDATA #REQUIRED
>
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>
NAME: Is the name of the class (e.g. Functional)
NLSID: Is the translation ID. The naming convention is metric_class_<classname>
<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 ‘EvaluationCost' MetricClass for a Target type ‘example3'. EvaluationCost has 3 categories: CHEAP, MEDIUM, and EXPENSIVE. Metric, ‘metric1' is a CHEAP metric to evaluate.
Refer to the explanations of CategoryValue, Metric for more details.
A MetricCategory element lists each choice within a classification of metrics.
<!ELEMENT MetricCategory EMPTY>
<!ATTLIST MetricCategory
NAME CDATA #REQUIRED
NLSID CDATA #IMPLIED>
NAME: The name of the category (e.g. Security)
NLSID: The NLSID of the category. The naming convention here is metric_cat_<category_name>
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"
>
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.
<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, ‘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 ‘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 ‘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>
‘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 ‘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>
‘http_raw' metric can be evaluated from a remote location and therefore is tagged as ‘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>
‘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.
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+)>
<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, ‘OS' and ‘Version' must have values, ‘SunOS' and ‘5.9' for the metric, ‘prop' to be evaluated. EMAgent allows the definition of upto 5 category properties which can be used in ValidIfs elements.
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>
NAME: Specifies the name of the category property.
CHOICES: Specifies the values the property can have. This may contain values separated by ";".
<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 ‘Version' CategoryProperty now has two choices 5.8 and 5.9, the metric would be evaluated for ‘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.
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>
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.
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 ‘metric1' to repository table, ‘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.
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.
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)
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.
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>
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 ‘_' 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: If this attribute is set to TRUE, it 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)
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. ‘ciscoMemoryPoolName' is a key column in a metric. The values of this column are of type, ‘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, ‘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 ‘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"/>
‘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 ‘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, ‘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 ‘pgScan' column, the previous value of the same column (‘_pgScan') and the collect interval. Note: ‘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 + ‘/egs/log/' "/>
The value of the column, ‘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 ‘ay'" />
<ColumnDescriptor NAME="value2" TYPE="NUMBER" COMPUTE_EXPR="Col __beginswith ‘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 ‘#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 ‘#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".
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, ‘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>
<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.
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>
REP_TABLE_NAME: Indicates the table name that the content of the metric should be uploaded to.
<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, ‘table1' for Mid-tier versions between 10.1 (inclusive) and 10.3 (not inclusive). Metric column, ‘col1' maps to ‘col1_rep' in the repository table, ‘table1'.
Refer to the example for ValidMidTierVersions also.
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>
METRIC_COLUMN: Name of the ColumnDescriptor this applies to
REP_TABLE_COLUMN: The database table column name this data should end up in.
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"
>
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)
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 ‘OS' fetchlet to return the property ‘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.
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.
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)
<Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>
‘perlBin' Property has ‘SYSTEMGLOBAL' scope which implies that emd.properties file is used to resolve the property
<Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
‘delimiter' property has ‘GLOBAL' scope.
<Property NAME="hostname" SCOPE="INSTANCE">NAME</Property>
‘hostname' has ‘INSTANCE' scope which implies that the value will be resolved by discovery. The value ‘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. ‘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, ‘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.
This represents the Label that will be displayed in UI.
<!ELEMENT Label (#PCDATA)>
<!ATTLIST Label
NLSID CDATA #REQUIRED>
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.
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>
<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.
This represents the icon to be used.
<!ELEMENT Icon (#PCDATA)>
<!ATTLIST Icon
GIF CDATA #IMPLIED>
This holds the description of the displayed entity.
<!ELEMENT Description (#PCDATA)>
<!ATTLIST Description
NLSID CDATA #IMPLIED>
NLSID: Will contain the ID used to lookup the string in to the resource bundle.
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>
NLSID: Will contain the ID used to lookup the string in to the resource bundle.
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>
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.
<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, ‘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.
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>
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.
<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 ‘metric1' metric as well.
<AltSkipCondition METRIC="Response" COLUMN="State" ASSOC_TARGET="t2"/>
If the ‘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 ‘State' column in the other target type.
The association ‘t2' has to be defined in the targets.xml file for example1.
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*)>
<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, ‘example1' is associated with ‘DBCreds', ‘DBCredsMonitoring' and ‘DBCredsSysdba' credentials.
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>
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 ‘HostCreds' is declared as a CredentialType. Refer to a more detailed example in CredentialInfo.
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">
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)
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 ‘UserName'. Refer to a more detailed example in CredentialInfo.
CredentialTypeColumnValue holds the allowed values for a CredentialTypeColumn.
<!ELEMENT CredentialTypeColumnValue (#PCDATA)>
<!ATTLIST CredentialTypeColumnValue
IS_DEFAULT (TRUE|FALSE) "FALSE">
IS_DEFAULT: Is set to true if this is the default value in the list.
TRUE | FALSE (default)
<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 ‘DBRole' column in ‘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
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>
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.
<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
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>
NAME: Name of column in this credential type.
REF_TYPECOLUMN: Name of the column in the referred credential type
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>
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.
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.
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>
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
This element holds the allowed values for a CredentialSetColumn.
<!ELEMENT CredentialSetColumnValue (#PCDATA)>
<!ATTLIST CredentialSetColumnValue
IS_DEFAULT (TRUE|FALSE) "FALSE">
IS_DEFAULT: Set this attribute to true if the element represents the default value in the list.
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)*)>
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" >
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).
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
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.
NAME: attribute simply identifies the property collector, for error tracing etc.
PROP_LIST: Contains ‘;' 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 ‘;' 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.
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, ‘VersionAndLocation' has a ROW format and returns ‘OS', ‘OracleHome', ‘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.
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)*)>
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, ‘DiskActivity' contains all the columns of ‘DiskActivity' metric. The result of this operation is similar to the SQL statement,
“Select * from DiskActivity"
§ GetView: The metric result, ‘AvgSrvcTimeView' contains only ‘DiskActivityavserv' column of ‘DiskActivity' metric.
§ GroupBy: Metric result, ‘DA_MaxAvServ' is a grouping of the ‘AvgSrvcTimeView' based on the ‘longestServ' which is the max value of the ‘DiskActivityavserv' column.
§ GetTable: Metric result, ‘_LoadInternal' contains all the columns of the ‘_LoadInternal' metric.
§ JoinTable: ‘Load' metric contains a join of the ‘_LoadInternal' and ‘DA_MaxAvServ' metrics.
The last metric is returned as the result for the ‘Load' metric.
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">
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
<GetTable NAME="DiskActivity"/>
This statement gets all the columns of the ‘DiskActivity' metric.
Refer to the example in ExecutionDescriptor.
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>
GetView may contain 0 or more instances of either ‘ComputeColumn' or ‘Column' elements and 0 or more instances of either ‘Filter' or ‘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.
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">
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
<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 ‘result' that has totalRequests1 > 0.
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>
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.
<Column NAME="DiskActivityavserv"/>
‘DiskActivityavserv' is the metric column that is selected for the operation.
<Column NAME="responseTime" TABLE_NAME="groupbyapps"/>
Column, ‘responseTime' from ‘groupbyapps' metric is selected for the operation.
Refer to the example in ExecutionDescriptor
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>
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".
<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.
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>
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.
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>
NAME: Specifies the name of the grouping.
FROM_TABLE: Specifies the name of the metric.
This element may include 0 or more elements of ‘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.
'By' element defines a column that constitutes a GroupBy clause. Each ‘By' element will be added to the result table as a column.
<!ELEMENT By EMPTY>
<!ATTLIST By
NAME CDATA #REQUIRED
COLUMN_NAME CDATA #IMPLIED>
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">
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
<AggregateColumn NAME="longestServ" COLUMN_NAME="DiskActivityavserv" OPERATOR="MAX" />
This operation results in the calculation of the Maximum value from the ‘DiskActivityavserv' column.
Refer to the example in ExecutionDescriptor.
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">
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)
Union element must include atleast 1 Table element.
<Union NAME="result4">
<Table NAME="result" />
<Table NAME="result1" />
<Table NAME="result2" />
<Table NAME="result3" />
</Union>
‘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.
This element describes the metrics that can take part in Table operations like Union and JoinTables.
<!ELEMENT Table EMPTY>
<!ATTLIST Table
NAME CDATA #REQUIRED>
<Table NAME="result" />
This example describes ‘result' as a metric that can participate in Table operations.
Refer to the example of Union.
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">
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)
JoinTables must include atleast 2 ‘Table' elements, 0 or more elements of either ‘Column' or ‘ComputeColumn' and 0 ore more elements of ‘Where' element.
<JoinTables NAME="Load">
<Table NAME="_LoadInternal"/>
<Table NAME="DA_MaxAvServ"/>
</JoinTables>
This example defines ‘Load' as a join of ‘_LoadInterval' and ‘DA_MaxAvServ' metrics.
Refer to the example in ExecutionDescriptor.
<!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>
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:
<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>
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>
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.
PushDescriptor may include 0 or more elements of ‘ValidIf' and ‘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 ‘AQMetrics' receivelet. This receivelet provides data and/or events for the metric.
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.
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">
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
<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 ‘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 ‘CollectionLevel' element(s) and ‘CollectionItem' element(s)
<TargetCollection TYPE="oracle_beacon" >
NAME attribute implies that this might not be in the default_collections.
This element represents Collection Level List. It applies only to the default collections. The order implies the ‘contains' relationship.
<!ELEMENT CollectionLevel EMPTY>
<!ATTLIST CollectionLevel
NAME CDATA #REQUIRED>
<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.
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">
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.
CollectionItem may contain ‘ValidIf' element(s) which must all be satisfied for the CollectionItem to be evaluated. It may contain an optional ‘Schedule' element and either a ‘MetricColl' element or either ‘ItemProperty', ‘Filter', ‘LimitRows' or ‘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. ‘ProgramResourceUtilization is a CollectionItem.
<CollectionItem NAME = "general_collection" UPLOAD="12" INITIAL_UPLOADS="4">
In this sample, ‘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">
‘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">
‘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 ‘Yes', ‘No' or a numeric value. ‘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.
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">
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
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. ‘WebServicesService' metric is associated with a CollectionItem.
Refer to the example in TargetCollection.
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>
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.
This element describes a name value pair for a property.
<!ELEMENT ItemProperty (#PCDATA)> <!ATTLIST ItemProperty NAME CDATA #REQUIRED ENCRYPTED (NA|FALSE|TRUE) “NA" >
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.
<TargetCollection TYPE="example2">
. . .
<MetricColl NAME="metric1">
<ItemProperty NAME="prop1">foo</ItemProperty>
<Condition COLUMN_NAME="value" CRITICAL="bar" OPERATOR="EQ"/>
</MetricColl>
</TargetCollection>
‘prop1', ItemProperty will be utilized to compute the value of ‘prop1' property defined in ‘USER' scope in ‘metric1' in TargetMetadata for target type ‘example2'.
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.
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)
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 STATELESS_ALERT (TRUE | FALSE) "FALSE" >
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.
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 messages to be sent 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.
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.
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.
STATELESS_ALERT: The default is false. If this attribute is set to TRUE, it indicates to Enterprise Manager not to retain any state associated with the condition. The default is False.
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.
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">
COLUMN_NAME: Specifies name of the key column
OPERATOR:
Supported values are:
EQ (default) : Equals
LIKE: like
This element describes the action to be taken in response to an alert.
<!ELEMENT FixitJob (Property*) >
<!ATTLIST FixitJob
TYPE CDATA #IMPLIED >
<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.