This chapter contains the following sections:
As a plug-in developer, you are responsible for the following steps within the target metadata files creation process:
Create the target definition file.
The target type metadata file tells the Management Agent what data to retrieve and how to obtain that data for this particular target type.
For more information, see Section 3.3, "Creating the Target Type Metadata File".
Define metrics to collect from the target.
A metric refers to a specific piece of data collected from the target. A set of related metrics collectively comprise a metric group.
For more information, see Section 3.4, "Defining Metrics to Collect from the Target".
Define target configuration data to collect.
You can collect configuration data for a target and save it in the Management Repository as a snapshot representing the target's configuration at a specific point in time. Each configuration snapshot is associated with a specific target instance.
For more information, see Chapter 7, "Collecting Target Configuration Data".
Create the default collection file.
The default collection file defines the metric data to be collected from targets and uploaded to the Management Repository along with information such as the collection schedule.
For more information, see Section 3.5, "Creating the Default Collection File".
Package the various definition files in the plug-in staging directory (plugin_stage):
Target type metadata file
plugin_stage/oms/metadata/targetType/target_type.xml
plugin_stage/agent/metadata/target_type.xml
Note:
An identical copy of this file must be placed in both the /oms and /agent directories.Default collection file
plugin_stage/oms/metadata/default_collection/target_type.xml
plugin_stage/agent/default_collection/target_type.xml
Note:
An identical copy of this file must be placed in both the /oms and /agent directories.Configuration metadata file
plugin_stage/oms/metadata/snapshotlive/target-type_ecmdef.xml
For more information, see Chapter 14, "Validating, Packaging, and Deploying the Plug-in".
Two XML metadata files are required to define the target type that your plug-in will enable Enterprise Manager Cloud Control to monitor and manage:
The definition of a target type primarily consists of the metrics you want the Management Agent to collect for the target. The file contains a list of all metrics that will be collected for the target type, along with specifics on how to compute each metric.
For more information, see Section 3.3, "Creating the Target Type Metadata File".
This file defines the interval at which metric data will be collected or received from the target. You can specify optional alert thresholds and optional corresponding alerts messages for each metric. Cloud Control users can override the default collection intervals, but the default values must be provided in this file.
For more information, see Section 3.5, "Creating the Default Collection File".
This chapter also describes the metadata definitions required to collect configuration data for plug-in targets. This is an advanced feature but can be useful for many plug-ins. For more information, see Section 7.2, "About the Configuration Definition Files".
The following sections provide the summary of creating the target type and default collection metadata files, as well as an overview of target configuration data collection.
The target type metadata file tells the Oracle Management Agent what data to retrieve and how to obtain that data for this particular target type.
At the highest definition level, the target type metadata file is composed of four key XML elements as described in Table 3-1.
Table 3-1 Key Elements of the Target Type Metadata File
| Element | Description |
|---|---|
|
|
Specifies information about the plug-in, such as name and version. |
|
|
Defines a metric group, which in turn contains one or more metrics that each define a specific piece of data collected from the target. |
|
|
Defines properties that are populated when a target instance is created. |
|
|
Specifies credentials required to by the plug-in authenticate with a target instance. |
Enterprise Manager ships with predefined target type metadata files that cover the most common target types. In situations where the predefined target metadata files do not fit the types of targets you want to monitor, you can either:
Define a new target type by creating a target type metadata file
Use one of the predefined metadata files as a template for defining a new target type, and then repackage the files as a new plug-in
This section briefly introduces the structure of the target type metadata file. A complete example of a target type metadata file is provided with the EDK:
edk/samples/plugins/SampleHost/oms/metadata/targetType/demo_hostsample.xml
In the preceding directory path, edk represents the directory where you expanded the EDK archive. For information about the EDK archive, see Section 1.2, "About the Extensibility Development Kit (EDK)".
For additional information about creating target type metadata files, Section 3.6, "Guidelines for Creating Target Metadata".
Example 3-1 shows the minimum required information that a target type file must contain.
<TargetMetadata META_VER="2.0" TYPE="demo_hostsample">
<Display>
<Label NLSID="hs_displayname">Demo Plugin Sample Host</Label>
</Display>
<Metric NAME="Response" TYPE="TABLE">
<Display>
<Label NLSID="hs_response_displayname">Response</Label>
</Display>
<TableDescriptor>
<ColumnDescriptor NAME="Status" TYPE="NUMBER">
<Display>
<Label NLSID="hs_response_status">Status (up/down)</Label>
</Display>
</ColumnDescriptor>
</TableDescriptor>
<QueryDescriptor FETCHLET_ID="OSLineToken">
<Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property>
<Property NAME="fake" SCOPE="INSTANCE"
OPTIONAL="TRUE">USE_FAKE_DATA</Property>
<Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>
<Property NAME="script" SCOPE="GLOBAL">%scriptsDir%/emx/demo_hostsample/datacollector.pl --collect Response --fake %fake%</Property>
<Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>
<Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
</QueryDescriptor>
</Metric>
<InstanceProperties>
<InstanceProperty NAME="SAMPLE_DATA" CREDENTIAL="FALSE" OPTIONAL="TRUE">
<Display>
<Label NLSID="EMPLOYEE_ID_iprop">Employee ID</Label>
</Display>
</InstanceProperty>
</InstanceProperties>
</TargetMetadata>
The following sections provide information about the XML definitions shown in Example 3-1.
Oracle recommends that users adding new target types adhere to Enterprise Manager naming conventions. This naming convention allows for file naming consistency in environments where similar products from multiple vendors are used. The target naming convention follows the form vendorID_productID_PluginTag.
For example:
test_demo_targetType.xml
The first lines after the header of the target definition file identify the target type. The following excerpt defines the metadata version (META_VER="2.0") and target type (TYPE="test_demo_targetType").
<TargetMetadata META_VER="2.0" TYPE="test_demo_targetType">
The TYPE attribute and the META_VER attribute of the TargetMetadata element must match the TYPE attribute and the META_VER attribute of the TargetCollection element of the default collection metadata file. For more information about the default collection metadata file, see Section 3.5, "Creating the Default Collection File".
Metadata versioning allows different versions of the same target type metadata to exist concurrently within the managed environment, although only one metadata version is allowed per Management Agent. You should update the metadata version each time you update the target metadata file.
The syntax for the meta value is MajorNumber.MinorNumber. The value for MinorNumber can be either one or two digits. It is important that you choose to use either one or two digits for MinorNumber, and continue to use that syntax throughout the plug-in's lifecycle.
A one-digit MinorNumber can be updated up to nine times, after which the MajorNumber value must be increased. For example:
1.0, 1.1, 1.2, ...,1.9, 2.0, 2.1
A two-digit MinorNumber can be revised up to 99 times. For example:
1.01, 1.02, 1.09, ..., 1.10, 1.11, ..., 1.99, 2.01
Note that you cannot combine single-digit and two-digit formats. For example, increasing the version from 1.9 to 1.10 is not valid.
If you modify the metadata for one or more metrics, or change credentials, or update the target property file during plug-in development, be sure to increment the value of the META_VER attribute of the TargetMetadata element to the next digit value. For example, if the current version is "1.0", set the value to "1.1" if you modify the metric metadata:
<TargetMetadata META_VER="1.1" TYPE="demo_hostsample">
Continue to increment the version each time you modify your metrics. Otherwise, NullPointerException errors may occur if the plug-in is deployed to the same development or test installation that the previous version was deployed to.
Once plug-in development is complete, the META_VER value can safely be set to the actual production version.
In most cases, the plug-in will be required to authenticate with each target instance that it will collect data for, or run jobs against. Credential types and credential sets needed to enable authentication are defined in the CredentialInfo element within the target type metadata file.
For more information, see Chapter 16, "Defining Credentials".
Credentials information for the target includes and defines the credentials fields (referred to as columns) and the credentials sets specific to the target type. Enterprise Manager's security framework provides facilities for managing these credentials and using them when performing various management functions.
The extensibility framework uses type properties to internally categorize the target type for framework processing. They are not visible to the end user. Corresponding subsystems use the type properties to enable features for the target type or to perform appropriate validation checks.
The value set at the type property level applies to all targets of that type and across all metaversions, unlike instance properties which only apply to a specific target.
The following example specifies that the target type is a system class of target. The extensibility framework uses this setting to display the target on all system pages.
<TypeProperties> <TypeProperty PROPERTY_NAME="is_system" PROPERTY_VALUE="1"/> </TypeProperties>
Table 3-2 provides a description of the available type properties.
| Property Name | Description |
|---|---|
|
|
Specifies the type as modelling a system type. You must set this value for all system types.
Note: The property value is always set to 1 for all the |
|
|
Specifies the type as modelling a service. Note: The property value is always set to 1 for all the |
|
|
Enterprise Manager sets this value automatically. Do not modify. |
|
|
Do not use |
|
|
Do not use |
|
|
Set this value for an install home manageable entity (for example, Oracle home) |
|
|
Set this value for a discovered entity with an existence-only state, that is, an entity that is discovered but cannot be managed by Oracle yet. Possible value:
Note: When the entity becomes a managed entity by Oracle, you must remove this entry from the target type metadata file and register the target type again. |
|
|
This property is used for privilege propagation and specifies the privilege propagation mode. Possible values:
|
|
|
Used by the redundancy group feature to disable redundancy groups for certain target types (which have disallow redundancy group set). Specifies whether redundancy group can contain this type as a member. Possible value:
|
|
|
Used by the redundancy group feature to lock the target type to the specified member_target_type. |
|
|
Specifies the name of the instance or dynamic property that represents the target version for the target type (for all target pages and plug-in certification). Note: Oracle recommends including this property when you are defining target types. |
Example 3-2 Defining Type Properties
<TargetMetadata META_VER="1.1" TYPE="oracle_dbsys" CATEGORY_PROPERTIES="" RESOURCE_BUNDLE_PACKAGE="oracle.sysman.db.rsc">
<Display>
<Label NLSID="oracle_dbsys_nlsid">Database System</Label>
</Display>
<TypeProperties>
<TypeProperty PROPERTY_NAME="is_system" PROPERTY_VALUE="1"/>
<TypeProperty PROPERTY_NAME="priv_propagation_mode" PROPERTY_VALUE="2"/>
</TypeProperties>
<MonitoringMode MEDIATOR="Repository"/>
</TargetMetadata>
Instance properties are populated when a target instance is created. The InstanceProperties descriptor within the target type metadata file defines what properties an administrator must specify in the Enterprise Manager Cloud Control console when adding a new target instance of this particular target type.
Although the InstanceProperties section can be defined at various locations within the target type metadata file, Oracle recommends defining this section at the very end of the file for consistency. Instance properties defined in the target type metadata file are resolved to values specified for these instance properties in the target type metadata file.
Target instance properties are named values that can be used for computing the metrics of the target, or for display in the home page of the target. The list of target instance properties is specified in the metadata to allow data driven user interfaces to register targets, and for the Oracle Management Agent to validate that a target instance is complete.
Instance properties are populated when a target instance is created. In this example, the property is required (OPTIONAL="FALSE) and it is a credential property.
<InstanceProperties> <InstanceProperty NAME="password" OPTIONAL="FALSE" CREDENTIAL="TRUE"> <Display> <Label NLSID="USER_PASSWORD">User Password</Label> </Display> </InstanceProperty> </InstanceProperties>
The values for dynamic instance properties are passed back by the Management Agent collecting data from the target instance. They are typically used within a QueryDescriptor to define properties passed to the fetchlet responsible for metric collection. For more information about the QueryDescriptor element, see Table 3-4. For more information about fetchlets, see Chapter 21, "Using Fetchlets".
The properties in the following example are described in Section 3.4.2, "Defining the Basic Response Metric Group".
<InstanceProperties> <DynamicProperties NAME="AruidInfo" FORMAT="ROW" OPT_PROP_LIST="ARUID"> <QueryDescriptor FETCHLET_ID="OSLineToken"> <Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property> <Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property> <Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl</Property> <Property NAME="script" SCOPE="GLOBAL">%scriptsDir%/hostaruid.pl</Property> <Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property> <Property NAME="delimiter" SCOPE="GLOBAL">|</Property> </QueryDescriptor> </DynamicProperties> </InstanceProperties>
Using dynamic properties reduces the work involved in configuring a target by allowing certain properties to be computed rather than requiring the user to correctly specify their values (for example, the "Version" property of a database can be reliably computed given addressing information).
Dynamic properties are computed in the order that they are defined in the XML file so that later dynamic properties can use values from earlier dynamic properties in the XML file if required.
The Management Agent allows for the fact that the target must be up for the successful computation of these dynamic properties by recomputing the properties each time a target restart is detected; that is, each time the target status changes to Up.
Note:
Some properties can be computed without access to the target; therefore there is some support for computing dynamic properties when the target is down.To compute a dynamic property when the target is down, include the following attribute:
COMPUTE_WHEN_DOWN="TRUE"
Metrics are at the core of Cloud Control's target monitoring capabilities. When we speak of Cloud Control's ability to monitor and manage various targets, what we are really talking about is its ability to collect, process, and display target metrics.
A metric refers to a specific piece of data collected from the target.
Metrics can viewed as being of two basic types:
In this model, the plug-in polls the target for metric data at the frequency specified in the default collections file. This is the most common type of metric utilized by plug-ins.
A metric of this type requires the use of a fetchlet, a parametrized data access mechanism that takes arguments (for example, a script, a SQL statement, a target instance's properties) as input and returns formatted data.
Predefined fetchlets are provided by Oracle for use with plug-ins. For a list of available fetchlets and information about their usage, see Chapter 21, "Using Fetchlets".
In this model, the plug-in receives notifications that are sent asynchronously from the target, without being requested. This type of metric requires a receivelet, which enables the plug-in to receive such notifications. As with fetchlets, predefined receivelets are provided by Oracle. For information about using receivelets, see Chapter 20, "Using Receivelets".
The target metadata must define each type of metric the plug-in will collect, how and when the metric data is to be collected, and what metric thresholds will trigger an incident to be raised within Cloud Control.
Note:
All metrics that can be viewed from the Cloud Control UI must have a proper display label and NLSID.The metadata for metric groups and individual metrics is defined in two metadata files packaged with the plug-in:
The content of the target type metadata file consists primarily of metric definitions, along with credential information and target properties. The fetchlet or receivelet that a metric will use is defined in the QueryDescriptor or PushDescriptor element within the target type metadata file.
For information about key metric definition elements, see Section 3.4.7, "Overview of Key Metric Metadata Elements".
The default collection metadata file
The frequency at which data is collected for each metric is defined in the default collection metadata file. Metric Alert event conditions for each metric and the messages to display for such alerts are also defined in this file.
For information about the default collection metadata file, see Section 3.5, "Creating the Default Collection File".
As a matter of practice, Oracle recommends that you specify at least a single Response metric group that includes the following metric for each target type:
A Status metric that indicates target availability (required for all target types)
The corresponding default collection file must define a critical condition on the Status metric that represents the target status as up or down. For more information, see Section 3.5.2, "Defining Basic Metric Collection".
Example 3-3 defines a Status metric. The return value of Status is as follows:
0: Target status is down
1: Target status is up
The process by which the metric data is collected is defined in the QueryDescriptor element. This descriptor specifies that the OSLineToken fetchlet invokes a Perl script (emrepresp.pl) to collect the data. The Perl script returns a standard out (stdout) data stream containing the collected data to the fetchlet.
Each property passed to the OSLineToken fetchlet execution is specified in a Property tag within the QueryDescriptor element.
The OSLineToken fetchlet requires that a GLOBAL property called command be set to the command that is to be executed. Different tokens typically have specific required properties. For more information about the OSLineToken fetchlet, see Section 21.2, "OS Command Fetchlets".
When a plug-in is deployed to a Management Agent, any scripts or binaries associated that were packaged within the /agent/scripts directory in the plug-in archive are written to the following directory in the Management Agent, where AGENT_HOME is the Management Agent plug-in home directory and plugin_name is the name of the plug-in:
AGENT_HOME/plugins/plugin_name
The scriptsDir property is a token that defines this location.
Note:
In Enterprise Manager 11g and earlier, the scripts bundled with the plug-in were copied to the scripts directory under the Management Agent. However, for this release the scripts included in the plug-in are used directly.This changes the behavior of the scriptsDir property in theQueryDescriptor element. Previously, it referred to the directory under the Management Agent, but now it refers to the directory under the plug-in.If you want to refer to the scripts directory under the Management Agent, use the sdkScriptsDir property.The script property specifies the script (data_collector.pl) to be run.
The EDK provides an example of this script:
edk/samples/plugins/HostSample/demo_hostsample/stage/agent/scripts/emx/demo_hostsample
The startsWith and delimiter properties specify the format of the STDOUT of the script executed. In this case, the script will return a single row that looks like this:
em_result="value for Load|value for Status"
<Metric NAME="Response" TYPE="TABLE">
<TableDescriptor>
<ColumnDescriptor NAME="Status" TYPE="NUMBER">
<Display>
<Label NLSID="oracle_emrep_resp_status">Status</Label>
</Display>
</ColumnDescriptor>
</TableDescriptor>
<QueryDescriptor FETCHLET_ID="OSLineToken">
<Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>
<Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property
<Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl</Property>
<Property NAME="script" SCOPE="GLOBAL">%scriptsDir%/emrepresp.pl</Property>
<Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>
<Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
</QueryDescriptor>
</Metric>
For a description of these elements, see Section 3.4.7, "Overview of Key Metric Metadata Elements".
You can define much more complex metrics, such as metrics that collect CPU performance data or metrics for which values are computed from the values of other metrics. Examples of such advanced or complex metric definitions can be seen in the sample target type metadata file provided with the EDK:
edk/samples/plugins/HostSample/demo_hostsample/stage/oms/metadata/targetType/demo_hostsample.xml
Example 3-4 shows a metric group containing metrics that collect CPU performance data. As in the previous example, the QueryDescriptor element specifies that the OSLineToken fetchlet will invoke the data_collector.pl script to collect the data.
Example 3-4 Defining Advanced Metrics
<Metric NAME="CPUProcessesPerf" TYPE="TABLE">
<Display>
<Label NLSID="hs_cpuprocessesperf_displayname">Host Process CPU Performance
Statistics</Label>
</Display>
<TableDescriptor>
<ColumnDescriptor NAME="ProcPID" TYPE="NUMBER" IS_KEY="TRUE">
<Display>
<Label NLSID="hs_cpuprocessesperf_procpid">PID</Label>
</Display>
</ColumnDescriptor>
<ColumnDescriptor NAME="ProcUser" TYPE="STRING" IS_KEY="FALSE">
<Display>
<Label NLSID="hs_cpuprocessesperf_procuser">User</Label>
</Display>
</ColumnDescriptor>
<ColumnDescriptor NAME="ProcCPU" TYPE="NUMBER" IS_KEY="FALSE">
<Display>
<Label NLSID="hs_cpuprocessesperf_proccpu">CPU Usage (%)</Label>
</Display>
</ColumnDescriptor>
<ColumnDescriptor NAME="ProcCmd" TYPE="STRING" IS_KEY="FALSE">
<Display>
<Label NLSID="hs_cpuprocessesperf_proccmd">Command</Label>
</Display>
</ColumnDescriptor>
</TableDescriptor>
<QueryDescriptor FETCHLET_ID="OSLineToken">
<Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property>
<Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>
<Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl</Property>
<Property NAME="script" SCOPE="GLOBAL">%scriptsDir%/emx/demo_hostsample/data_
collector.pl</Property>
<Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>
<Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
</QueryDescriptor>
</Metric>
Example 3-5 shows a test metric. The Management Agent can check some metrics to determine if a target has been specified correctly with valid instance properties. Setting the IS_TEST_METRIC attribute to "TRUE" provides a Test button when adding a target instance.
Example 3-5 Defining a Test Metric
<Metric NAME="Ping" TYPE="TABLE" IS_TEST_METRIC="TRUE" USAGE_TYPE="HIDDEN">
<Display>
<Label NLSID="label_metrics_ping">Ping Test</Label>
</Display>
<TableDescriptor>
<ColumnDescriptor NAME="tcpIpPing" TYPE="NUMBER">
<Display>
<Label NLSID="test_ping">TCP Ping, Milliseconds</Label>
</Display>
</ColumnDescriptor>
</TableDescriptor>
<QueryDescriptor FETCHLET_ID="OSLineToken">
<Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property>
<Property NAME="scriptsDir" SCOPE="SYSTEMGLOBAL">scriptsDir</Property>
<Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl
%sdkScriptsDir%/osresp.pl</Property>
<Property NAME="ENVEM_TARGET_NAME" SCOPE="INSTANCE">hostName</Property>
<Property NAME="startsWith" SCOPE="GLOBAL">em_result=</Property>
<Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
</QueryDescriptor>
</Metric>
By default, the Management Agent collects metrics but you can define repository metrics. Repository metrics are collected at the Management Repository.
To define a repostitory metric, you must use the REPOSITORY attribute when defining the Metric element. For more information about the Metric element, see Table 3-4.
Example 3-6 provides an extract from a target metadata XML file where a repository metric is defined.
Note:
When defining repository metrics, you must set the metric TYPE attribute to TABLE. RAW is not supported for repository metrics.Example 3-6 Defining Repository Metrics
<Metric NAME="Response"
TYPE="TABLE"
REPOSITORY="TRUE">
<Display>
<Label NLSID="REPOS_SQL">REPOS_SQL</Label>
</Display>
<TableDescriptor>
<ColumnDescriptor NAME="Status" TYPE="NUMBER">
<Display>
<Label NLSID="Status">Status</Label>
</Display>
</ColumnDescriptor>
</TableDescriptor>
<QueryDescriptor FETCHLET_ID="REPOSITORY_SQL">
<Property NAME="Type">SQL</Property>
<Property NAME="Source">SELECT target_guid, 1 as Status from mgmt_targets where target_type='tvmrtm200'</Property>
</QueryDescriptor>
</Metric>
The purpose of the categorization of metrics is to define the nature of the data that is being collected. This is only for metrics that are visible in the All Metrics pages in the Cloud Control console.
Oracle recommends using the following guidelines when defining metric categories:
Categorize all Metrics and Metric Groups visible to the user in the All Metrics page of the Cloud Control console.
Use the published category values only as listed in Table 3-3.
If all metrics in a metric group belong to the same category, then you can set the category at the metric group level and leave the category empty at the metric level. All metrics in the group will inherit this category. You can set one category only at the metric group level. For an example, see Example 3-7, "Defining a Category at Metric Group Level".
If the metrics in the metric group have different categories, do not set a category at the metric group level. In such cases, set the category at the metric level. Each metric can have one category only. For an example, see Example 3-8, "Defining a Category at Metric Level".
The Metric framework has a Default metric class and a set of metric categories within this class. Table 3-3 provides a list of the available metric categories. You can categorize your metrics into the appropriate category within the Default metric class
| Category | Description |
|---|---|
|
Availability |
Lets you know whether a target or component is up. Used mainly for Response or Status metrics. |
|
Capacity |
Defines how much you have of something. |
|
Fault |
A severe error which results in a component not operating, or memory corruptions or data corruptions. |
|
Load |
How much work an entity is being asked to do. |
|
LoadType |
Indicates the characteristics of the work that an entity is being asked to do. |
|
Response |
How quickly is the system is responding. |
|
BusinessKPI |
Measures output in business terms. |
|
Utilization |
How much of something an entity is using |
|
Security |
Reporting on security issues. |
Example 3-7 categorizes all metrics within MyMetricGroup with a metric class of Default and a metric category of Load.
Example 3-7 Defining a Category at Metric Group Level
<Metric NAME="MyMetricGroup" TYPE="TABLE">
<Display> <Label>MyMetricGroup</Label> </Display>
<CategoryValue CLASS="Default" CATEGORY_NAME="Load"/>
<TableDescriptor>
<ColumnDescriptor NAME="MyMetric1" TYPE="NUMBER"> </ColumnDescriptor>
<ColumnDescriptor NAME="MyMetric2" TYPE="NUMBER"> </ColumnDescriptor>
</TableDescriptor> </Metric>
Example 3-8 categorizes the MyMetric1 metric with a metric class of Default and a metric category of Load, and the MyMetric2 metric with a metric class of Default and a metric category of Load Type.
Example 3-8 Defining a Category at Metric Level
<<Metric NAME="MyMetricGroup" TYPE="TABLE">
<Display>
<Label>MyMetricGroup</Label>
</Display> <TableDescriptor>
<TableDescriptor>
<ColumnDescriptor NAME="MyMetric1" TYPE="NUMBER">
<Display>
<Label>MyMetric1</Label>
</Display>
<CategoryValue CLASS="Default" CATEGORY_NAME="Load"/>
</ColumnDescriptor>
<ColumnDescriptor NAME="MyMetric2" TYPE="NUMBER">
<Display>
<Label>MyMetric2</Label>
</Display>
<CategoryValue CLASS="Default" CATEGORY_NAME="Load Type"/>
</ColumnDescriptor>
</TableDescriptor>
</Metric>
From Release 12c (12.1.0.4.0) onwards, Enterprise Manager provides the option to statistically compute metric thresholds that are adaptive in nature and this is available for all targets.
For more information about Adaptive Thresholds, see Oracle Enterprise Manager Administration Guide, Release 12c (12.1.0.4.0).
You can provide a named configuration for your target type. This quick configuration contains preconfigured metrics values and a computation mechanism.
To define a quick configuration:
Create a quick configuration file to determine the predefined values, and threshold calculation method for a group of metrics.
Example 3-9 defines a quick configuration for the Host target type.
Example 3-9 Quick Configuration for Adaptive Thresholds
<?xml version="1.0" encoding="UTF-8"?> <baselineIntegration xmlns="http://www.oracle.com/EnterpriseGridControl/BaselineIntegration/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.oracle.com/EnterpriseGridControl/BaselineIntg.xsd" targetType="host" version="12.1.0.4"> <quickConfigration> <quickConfigDescription defaultText="Default text " resourceBundle="a.b.c.abcMsg" nlsId="SEC_CONFIG" /> <baselineConfig configType="MV" subinterval="NX" interval="7" defaultText="Security Config" resourceBundle="a.b.c.abcMsg" nlsId="SEC_CONFIG"> <metricSetting metricName="memfreePct" metricGroup="Load" thrsholdMethod="SIGLVL" warnignLvl=".99" criticalLvl=".999" numOccurrence="10" insufficientDataAction="UNSET" /> <metricSetting metricName="cpuUtil" metricGroup="Load" thrsholdMethod="PCTMAX" warnignLvl="20" criticalLvl="30" numOccurrence="11" insufficientDataAction="UNSET" /> metricSetting metricName="swapUtil" metricGroup="Load" thrsholdMethod="PCTMAX" warnignLvl="40" criticalLvl="50" numOccurrence="12" insufficientDataAction="UNSET" / </baselineConfig> <baselineConfig configType="MV" subinterval="NX" interval="21" defaultText="Space Config" resourceBundle="a.b.c.abcMsg" nlsId="SPACE_CONFIG"> <metricSetting metricName="memfreePct" metricGroup="Load" thrsholdMethod="SIGLVL" numOccurrence="3" warnignLvl=".99" criticalLvl=".999" insufficientDataAction="PRESERVE" /> <metricSetting metricName="cpuUtil" metricGroup="Load" thrsholdMethod="PCTMAX" warnignLvl="25" numOccurrence="2" criticalLvl="35" insufficientDataAction="PRESERVE" /> metricSetting metricName="activeMem" metricGroup="Load" thrsholdMethod="PCTMAX" warnignLvl="45" criticalLvl="55" numOccurrence="5" insufficientDataAction="PRESERVE" / <metricSetting metricName="memUsedPct" metricGroup="Load" thrsholdMethod="PCTMAX" warnignLvl="65" criticalLvl="75" numOccurrence="2" insufficientDataAction="PRESERVE" /> </baselineConfig> </quickConfigration> </baselineIntegration>
Register the quick configuration file with Enterprise Manager by placing the file in the following location before plug-in deployment:
plugin_stage/oms/metadata/adaptiveThreshold/
For information about plug-in deployment, see Chapter 14, "Validating, Packaging, and Deploying the Plug-in".
The end user activates the quick configuration from the Cloud Control UI (From the Metric and Collection Settings page, select Advanced Threshold Management).
For information about using the Advanced Threshold Management feature, see the Oracle Enterprise Manager Administration Guide, Release 12c (12.1.0.4.0).
Table 3-4 Key Elements Used to Define Metrics
| Element | Description |
|---|---|
|
|
Required. Defines a metric group containing one or more metrics, each defined in a
|
|
|
Required when the Metric |
|
|
Defines a single metric to be collected. It includes the following attributes:
|
|
|
Defines a command to run, which returns the set of data described in the Note: You can refer to earlier defined properties using the <Property NAME="perlBin" SCOPE="SYSTEMGLOBAL">perlBin</Property> <Property NAME="command" SCOPE="GLOBAL">%perlBin%/perl</Property> The element includes a The following are among the fetchlets commonly used by plug-in developers:
For a complete list of available fetchlets and information about their usage, see Chapter 21, "Using Fetchlets". The SCOPE property defines where the property value is to be obtained. The following scope options are available:
|
|
|
Defines object identifiers (OIDs). The Management Agent uses an SNMP receivelet to listen for SNMP traps as defined in the target type's Management Information Base (MIB). The Defines a command to run, which returns the set of data described in the Note: You can refer to earlier defined properties using the <Property NAME="MatchSpecificTrap" SCOPE="GLOBAL">50</Property> <Property NAME="MatchAgentAddr" SCOPE="INSTANCE">AdminAddress</Property> The element includes a The SNMP receivelet is the only receivelet commonly used by plug-in developers. For more information about the SNMP receivelet, see Chapter 20, "Using Receivelets". The SCOPE property defines where the property value is to be obtained. The following scope options are available:
|
|
|
Used to compute aggregation metrics. Specifies the execution plan for evaluating a metric. The Management Agent runs each statement of the plan, in the order it is defined, to produce a Metric Result. The Metric Result generated as result of the evaluation of the last statement of the execution plan will be returned. |
Table 3-4 describes the key elements that define metrics. For additional information about defining metrics, see Section 3.6, "Guidelines for Creating Target Metadata".
This section provides some troubleshooting tips if you encounter any issues with your metric definitions.
To list metrics for a given target type, from a SQL*Plus session, enter the following:
select * from mgmt_metrics where target_type=target_type and type_meta_ver=max_type_meta
To check if there are any metric load issues, from a SQL*Plus session, enter the following:
select * from sysman.mgmt_system_error_log where module_name='METRIC_LOAD'
To check if there are any collection issues during the metadata load, from a SQL*Plus session, enter the following:
select * from sysman.mgmt_system_error_log where module_name='MGMT_COLLECTION.Collection Subsystem'
To check what is being collect for a specific target, from a SQL*Plus session, enter the following:
select * from sysman.gc_metric_values where entity_type=target_type and entity_name=target_name
The default collection metadata file for a target type defines the following:
The metric data (including configuration collection metric data) to be collected from targets and written to the Management Repository
The frequency of at which this metric data is collected
Thresholds that, when exceeded, will cause a Metric Alert event to be raised
An optional message to display when a threshold is exceeded
Note:
Although you can use any name for a default collection file, Oracle recommends that you use a naming convention that makes it easy to associate the collection file with the corresponding target type metadata file name. For example, using the same file name as the target type metadata file.For information about naming the target type metadata file, see Section 3.3.2, "Naming the Target Type Metadata File".
Note that the value of the TYPE attribute and the META_VER attributein the default collection metadata file must match the TYPE and the META_VER values defined in the target type metadata file to create an association between them.
As noted, you can also specify Metric Alert event conditions on each metric that will be raised as Incidents within Enterprise Manager Cloud Control. Such events are generated when a threshold specified in this file is exceeded. For example, you may want to raise a WARNING alert when CPU usage reaches 90% of capacity. You can also specify the message text to be displayed in Enterprise Manager Cloud Control when an alert event is triggered.
The EDK includes an example of a default collection file in the following location:
/samples/plugins/HostSample/stage/oms/metadata/default_collection/demo_hostsample.xml
For information about defining the elements in the default collection file, see Section 3.5.5, "Overview of Key Default Collection Metadata Elements" and Section 3.6, "Guidelines for Creating Target Metadata".
For efficiency, metrics are typically grouped together for collection, enabling certain metrics to be collected at the same time or same frequency. This is useful because it guarantees the order of execution of the metrics, which is important if some metrics rely on the results of other metrics.
Each group of metrics to be collected together is defined in a CollectionItem within the default collection file. The collection schedule for the group is defined in a Schedule element. The CollectionItem provides the end user with the most control to enable or disable metrics and to change the collection schedule.
Each metric included in the group is in turn defined within a MetricColl element within the CollectionItem. (Note that if the CollectionItem contains just a single metric, like the Response metric example shown in Section 3.4.2, "Defining the Basic Response Metric Group", it is not necessary to specify the MetricColl tag.)
Note that the UPLOAD value for the CollectionItem is set to 6, meaning that every sixth collection of data will be written to the Management Repository. Because the IntervalSchedule specifies that data will be collected every 5 minutes, the data will be written to the Management Repository every 30 minutes (or every sixth data collection).
<TargetCollection> ... <CollectionItem NAME="Perf" UPLOAD="6"> <Schedule> <IntervalSchedule INTERVAL="5" TIME_UNIT="Min"/> </Schedule> <MetricColl NAME="CPUProcessesPerf"> ... </MetricColl> <MetricColl Name="MemoryPerf"> ... </MetricColl> </CollectionItem> ... </TargetCollection>
You should consider grouping metrics into a CollectionItem if any of the following applies:
The metrics are logically related, such as all metrics related to performance
The metrics should be collected at the same frequency, such as all metrics that should be collected every 5 minutes
The metrics should be collected at roughly the same time, such as metrics collected during non-peak times
You want to collect all of the metrics, or none of the metrics, at the same time
Note that if you have metrics that will be collected on demand, grouping them will improve performance and reduce the communications required by the Management Agent and Oracle Management Service to collect and return metric data from the target.
Providing different collection intervals will provide the best flexibility to users to schedule each metric independently. Grouping together unrelated metrics is not advisable, as you will not have the ability to turn off collection of just a few metrics in the group without disabling the those metrics that you do need.
The following represents the CollectionItem entry for the basic Response metric group, which includes the Status metric. It specifies that data for this metric should be collected every 5 minutes, which is the standard collection interval for this type of metric.
A condition has been set on the Status metric. For more information about alert conditions, see Section 3.5, "Creating the Default Collection File" and Table 3-5.
Note that because the CollectionItem contains just one metric (Status), it is not necessary to include a MetricColl tag for the single metric.
<TargetCollection META_VER="2.0" TYPE="test_demo_targetType"> ... <CollectionItem NAME="Response"> <Schedule> <IntervalSchedule INTERVAL="5" TIME_UNIT="Min"/> </Schedule> <Condition COLUMN_NAME="Status" CRITICAL="0" OPERATOR="EQ" CLEAR_MESSAGE_NLSID="Response_Status_clearalertmessage" MESSAGE="Failed to connect to database instance: %oraerr%."MESSAGE_NLSID="Response_Status_alertmessage"/> </CollectionItem> ... </TargetCollection>
Example 3-10 illustrates the collection of a more advanced metric that raises a metric alert when specified WARNING and CRITICAL thresholds are exceeded. These thresholds, and the message to send to Cloud Control when they are exceeded, are defined in the Condition element.
The data for each metric is specified in a MetricColl element within a CollectionItem, as shown in Example 3-10. For a description of the elements in this example, see Table 3-5.
Example 3-10 Defining Advanced Metric Collection
<TargetCollection>
...
<CollectionItem NAME="Perf" UPLOAD="6">
<Schedule>
<IntervalSchedule INTERVAL="5" TIME_UNIT="Min"/>
</Schedule>
<MetricColl NAME="CPUProcessesPerf">
<Condition COLUMN_NAME="ProcCPU" WARNING="75" CRITICAL="90" OPERATOR="GE"
OCCURRENCES="2"
MESSAGE="The value for %columnName% is %value%%%, which is above the
critical (%critical_threshold%%%) or warning (%warning_threshold%%%)
threshold."
CLEAR_MESSAGE="The value for %columnName% is %value%%%, which is
below the critical (%critical_threshold%%%) or warning (%warning_
threshold%%%) threshold." />
</MetricColl>
</CollectionItem>
...
</TargetCollection>
Note that in addition to a message sent to Enterprise Manager when either the WARNING or CRITICAL thresholds are passed, and ”all clear” message to be sent when an alert condition no longer exists has also been defined in the CLEAR_MESSAGE attribute.
As with all other metrics, the frequency at which the configuration metric data is collected is defined default collection file. Given the size of target configuration collections and the infrequent change rate, these metrics should ideally be collected every 24 hours, during off-peak hours.
Note that the value of the TARGET_TYPE attribute of the root METADATA SNAP_TYPE attribute in the configuration metadata file must be identical the TYPE attribute of TargetCollection in the default collection file.
The following example defines the collection frequency for the HostConfig metric
<TargetCollection>
...
<CollectionItem NAME="HostSampleSnap" CONFIG="TRUE">
<Schedule OFFSET_TYPE="INCREMENTAL">
<IntervalSchedule INTERVAL="24" TIME_UNIT="Hr"/>
</Schedule>
<MetricColl NAME="HostConfig" />
</CollectionItem>
...
</TargetCollection>
Table 3-5 describes the key elements included in the default collection metadata file.
Table 3-5 Key Elements Within the Default Collection Metadata File
| Element | Description |
|---|---|
|
Required. The root element for the file. It includes a |
|
|
Defines a collection frequency and threshold values for a set of metrics. The frequency defined in the included
|
|
|
Contains an
Note: Response metrics must be collected frequently. Define the collection interval at a value between 1 minute and 5 minutes. Other metrics should be collected less frequently. Usually an interval of 15 minutes is sufficient. However, if you are defining metrics collecting a lot of data, then consider an interval of 30 minutes or 1 hour. |
|
|
Contains one or more Condition elements corresponding to a single metric group defined in a Metric element in the target type metadata file. Each condition must have an associated alert message that includes a metric description with a specified unit and the %value% placeholder for the value that causes the threshold to be raised. The NAME attribute in this element must match the NAME attribute in the corresponding Metric element. |
|
|
Defines a metric alert condition. It contains the following optional attributes:
|
This section provides some troubleshooting tips if you encounter any issues with your collection process.
To check if the collection is disabled for a specific target, from a SQL*Plus session, enter the following:
select * from sysman.mgmt_collections where object_type=2 and object_guid=target_guid and is_enabled=1
When developing target type definition files for new plug-ins, special consideration must be paid to the way in which you want a particular target type to be monitored. How a target type is monitored can greatly affect Enterprise Manager performance. Follow these general guidelines for defining target metadata and collections to optimize system performance.
Metadata is data about data. Generically, the term refers to any data used to help the identification, description, and location of a network entity. Target metadata for an Enterprise Manager target consists of the metrics a user wants to expose and the methods used to compute those metrics.
Note:
Ensure that all metrics that are viewable are categorized. At a minimum, metrics that have thresholds must be categorized so that generated incidents are categorized. For more information about categorization, see Section 3.4.5, "Categorizing Metrics".Whenever the target metadata changes, increment the metadata version (META_VER). For more information, see Section 3.3.3, "Defining the Target Type Metadata".
Performance metrics can be classified into metrics that must be computed to track performance trends and others that are more useful to drill down to get the details at a particular point in time. Real-time only metrics include those that need contextual information to return detailed information about a particular subset of the system, such as the resource utilization for specific processes, to diagnose further.
A key column in a metric is used in the management repository to trend performance data on an axis, such as the tablespace usage per database tablespace. Key-based metrics should be used to model sub-components of the target for which meaningful metric data should be collected, either for target monitoring or target diagnostic purposes. As such, only key columns that are the logical identifiers of the target sub-components should be included in the metric.
Note that including key columns for which the number of distinct values collected across a large number of targets could result in an excessive number of key values being stored in the management repository. For example, using a timestamp (or equivalent, like database SCN or UNIX ctime) as a key value will result in a new value for every collection for every target, and is therefore not advisable.
Including a combination of key columns can also be problematic. For example, if you include three key columns in a metric, in which each key can take one of 10 target-specific values (10X10x10) multiplied by the number of targets, you would be collecting data for 1000 keys per target. This could be considered excessive if more than a handful of targets are being managed.
Do not define metrics that have nonsharable and durable keys across targets and time.
You can have no key columns, but the query descriptor must return a single row.
Note:
Do not modify key columns, that is, order, data type, or number after creating a metric.In some cases, metric columns can be used to compute the values of other more interesting metric columns. When the original columns are not required, then you can mark these columns as transient so that they are not uploaded to the Management Repository, therefore saving space.
Metrics that are dependent on a duration of time must not be uploaded. Mark these types of metrics as transient. This includes delta metrics such as Request Process (last collection interval).
Metrics should contain data values for recent activity. In many cases, to do this, you must create rate metrics out of existing metrics. The COMPUTE_EXPR attribute (defined in Table 3-4) specifies the formula for calculating the value of a column. The following list provides the supported grammar for Compute Expression:
expression := (cond_expr | (cond_expr ? cond_expr : cond_expr)
cond_expr := (string_expr |
(string_expr == string_expr) |
(string_expr < string_expr) |
(string_expr > string_expr) |
(string_expr <= string_expr) |
(string_expr >= string_expr) |
(string_expr __contains string_expr) |
(string_expr __beginswith string_expr) |
(string_expr __endswith string_expr) |
(string_expr __matches string_expr) |
(string_expr __delta string_expr))
string_expr := (simple_expr |
(simple_expr __leadingchars simple_expr) |
(simple_expr __trailingchars simple_expr) |
(simple_expr __substringpos simple_expr))
simple_expr := (term |
(simple_expr + term ) |
(simple_expr - term) )
term := (unary_expr |
(term * unary_expr ) |
(term / unary_expr ) )
unary_expr := (factor |
(__is_null factor) |
(__length factor) |
(__to_upper factor) |
(__to_lower factor) |
(__ceil factor) |
(__floor factor) |
(__round factor) )
factor := ( identifier |
string_literal |
number |
'(' expression ')' )
string_literal := '\'' (character | "\\'" )* '\''
To create rate metrics from existing metrics, define the following metrics:
Calculating Delta
requests.completed.delta = (requests.completed > _requests.completed) ? (requests.completed - _requests.completed) : 0
If the current value of requests.completed is more than the previous value, then obtain delta by getting the difference between the current value and the last value. Otherwise return 0.
Calculating Rate
requests.completed (per minute) = (requests.completed > _requests.completed) ? (requests.completed - _requests.completed) *60 /__interval: 0
If the current value of requests.completed is more than the previous value, then obtain delta by getting the difference between the current value and the last value and then multiplying by 60 and dividing by the interval between 2 collections. Otherwise, return 0.
When creating metrics for custom targets, it is important to take into account the cost (CPU usage) of creating additional operating system (OS) processes. This is especially true for systems running Microsoft Windows where process creation is much more CPU intensive compared to UNIX-based systems such as Linux or Oracle Solaris. The percentage CPU utilization increases linearly with creation of child processes. To minimize process creation, avoid executing OS programs or commands from metric collection scripts. For example, when writing Perl scripts, avoid using the system function or backticks (``) to execute an OS command.
Target properties are named values that can be used for computing the metrics of the target, or for display in the home page of the target. The list of target properties is specified in the metadata to allow data driven user interfaces to register targets, and for the Management Agent to validate that a target instance is complete.
Static Instance Properties: These are properties whose values need to be specified for a target in the targets.xml entry for the target. An instance property can be marked optional if the target declaration is considered complete even without the specification of the property. The metadata specification of a target property can also provide a default value for use in a configuration user interface.
Dynamic Instance Properties: The Management Agent also allows for target instance properties to be computed. Such properties are computed using a QueryDescriptor very similar to the ones used in metrics.
Use of dynamic properties reduces the work involved in configuring a target by allowing certain properties to be computed rather than requiring the user to correctly specify their values (for example, the Version property of a database can be reliably computed given addressing information).
The Management Agent allows for the fact that the target needs to be up for the successful computation of these dynamic properties by recomputing the properties each time a target bounce is detected (each time the target status changes to Up).
The metric concept, as it pertains to the Management Agent, can be used to denote configuration and performance information.
Configuration Metrics: Configuration metrics collect data similar to target properties that denote the configuration of the target. This information is periodically refreshed and can be used to track changes in the setup of a target. The collection interval on such metrics is typically on the order of about 24 hours.
Performance Metrics: Performance metrics are used to track the responsiveness of a target. These metrics are typically collected more often than configuration metrics though the interval of some performance metrics may vary widely from those of others. Also, performance metrics usually ship with thresholds that are the basis of performance alerts for the target.
A required metric for all targets is the "Response" metric consisting of a "Status" column with a condition on it. This metric is used to track the availability of the target.
The conventions used in naming your metrics are extremely important because many areas of the Enterprise Manager user-interface are data-driven. For example, actual metric column labels and key values can be part of the page title, instruction text, or column headings. Specifically, these elements appear on the All Metrics page, Metric and Collections Settings page, Event Rules page, Group Charts page, and other pages within the Enterprise Manager user-interface. For this reason, Oracle recommends the following metric naming conventions.
Ensure that metric column names are as explicit as possible. Do not include count in the column name because it adds to the length of the name and does not provide value to the end user. For example:
Errors (per minute)
Note: Do not use Error Count (per minute).
All metric column names (labels) must be unique within a given target type and version, and easily understood by the user (metric units used as required). If the metric refers to a unit of measure, include the unit in the metric label inside a parenthesis. For example:
Network Interface Total I/O Rate (MB/sec)
Requests Processed (per minute)
Transactions Committed (%)
Metrics that are increasing values which reset at startup should not be uploaded. Mark these metrics as transient and include since startup in the metric label inside a parenthesis. For example:
Processing Time (since startup)
Errors (since startup)
Requests (since startup)
Average Execution Time (ms - since startup)
All metric column names (labels) should be self-explanatory without dependence on the metric name. For example:
Tablespace Space Used (%)
Key column names must be self-explanatory. Enterprise Manager uses these names when specifying metric thresholds or configuring notifications. For readability, the name of the key column name must fit easily within the phrase "all key column name objects". For example:
all tablespace objects
Across target versions, the same columns must use the same labels. This ensures columns, such as metric columns and short names, have the same NLS IDs across different target versions.
Collections are the mechanism by which the Management Agent periodically computes the metrics of a target and uploads the data to the Management Repository. The most important thing to keep in mind when creating the collections for a target type is to avoid overburdening the Management Repository with excess data. In a large enterprise with hundreds of Management Agents and thousands of targets, the key to scalability is to limit the amount of data collected about a target that is uploaded to the repository. This is especially important since raw data is maintained for 24 hours - rollup benefits only accrue beyond that point.
Alert messages tell the user when something is wrong. These messages should also assist the user in solving the problem. Oracle recommends following these content guidelines when writing alert messages:
Alert messages should be meaningful, and must include the metric display name, metric value and the thresholds that caused the alerts.
The most significant part of the message should be covered within the first 60 characters of the message text. The reason is that the first part of the message is the most visible to users in e-mail notifications, incident tables containing the alert message, and so on.
Include warning thresholds and critical thresholds in the alert message.
Target down messages should, in addition to indicating that the target is down, include information indicating possible reasons why the target may be down.
Include error codes and messages whenever possible.
The following is a good example of an alert message:
CPU Load (Run Queue Length averaged over 15 minutes) is %value%, crossed warning (%warning_threshold%) or critical (%critical_threshold%) threshold.
Note that you should not include information on how to resolve or diagnose the problem in the alert message. You should instead provide this content in the Guided Resolution section of Incident Manager. See Section 10.5, "Providing Content in the Guided Resolution Region" for more information.
It is important to pay attention to metric evaluation order so as to avoid metric collection failures. For example, the Response metric should be evaluated first in order to prevent a collection failure when a target is down. Also, ensure that the metric collection error is consistent. For example, you should have a new message every time that a metric is collected.
When a CollectionItem tag is used to define a collection, then the Management Agent evaluates all metrics with a collection item in order. However, collection items run independent of each other.
Note:
Programmatic logic of the Management Agent distributes the metric evaluations so that each evaluation is separated by approximately 10 seconds.In general, there is almost never a good reason to collect information at intervals smaller than 5 minutes. In the rare case where data variations occur at a smaller granularity and administrators need to be notified sooner, the Management Agent provides the capability to use a small collection interval to compute the metrics and threshold information while still only uploading data once in every nn computation cycles.
Some metrics can result in the creation of a large number of rows in a Management Repository table. In some cases, only a subset of these rows may need to be uploaded to the repository. The Management Agent allows the specification of filter conditions that can be used to find rows to skip uploading. Also, a "limit_to" clause can be used on metrics that return sorted metric data to upload only the first n rows to the repository.
To localize your target metadata:
Target metadata can optionally support localized strings, including target type display name and metric and metric column labels, enabling Enterprise Manager to display labels in the language and locale of each Enterprise Manager user. To support this feature, the target metadata file must include the RESOURCE_BUNDLE_PACKAGE property in the TargetMetadata tag. The RESOURCE_BUNDLE_PACKAGE property specifies the location of the resource properties files that contains the localized target strings. For information about the TargetMetadata tag, see Section 3.3, "Creating the Target Type Metadata File".
Use the three-part plug-in id, followed by the package selected for the resource bundles. For example, if the plug-in ID is test.group.domain, then define the resource bundle package as follows:
RESOURCE_BUNDLE_PACKAGE=test.group.domain.rsc
In the previous example, rsc is the package selected for the resource bundles. You can use any alphanumeric string for the package name but you cannot include special characters.
The strings included in the target metadata that can be externalized to the resource properties file are the Label tags associated with the target type, metric and column items.
Note:
If the resource property cannot be loaded, then the Label tag has a default value that is displayed and the NLSID property specifies the key to be used to load the string resource that will be loaded in the user's locale.You must place all of the strings defined for your target metadata in a resource properties file, named target_typeMsg.properties. Include this file in the corresponding directory in the resource deployment. For more information, see Section 3.7.4, "Package Resource Bundles".
In Example 3-11, the plug-in ID is test.group.domain and the target type is domain_widget.
Example 3-11 Defining a Resource Bundle Package for Target Metadata Localization
<TargetMetadata META_VER="1.0" TYPE="domain_widget" RESOURCE_BUNDLE_PACKGE="test.group.domain.rsc"> <Display> <Label NLSID="dom_widget">Domain Widget</Label> </Display>
For this plug-in deployment, you must have a resource properties file named test.group.domain.rsc.domain_widgetMsg.properties. This file contains all the strings for the target metadata and includes the following:
# Strings for the domain_widget target type within the test.group.domain plug-in dom_widget = Domain Widget
In the default collection metadata file, metric collection conditions can specify the following properties for the message alert and cleared message:
| MESSAGE
Specifies the default message (in English) when a condition is met. |
MESSAGE_NLS_ID
Specifies the resource identifier that will be used to locate the translated version of the message in the resource properties file associated with the target type metadata. |
| CLEAR_MESSAGE
Specifies a cleared message to be sent when an alert condition no longer exists. |
CLEAR_MESSAGE_NLS_ID
Specifies the resource identifier that will be used to locate the translated version of the cleared message in the resource properties file associated with the target type metadata. |
Example 3-12 provides an example of a metric definition that includes the resource identifier for the alert message and cleared message.
Example 3-12 Defining a Metric to Include Localization Properties
<MetricColl NAME="CPUPerf">
<Condition COLUMN_NAME="non_nice" WARNING="NotDefined" CRITICAL="NotDefined"
OPERATOR="GE"
MESSAGE="The value for %columnName% is %value%%%. It has risen above the critical (%critical_threshold%%%) or warning (%warning_threshold%%%) threshold."
MESSAGE_NLS_ID="dhs_non_nice_cond_msg"
CLEAR_MESSAGE="The value for %columnName% is %value%%%. It has fallen below the critical (%critical_threshold%%%) or warning (%warning_threshold%%%) threshold."
CLEAR_MESSAGE_NLS_ID="dhs_non_nice_clear_msg" />
Before you package the resource bundle, check the Section 3.7.4.1, "About Resource Property Bundle Content" to ensure the contents of your package are formatted correctly.
All of these resource properties files must be formatted as proper Java resource properties bundles. Include the appropriate country and locale according to the following Java specifications in the file names.
http://docs.oracle.com/javase/7/docs/api/java/util/PropertyResourceBundle.html
Character encoding must be done according to the Java language specification for those resource properties bundles that will be used for target metadata, jobs, and so on.
http://docs.oracle.com/javase/specs/jls/se5.0/html/lexical.html#3.3
Encoding of Flex resource properties files does not follow the same encoding as the Java language specification. Therefore it is necessary to separate any string resources that will be displayed in the Flex UI (MPCUI) into separate resource properties bundles. For more information, see the Flex Documentation:
http://www.adobe.com/support/documentation/en/flex/1/internationalization_flex_short/internationalization_flex_short9.html
To package resource bundles:
Add the Resource properties files to a plug-in using a JAR file that includes the plug-in staging area under the oms/archives directory from where the plug-in OPAR is created. This jar file can contain properties files only and not any other files such as Java class files, images, and so on.
Include the properties files in a directory where the path is the three part plug-in id, followed by a subpackage name of your choice. For example, if the plug-in id is test.group.domain, then the path to the resource properties files must be test.group.domain.rsc, where rsc is the subpackage selected for the resource bundles as described in Chapter 3, "Define the Resource Bundle Package".
Using the previous example, enter the following JAR command to create a JAR file to include in the oms/archives directory of the plug-in stage area:
jar cvf test_group_resources.jar test/group/domain/rsc/*
Place the JAR file in the oms/archives directory and then the EDK tools can validate and package the plug-in. For more information, see Chapter 14, "Validating, Packaging, and Deploying the Plug-in".
Note:
If the JAR file contains anything other than properties files, then the following validation error appears:Plug-ins of type MP and MPP can only contain resource bundles in archives in java properties format. Found other files in artifact. ./stage/oms/archives/test_group_resources.jar
See Also:
For examples of resource properties bundles, see the following pages from The Java Tutorial:http://docs.oracle.com/javase/tutorial/i18n/resbundle/propfile.html
Before you register a new target type, check the following list:
Target Type Name
Ensure that the target type name follows the following naming format, where plugin represents the plug-in name and type represents the target type name:
oracle_plugin_type
For example, oracle_vt_zone or oracle_emas_forms_server.
Model
Ensure that the target is a manageable entity or that it can be monitored. Also, ensure that it makes business sense to model the target type.
Ensure that the target type has a response metric and other quantifiable numeric metrics
Ensure that the target type is a required target and has an identifiable presence even if Enterprise Manager is not installed.
Identify the manageable entity class to which the target type belongs and set the property correctly.
Ensure that the Response metric has one numeric metric column only called Status
Version
Ensure that the metadata version is defined correctly. For more information about the metadata version number, see Section 3.3.3, "Defining the Target Type Metadata".
Associations
Ensure that no abstract association types are used. For example:
select assoc_type from mgmt_assoc_types where is_abstract=1
Ensure that core association types are used. For example:
select assoc_type from mgmt_assoc_types where category=1
Do not define the provided_by/relies_on_key_component allowed pair. The Service framework automatically adds a service (provided_by/relies_on_key_component allowed pair).
Properties
Do not store credentials such as user names and passwords in the target properties.
Include properties that are used for monitoring the target only in the target properties. If data is not actively used by the Management Agent, then it is not a target property.
Add a target version property to capture the target version. By default, Enterprise Manager uses a TargetVersion property to represent the target version. For more information about this property, see Table 3-2.
Test your new target type definitions by using the metric browser. The metric browser is a development utility that is an integral part of the Management Agent. As a subsystem of the Management Agent, it allows you to quickly access the metric values for targets monitored by the Management Agent without the overhead of a Management Repository or other components of the Enterprise Manager framework.
To configure the Management Agent's metric browser for debugging metrics without the Enterprise Manager Cloud Control console:
Check that the _enableMetricBrowser line in the $AGENT_HOME/sysman/config/emd.properties file is enabled, where AGENT_HOME represents the home directory of the Management Agent:
_enableMetricBrowser=True
Enter the following command to apply the changes that you made to the emd.properties file:
emctl reload agent
Open the emd.properties file and check the EMD_URL line. It has the following format:
EMD_URL=http://host:port/emd/browser/main
Alternatively, you can use the emctl command to activate the metric browser as follows:
emctl setproperty agent -name _enableMetricBrowser -value true
After the target instance has been added to the targets.xml file and the new information has been reloaded, you can view available targets and metrics through the metric browser. Access the following URL using any web browser:
http://host:port/emd/browser/main
Tip:
To find the port number used by the Management Agent, open the $AGENT_HOME/sysman/config/emd.properties file and search for the EMD_URL line.Note:
You must use the Management Agent operating system credentials to log in to the metric browser.To verify that your target metadata files are defined correctly, enter the following command from the bin directory of the EDK:
empdk validate_plugin -stage_dir plugin_stage
In the preceding command, plugin_stage represents the plug-in staging directory.
For information about the EDK, see Section 1.2, "About the Extensibility Development Kit (EDK)" and for more information about the empdk command and its usage, see Section 14.3, "Validating the Plug-in".
This section provides some troubleshooting tips if you encounter any issues with your targets.
My target is not added to Enterprise Manager
If your target is not added, do the following:
Check the Oracle Management Service trace file (emoms.trc) for exceptions. The OMS trace file is located in the EM_INSTANCE_BASE/em/OMS_NAME/sysman/log/ directory, where EM_INSTANCE_BASE is the OMS Instance Base directory (by default, this directory is under the parent directory of the Oracle Middleware Home).
grep –i EntityManager.createEntities * grep –i EntityUtil *
If your target is added to the Management Repository but not to the Management Agent, go to the agentStateDir/sysman/log directory and check the Management Agent log file (gcagent_mdu.log). This log file tracks the metadata updates to the Management Agent.
My target continues to show a pending status
If your target is monitored by the Management Agent and it shows a pending status, then do the following:
Check if the Management Agent is still monitoring the target.
To listing the name and type of each target being monitored by a Management Agent:
Change directory to the AGENT_HOME/bin directory (UNIX) or the AGENT_HOME\bin directory (Windows).
Enter the following command:
emctl config agent listtargets
Check the output for your target.
Check that the plug-in is deployed on the Management Agent by reviewing the following log file:
agent_inst/sysman/registry.xml
Check that the Management Agent received the request to add the target. Go to the agentStateDir/sysman/log directory and review the Management Agent log file (gcagent_mdu.log).
From a SQL*Plus session, run the tgtinfo.sql script, similar to:
@tgtinfo oracle_database orcl
The tgtinfo.sql script includes the following:
SELECT type_meta_ver, ':'||category_prop_1||':'||
category_prop_2||':'||
category_prop_3||':'||
category_prop_4||':'||
category_prop_5||':' category_prop,
target_guid,
TO_CHAR(load_timestamp,'DD_MON-YY HH24:MI:SS'),
timezone_region,owner,host_name,emd_url,broken_reason,broken_str,manage_status,
promote_status,
dynamic_property_status
FROM sysman.em_targets
WHERE target_type='&&1'
AND target_name='&&2'
/
Note:
If you are having issues running the script, edit the script to replace&&1 with the type of the target and replace &&2 with the name of the target.The output from the script includes the following information:
TARGET_TYPE
Name of the target, such as oracle_database
TYPE_META_VER
Metadata version number. Check that the metadata version is correct for the target.
CATEGORY_PROP_1
Category properties can be used to distinguish different metric definitions based on different configurations. Check that the value is correct for the target.
BROKEN_REASON
If this value is greater than 0, then target is broken (for example, the target could not be saved or it is missing required properties). The BROKEN_STR value will provide a reason as to why the target is broken.
MANAGE_STATUS
The manage status of the target. Possible values include:
0: Ignored
1: Not yet managed
2: Managed
3: Managed target component
PROMOTE_STATUS
The promotion status of the target. Possible values include:
0: Cannot promote (an existence-only entity)
1: Eligable for promotion
2: Promotion in progress
3: Promoted to Management Agent
4: Promotion in progress but target was added to the Management Agent previously
DYNAMIC_PROPERTY_STATUS
Status of the dynamic properties. Possible values include:
0: Dynamic properties have not been uploaded by the Management Agent
1: Dynamic properties are uploaded by the Management Agent