| Oracle® Enterprise Manager Extensibility Guide 10g Release 5 (10.2.0.5) Part Number B40007-03 |
|
|
PDF · Mobi · ePub |
| Oracle® Enterprise Manager Extensibility Guide 10g Release 5 (10.2.0.5) Part Number B40007-03 |
|
|
PDF · Mobi · ePub |
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, or service.
Associated Target: Targets whose data depend on each other.
Metric: Collectable data.
Mid Tier: OMS - Oracle Management Server
Container: A container is a home that houses an Oracle installation. Currently 2 kinds of containers are possible - Oracle Home (database, Enterprise Manager, 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 etc.
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.
<!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
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.
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:
Attributes introduced in Enterprise Manager Version 10.2:
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.
HELP: Not used.
TypeProperties (First introduced in Enterprise Manager version 10.2.)
DiscoveryHelper (First introduced in Enterprise Manager version 10.2.)
MetricClass (First introduced in Enterprise Manager version 10.2.)
<TargetMetadata TYPE="example1" META_VER="2.0" REQ <TargetMetadata TYPE="example1" META_VER="2.0" REQ UIRED_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.
<Metric NAME="prop" TYPE="TABLE"><TableDescriptor><ColumnDescriptor NAME="name" TYPE="STRING" IS_KEY="TRUE" /> <ColumnDescriptor NAME="value" TYPE="STRING" /></TableDescriptor><Property NAME="hostname" SCOPE="INSTANCE">NAME</Property></QueryDescriptor></Metric></TargetMetadata><QueryDescriptor FETCHLET_ID="OS">
This is a very simple example that describes a Target type, 'example1' having data () 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.
<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. The 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.
| 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 Grid Control Console 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.
The TypeProperties holds TypeProperty elements for the target type. This element is introduced in Enterprise Manager version 10.2.
<!ELEMENT TypeProperties (TypeProperty*)>
TypeProperty element contains the property name-value pair for a target type. This element is introduced in Enterprise Manager Version 10.2.
<!ELEMENT TypeProperty EMPTY> <!ATTLIST TypeProperty PROPERTY_NAME CDATA #REQUIRED PROPERTY_VALUE CDATA #IMPLIED >
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>
ASSOC_TARGET: The name of the associated target.
TYPE: The target type of the associated target.
Attributes introduced in Enterprise Manager version 10.2:
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:
a) OPTIONAL_SINGLE_CARDINAL: Zero or one targets as associated.
b) REQUIRED_SINGLE_CARDINAL: Exactly one associated target.
c) OPTIONAL_MULTI_CARDINAL: Zero or several associated targets.
d) REQUIRED_MULTI_CARDINAL: One or more associated targets.
ASSOC_TYPE: Describes the relation of the associated targets.
Supported values are:
a) RELATES_TO (default): Implies "some" generic relationship.
b) DEPENDS_ON: Dependency on associated target.
c) CONNECTS_TO: Source target connects to associated target.
d) SERVICE_ACCESS_POINT
e) RUNS_ON: Source target runs on (installed on) associated target.
f) CONTAINS: Source target contains associated target.
g) HOSTED_BY: Similar to runs on.
h) MONITORED_BY: Source target is monitored by associated target (Agent).
i) OPTIONALLY_CONNECTS_TO
AssocTarget element for versions prior to 10.2 MUST have the following attributes:
a) ASSOC_TARGET
b) TYPE
AssocTarget element for versions 10.2 and later MUST use the following attributes at least.
a) ASSOCIATION_NAME instead of ASSOC_TARGET
b) 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 Enterprise Manager version 10.2.
<!ELEMENT AssocPropDef EMPTY> <!ATTLIST AssocPropDef NAME CDATA #REQUIRED REQUIRED (TRUE | FALSE) #REQUIRED>
The DiscoveryHelper helps the agent in its process of discovering the target type. This element is introduced in Enterprise Manager version 10.2.
<!ELEMENT DiscoveryHelper (DiscoveryHint*) > <!ATTLIST DiscoveryHelper CATEGORYNAME CDATA #REQUIRED OUI_BASED (TRUE | FALSE) "TRUE" >
The DiscoveryHint allows users to specify any hint which can be a guide to discovery. This element is introduced in Enterprise Manager version 10.2.
<!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). This element was first introduced in Enterprise Manager version 10.2.
<!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.
Please refer to the explanations of CategoryValue, Metric for more details.
A MetricCategory element lists each choice within a classification of metrics. This element was first introduced in Enterprise Manager version 10.2.
<!ELEMENT MetricCategory EMPTY> <!ATTLIST MetricCategory NAME CDATA #REQUIRED NLSID CDATA #IMPLIED>
A metric element is used to declare the different measurable characteristics (performance, load, configuration etc.) of a target. The metric element describes the structure of the collected data as well as how to compute the information.
Note:
Oracle EM 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.QueryDescriptor, ExecutionDescriptor, PushDescriptor is optional only for REPOSITORY_TABLE, REPOSITORY_STRING, REPOSITORY_NUMBER and REPOSITORY_EVENT metric types. For all other metric types they are required.
<!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" REPOS_PLSQL CDATA #IMPLIED 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">
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 please use a table with 1 column of type NUMBER.
b) STRING: Deprecated - Instead please use a table with 1 column of type STRING
c) TABLE: Tabular data
d) RAW: Tabular data
c) EXTERNAL: Data not parsed/fronted by EMD.
e) REPOSITORY_TABLE: computed elsewhere
f) REPOSITORY_NUMBER: computed elsewhere
g) REPOSITORY_STRING: computed elsewhere
h) REPOSITORY_EVENT: First introduced only in Enterprise Manager version 10.2.
REPOS_PLSQL: If type is REPOSITORY_TABLE, REPOSITORY_NUMBER or REPOSITORY_STRING, this attribute specifies the name of the PL/SQL proc to execute at the repository to evaluate the metric.
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.
Values introduced in Enterprise Manager version 10.2:
d) HIDDEN_COLLECT: Metric can be collected. It will not be viewable. The data is not uploaded. It is similar to HIDDEN, but can have collection on it.
e) COLLECT_UPLOAD: Metric can be collected and uploaded, Metadata is uploaded to MGMT_METRICS but it is not viewable in 'All' metric 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 EM framework.
TRUE or FALSE (default)
Attributes introduced in Enterprise Manager version 10.2:
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.
ValidMidTierVersions (First introduced in Enterprise Manager version 10.2.)Display
CategoryValue(First introduced in Enterprise Manager version 10.2.)
<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.
This element was first introduced in Enterprise Manager version 10.2. The ValidMidTierVersions element is used in the mid tier based versioning support in the agent, introduced in Enterprise Manager version 10.2.
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).
<ValidMidTierVersionsSTART_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.
<ValidMidTierVersionsEND_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 Enterprise Manager 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 please refer to the example 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 RAQ 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 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.
Values introduced in Enterprise Manager version 10.2.
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. Support for string expressions is introduced in Enterprise Manager version 10.2. Please refer to the example 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.
COLUMN_NAME: This value will be used if the metric type is RAW to identify the database column.
IS_LONG_TEXT: This value will only be used when the metric is RAW and the column will be in digested form. The agent has support for metrics that expect to return the same long string repeatedly in metric results. If a column is marked with IS_LONG_TEXT="TRUE", the agent sends a row mapping the string to a digest into the MGMT_LONG_TEXT table and thereafter only sends the digested value as the data to the repository.
TRUE | FALSE (default)
IS_DATE: This value will only be used when the metric is RAW and the column is date type.
TRUE | FALSE (default)
STATELESS_ALERTS: This attribute if set to TRUE indicates to EM 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.
Attributes introduced in Enterprise Manager version 10.2.
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
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 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 was first introduced in Enterprise Manager version 10.2 and 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'.
Please refer to the example for ValidMidTierVersions also.
The ColumnMapper element was first introduced in Enterprise Manager version 10.2 and 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>
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">
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
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>
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>
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>
This holds the Unit information for the displayed data.
There are some standard units and unit nls ids that are supported. Please 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>
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 or Agent 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 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"/> <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. It describes the components of the credential (CredentialTypeColumn s), 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. Please refer to a more detailed 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'. Please refer to a more detailed 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
Please refer to the 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.
Please 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>
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:
a) MONITORING (default): Specifies credentials that management applications can use to connect directly to the target.
b) PREFERRED_CRED: Specifies a user's preferred credentials
c) SYSTEM: Specifies a fixed set of credentials that are used by certain specialized applications (patching, cloning etc.)
Attributes introduced in Enterprise Manager version 10.2:
CONTEXT_TYPE: Specifies what kind of entity, the set pertains to.
Supported values are:
a) TARGET (default): These are the stored credentials for a target that could be used by applications such as job system, patch etc.
b) CONTAINER: These are the stored credentials for a container. These are always host credentials.
c) 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.
Please 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. This element was first introduced in Enterprise Manager version 10.2.
<!ELEMENT CredentialSetColumn (Display?, CredentialSetColumnValue*) > <!ATTLIST CredentialSetColumn TYPE_COLUMN CDATA #REQUIRED SET_COLUMN CDATA #REQUIRED>
This element holds the allowed values for a CredentialSetColumn. This was introduced in Enterprise Manager version 10.2.
<!ELEMENT CredentialSetColumnValue (#PCDATA)> <!ATTLIST CredentialSetColumnValue IS_DEFAULT (TRUE|FALSE) "FALSE">
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" 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" >
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.
Attributes introduced in Enterprise Manager version 10.2:
IS_COMPUTED: If TRUE, indicates that it describes a dynamic property.
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".
Please refer to additional example 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">
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:
a) 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.
b) 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.
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. EMAgent 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
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.
Please 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:
a) GLOBAL (default)
b) INSTANCE
c) SYSTEMGLOBAL
OPERATOR: Specifies the operation to perform.
Supported operators are:
a) EQ (default): Equal
b) LT: Less than
c) GT: Greater than
d) LE: Less than or equal to
e) GE: Greater than or equal to
f) NE: Not equals
g) CONTAINS: contains
h) MATCH: matches
i) ISNULL: is NULL
j) ISNOTNULL: 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.
Please 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. Support for string expressions is introduced in Enterprise Manager version 10.2. Please refer to the example 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>
Please refer to the example 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>
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>
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.
Please 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">
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>
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.
Please 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:
a) EQ (default): Equals
b) GT: Greater than
c) GE: Greater than or equal to
d) LE: Less than or equal to
e) LT: Less than
f) NE: Not equals
g) CONTAINS: Contains
h) 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' recvlet. This recvlet 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 DDT 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.
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. Please use the example with MetricColls instead.
TargetCollection includes optional 'CollectionLevel' element(s) and 'CollectionItem' element(s)
<TargetCollection TYPE="oracle_beacon" >
This is a typical usage for TargetCollection element. It describes TargetCollection for 'oracle_beacon'.
<TargetCollection TYPE="oracle_csa_collector" NAME="CSA_collector">
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 EM 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.
Attributes introduced in Enterprise Manager version 10.2:
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
Please 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. Attributes introduced in version 10.2.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>1Supported values are:a) CHANGE_ONLY (default): Upload data when there is severity change.c) WARNING: Upload data when there is severity change and when any condition is in WARNING or CRITICALd) 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.
Please refer to the examples 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>
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.
Note:
Filter elements for TargetCollection and TargetMetadata are different.<!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" >
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>
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 message(s)to be sent along with the event occurrence. This message can contain the following place holders.
a) %value%: The value of the metric (or column of metric)
b) %target%: name of the target
c) %metric_id%: metric id
d) %column_name% This will be the value of any column this can include value columns as well as key columns
e) %warning_threshold%: the warning threshold of the condition
f) %critical_threshold%: the critical threshold of the condition
g) %num_of_occur%: number of occurrences
MESSAGE_NLSID: Specifies the String ID of the ResourceBundle for the message.
COLUMN_NAME: For table metric, COLUMN_NAME defines which column will be checked. KeyColumn will be used to identify a row.
PUSH: This attribute is used to distinguish conditions created for push-based alerts from conditions that are evaluated over the collected data. The agent does not evaluate PUSH="TRUE" conditions.
TRUE | FALSE (default)
GENERATE_INIT_CLEAR: This attribute can be used to override the agent's behavior of not generating a severity the very first time a CLEAR is generated. Set this to TRUE if you do want the initial CLEAR.
TRUE | FALSE (default)
Attributes introduced in Enterprise Manager version 10.2:
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.
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 please refer to TargetCollection.
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">
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_emdurl" SCOPE="SYSTEMGLOBAL">EMD_URL</Property> <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.
|
 Copyright © 2003, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|