Using Metric Extensions

13 Using Metric Extensions

Metric extensions provide you with the ability to extend Oracle's monitoring capabilities to monitor conditions specific to your IT environment. This provides you with a comprehensive view of your environment. Furthermore, metric extensions allow you to simplify your IT organization's operational processes by leveraging Enterprise Manager as the single central monitoring tool for your entire datacenter instead of relying on other monitoring tools to provide this supplementary monitoring.

This chapter covers the following:

What are Metric Extensions?

Metric extensions allow you to create metrics on any target type. Unlike user-defined metrics (used to extend monitoring in previous Enterprise Manager releases), metric extensions allow you to create full-fledged metrics for a multitude of target types, such as:

Hosts
Databases
Fusion Applications
IBM Websphere
Oracle Exadata databases and storage servers
Siebel components
Oracle Business Intelligence components

You manage metric extensions from the Metric Extensions page. This page lists all metric extensions in addition to allowing you to create, edit, import/export, and deploy metric extensions.

Graphic shows the metric extension home page.

The cornerstone of the metric extension is the Oracle Integration Adapter. Adapters provide a means to gather data about targets using specific protocols. Adapter availability depends on the target type your metric extension monitors.

How Do Metric Extensions Differ from User-defined Metrics?

In previous releases of Enterprise Manager, user-defined metrics were used to extend monitoring capability in a limited fashion: user-defined metrics could be used to collect point values through execution of OS scripts and a somewhat more complex set of values (one per object) through SQL. Unlike metric extensions, user-defined metrics have several limitations:

Limited Integration: If the OS or SQL user-defined metric executed custom scripts, or required atonal dependent files, the user needed to manually transfer these files to the target's file system.
Limited Application of Query Protocols: OS user-defined metrics cannot model child objects of servers by returning multiple rows from a metric (this capability only exists for SQL user-defined metrics).
Limited Data Collection: Full-fledged Enterprise Manager metrics can collect multiple pieces of data with a single query and reflect the associated data in alert context. However, in the case of user-defined metrics, multiple pieces of data must be collected by creating multiple user-defined metrics. Because the data is being collected separately, it is not possible to refer to the associated data when alerts are generated.
Limited Query Protocols: User-defined metrics can only use the "OS" and "SQL" protocols, unlike metric extensions which can use additional protocols such as SNMP and JMX.
Limited Target Application: User-defined metrics only allow OS user-defined metrics against host targets and SQL user-defined metrics against database targets. No other target types are permitted. If, for example, you want to deploy a user-defined metric against WebLogic instances in your environment, you will not be able to do so since it is neither a host or database target type.

Most importantly, the primary difference between metric extensions and user-defined metrics is that, unlike user-defined metrics, metric extensions are full-fledged metrics similar to Enterprise Manager out-of-box metrics. They are handled and exposed in all Enterprise Manager monitoring features as any Enterprise Manager-provided metric and will automatically apply to any new features introduced.

Metric Extension Lifecycle

Developing a metric extension involves the same three phases you would expect from any programmatic customization:

Developing Your Metric Extension
Testing Your Metric Extension
Deploying and Publishing Your Metric Extension

Graphic shows the metric extension lifecycle.

Developing Your Metric Extension

The first step is to define your monitoring requirements. This includes deciding the target type, what data needs to be collected, what mechanism (adapter) can be used to collect that data, and if elevated credentials are required. After making these decisions, you are ready to begin developing your metric extension. Enterprise Manager provides an intuitive user interface to guide you through the creation process.

Graphic shows the General properties page of the metric extension creation wizard.

The metric extension wizard allows you to develop and refine your metric extension in a completely editable format. And more importantly, allows you to interactively test your metric extension against selected targets without having first to deploy the extension to a dedicated test environment. The Test page allows you to run real-time metric evaluations to ensure there are no syntactical errors in your script or metric extension definition.

When you have completed working on your metric extension, you can click Finish to exit the wizard. The newly created metric extension appears in the Metric Extension Library where it can be accessed for further editing or saved as a deployable draft that can be tested against multiple targets.

Note:

You can edit a metric extension only if its status is editable. Once it is saved as a deployable draft, you must create a new version to implement further edits.

Testing Your Metric Extension

Once your metric extension returns the expected data during real-time target testing, you are ready to test its robustness and actual behavior in Enterprise Manager by deploying it against targets and start collecting data. At this point, the metric extension is still private (only the developer can deploy to targets), but is identical to Oracle out-of-box metrics behavior wise. This step involves selecting your editable metric extension in the library and generating a deployable draft.

You can now deploy the metric extension to actual targets by going through the “Deploy To Targets…" action. After target deployment, you can review the metric data returned and test alert notifications. As mentioned previously, you will not be able to edit the metric extension once a deployable draft is created: You must create a new version of the metric extension.

Deploying Your Metric Extension

After rigorous testing through multiple metric extension versions and target deployments, your metric extension is ready for deployment to your production environment. Until this point, your metric extension is only viewable by you, the metric extension creator. To make it accessible to all Enterprise Manager administrators, it must be published. From the Actions menu, select Publish Metric Extension.

Now that your metric extension has been made public, your metric extension can be deployed to intended production targets. If you are monitoring a small number of targets, you can select the Deploy To Targets menu option and add targets one at a time. For large numbers of targets, you deploy metric extensions to targets using monitoring templates. An extension is added to a monitoring template in the same way a full-fledged metric is added. The monitoring template is then deployed to the targets.

Note:

You cannot add metric extensions to monitoring templates before publishing the extension. If you attempt to do so, the monitoring template page will warn you about it, and will not proceed until you remove the metric extension.

Note:

In the case of a metric extension deployment missing from the agent, or a target's metric extension attachment missing from agent, try using the EM CLI verb resync_target. For more information, see resync_target.

Updating Metric Extensions

Beginning with Enterprise Manager Release 12.1.0.4, metric extensions can be updated using the Enterprise Manager Self-update feature. See Updating Cloud Control for more information.

Working with Metric Extensions

Most all metric extension operations can be carried out from the Metric Extension home page. If you need to perform operations on published extensions outside of the UI, Enterprise Manger also provides EM CLI verbs to handle such operations as importing/exporting metric extensions to archive files and migrating legacy user-defined metrics to metric extensions. This section covers metric extension operations carried out from the UI.

Administrator Privilege Requirements

In order to create, edit, view, deploy or undeploy metric extensions, you must have the requisite administrator privileges. Enterprise Manager administrators must have the following privileges:

Create Metric Extension: System level access that:

Lets administrators view and deploy metric extensions

Allows administrators to edit and delete extensions.
Edit Metric Extension: Lets users with "Create Metric Extension" privilege edit and create next versions of a particular metric extensions. The metric extension creator has this privilege by default. This privilege must be granted on a per-metric extension basis.
Full Metric Extension: Allows users with 'Create Metric Extension' privilege to edit and create new versions of a particular metric extension.
Manage Metrics: Lets users deploy and un-deploy extensions on targets

Note: The Manage Metrics privilege must be granted on a per-target basis.

Granting Create Metric Extension Privilege

To grant create metric extension privileges to another administrator:

From the Setup menu, select Security, then select Administrators.
Choose the Administrator you would like to grant the privilege to.
Click Edit.
Go to the Resource Privileges tab, and click Manage Privilege Grants for the Metric Extension resource type.
Under Resource Type Privileges, click the Create Metric Extension check box.
Click Continue, review changes, and click Finish in the Review tab.

Managing Administrator Privileges

Before an Enterprise Manager administrator can edit or delete a metric extension created by another administrator, that administrator must have been granted requisite access privileges. Edit privilege allows editing and creating next versions of the extension. Full privilege allows the above operations and deletion of the extension.

To grant edit/full access to an existing metric extension to another administrator:

From the Setup menu, select Security, then select Administrators.
Choose the Administrator you would like to grant access to.
Click Edit.
Go to Resource Privileges and click Manage Privilege Grants (pencil icon) for the Metric Extensions resource type.
Under Resource Privileges, you can search for and add existing metric extensions. Add the metric extensions you would like to grant privileges to. This allows the user to edit and create next versions of the metric extension.

On this page, you can also grant an administrator the Create Metric Extension privilege, which will allow them to manage metric extension access. See "Managing Administrator Access to Metric Extensions" for more information.
If you would additionally like to allow delete operations, then click the pencil icon in the Manage Resource Privilege Grants column, and select Full Metric Extension privilege in the page that shows up.
Click Continue, review changes, and click Finish in the review tab.

Managing Administrator Access to Metric Extensions

Administrators commonly share the responsibility of monitoring and managing targets within the IT environment. Consequently, creating and maintaining metric extensions becomes a collaborative effort involving multiple administrators. Metric extension owners can control access directly from the metric extension UI.

Granting Full/Edit Privileges on a Metric Extension

As metric extension owner or Super Administrator, perform the following actions to assign full/edit privileges on a metric extension to another administrator:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
Choose a metric extension requiring update.
From the Actions menu, select Manage Access.
Click Add. The administrator selection dialog box appears. You can filter the list by administrator, role, or both.
Choose one or more administrators/roles from the list.
Click Select. The chosen administrators/roles appear in the access list.

In the Privilege column, Edit is set by default. Choose Full from the drop-down menu to assign Full privileges on the metric extension.

Edit Privilege: Allows an administrator to make changes to the metric extension but not delete it.

Full Privilege: Allows an administrator to edit and also delete the metric extension. The privilege granted to a user or role applies to all versions of the metric extension.
Click OK.

Revoking Access Privileges on a Metric Extension

As metric extension owner or Super Administrator, perform the following actions to revoke metric extension privileges assigned to another administrator:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
Choose a metric extension requiring update.
From the Actions menu, select Manage Access.
Choose one or more administrators/roles from the list.
Click Remove. The chosen administrators/roles is deleted from the access list.
Click OK.

Enterprise Manager allows metric extension ownership to be transferred from the current owner of the metric extension to another administrator as long as that administrator has been granted the Create Metric Extension privilege.

Note:

The Enterprise Manager Super Administrator has full managerial access to all metric extensions (view, edit, and ownership transfer).

As mentioned above, manage access is only enabled for the owner of the extension or an Enterprise Manager Super User. Once the ownership is transferred, the previous owner does not have any management privileges on the metric extension unless explicitly granted before ownership transfer. The Change Owner option is only available to users and not roles.

Manage access allows the metric extension owner or Super Administrator to grant other Enterprise Manager users or roles the ability to edit, modify, or delete metric extensions.

Transferring Metric Extension Ownership

Note:

The Enterprise Manager Super Administrator has full managerial access to all metric extensions (view, edit, and ownership transfer).

Manage access allows the metric extension owner or Super Administrator to grant other Enterprise Manager users or roles the ability to edit, modify, or delete metric extensions.

Creating a New Metric Extension

To create a new metric extension:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
From the Create menu, select Metric Extension. Enterprise Manager will determine whether you have the Create Extension privilege and guide you through the creation process.
Decide on a metric extension name. Be aware that the name (and Display Name) must be unique across a target type.
Enter the general parameters.
The selected Adapter type defines the properties you must specify in the next step of the metric extension wizard. The following adapter types are available:
- OS Command Adapter - Single Column
  
  Executes the specified OS command and returns the command output as a single value. The metric result is a 1 row, 1 column table.
- OS Command Adapter- Multiple Values
  
  Executes the specified OS command and returns each command output line as a separate value. The metric result is a multi-row, 1 column table.
- OS Command Adapter - Multiple Columns
  
  Executes the specified OS command and parses each command output line (delimited by a user-specified string) into multiple values. The metric result is a mult-row, multi-column table.
- SQL Adapter
  
  Executes custom SQL queries or function calls against single instance databases and instances on Real Application Clusters (RAC).
- SNMP (Simple Network Management Protocol) Adapter
  
  Allow Enterprise Manager Management Agents to query SNMP agents for Management Information Base (MIB) variable information to be used as metric data.
- JMX (Java Management Extensions) Adapter
  
  Retrieves JMX attributes from JMX-enabled servers and returns these attributes as a metric table.
Refer to the Adapters section for specific information on the selected adapter needed in the Adapter page (step 2) of the wizard.

Note:

Be aware that if you change the metric extension Adapter, all your previous adapter properties (in Step 2) will be cleared.

Collection Schedule

You defined the frequency with which metric data is collected and how it is used (Alerting Only or Alerting and Historical Trending) by specifying collection schedule properties.

Depending on the target type selected, an Advanced option region may appear. This region may (depending on the selected target type) contain one or two options that determine whether metric data continues to be collected under certain target availability/alert conditions. The options are:
- Option 1: Continue metric data collection even if the target is down. This option is visible for all target types except for Host target types as it is not possible to collect metric data when the host is down.
- Option 2: Continue metric data collection when an alert severity is raised for a specific target metric. This metric is defined in such a way (AltSkipCondition element is defined on this metric) that when a severity is generated on this metric, the metric collections for other target metrics are stopped. The explanatory text above the checkbox for this option varies depending on the selected target type.
  
  The Management 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. If the AltSkipCondition element is defined for that target metric, other metrics are skipped whenever there is an error in evaluating the Response metric or there is a non-clear severity on the Response:Status metric. There are two situations where a metric collection will be skipped or not happen:
  - When a target is down (option 1). This is same as the Severity on Response/Status metric.
  - When a target is UP, but there is a severity on any other metric. Such conditions are called Alt Skip (Alternate Skip) conditions.
  Option 2 is only visible if an AltSkipCondition defined for one of the target's metrics. For example, this option will not be visible if the selected target type is Oracle Weblogic Domain, but will be visible if the selected target type is Database Instance.
  
  The following graphic shows the Advanced collection schedule options.
From the Columns page, add metric columns defining the data returned from the adapter. Note that the column order should match the order with which the adapter returns the data.
- Column Type
  
  A column is either a Key column, or Data column. A Key column uniquely identifies a row in the table. For example, employee ID is a unique identifier of a table of employees. A Data column is any non-unique data in a row. For example, the first and last names of an employee. You can also create rate and delta metric columns based on an existing data column. See Rate and Delta Metric Columns below.
- Value Type
  
  A value type is Number or String. This determines the alert comparison operators that are available, and how Enterprise Manager renders collection data for this metric column.
- Alert Thresholds
  
  The Comparison Operation, Warning, and Critical fields define an alert threshold.
- Alert Thresholds By Key
  
  The Comparison Operation, Warning Thresholds By Key, and Critical Thresholds By Key fields allow you to specify distinct alert thresholds for different rows in a table. This option becomes available if there are any Key columns defined. For example, if your metric is monitoring CPU Usage, you can specify a different alert threshold for each distinct CPU. The syntax is to specify the key column values in a comma separated list, the "=" symbol, followed by the alert threshold. Multiple thresholds for different rows can be separated by the semi-colon symbol ";". For example, if the key columns of the CPU Usage metric are cpu_id and core_id, and you want to add a warning threshold of 50% for procecessor1, core1, and a threshold of 60% for processor2, core2, you would specify: procecessor1,core1=50;processor2,core2=60
- Manually Clearable Alert
  
  Note:
  
  You must expand the Advanced region in order to view the Manually Clearable Alert option.
  
  If this option is set to true, then the alert will not automatically clear when the alert threshold is no longer satisfied. For example, if your metric is counting the number of errors in the system log files, and you set an alert threshold of 50, if an alert is raised once the threshold is met, the alert will not automatically clear once the error count falls back below 50. The alert will need to be manually cleared in the Alerts UI in the target home page or Incident Manager.
- Number of Occurrences Before Alert
  
  The number of consecutive metric collections where the alert threshold is met, before an alert is raised.
- Alert Message / Clear Message
  
  The message that is sent when the alert is raised / cleared. Variables that are available for use are: %columnName%, %keyValue%, %value%, %warning_threshold%, %critical_threshold%
  
  You can also retrieve the value of another column by surrounding the desired column name with "%". For example, if you are creating an alert for the cpu_usage column, you can get the value of the core_temperature column by using %core_temperature%. Note that the same alert / clear message is used for warning or critical alerts.
  
  Note:
  
  Think carefully and make sure all Key columns are added, because you cannot create additional Key columns in newer versions of the metric extension. Once you click Save As Deployable Draft, the Key columns are final (edits to column display name, alert thresholds are still allowed). You can still add new Data columns in newer versions. Also be aware that some properties of existing Data columns cannot be changed later, including Column Type, Value Type, Comparison Operator (you can add a new operator, but not change an existing operator), and Manually Clearable Alert.
- Metric Category
  
  The metric category this column belongs to.
Rate and Delta Metric Columns

You can create additional metric columns based on an existing data column that measures the rate at which data changes or the difference in value (delta) since the last metric collection. The rate/delta metric definition will be allowed when a metric's collection frequency is periodic. For example, collected every 10 minutes. Converseley, a metric that is computed every Monday and Tuesday only cannot have a rate/delta metric as data sampling is too infrequent.

After at least one data column has been created, three additional options appear in the Add menu as shown in the following graphic.
- Add Delta metric columns based on another metric column
  
  Example: You want to know the difference in the table space used since the last collection.
  
  Delta Calculation:
  
  current metric value - previous metric value
- Add Rate Per Minute metric column based on another metric column
  
  Example: You want to know the average table space usage per minute based on the table space column metric which is collected every 1 hr.
  
  Rate Per Minute Calculation:
  
  (current metric value - previous metric value)/ collection schedule
  
  where the collection schedule is in minutes.
- Add Rate Per Five Minutes metric column based on another metric column
  
  Example: You want to know the average table space usage every five minutes based on the table space column which is collected say every 1 hour]
  
  Rate Per Five Minute Calculation:
  
  [(current metric value - previous metric value)/ collection schedule ] * 5
  
  where the collection schedule is in minutes.
To create a rate/delta metric column, click on an existing data column in the table and then select one of the rate/delta column options from the Add menu.
From the Credentials page, you can override the default monitoring credentials by using custom monitoring credential sets. By default, the metric extension wizard chooses the existing credentials used by Oracle out-of-box metrics for the particular target type. For example, metric extensions will use the dbsnmp user for database targets. You have the option to override the default credentials, by creating a custom monitoring credential set through the "emcli create_credential_set" command. Refer to the Enterprise Manager Command Line Interface Guide for additional details. Some adapters may use additional credentials, refer to the Adapters section for specific information.
From the Test page, add available test targets.
Click Run Test to validate the metric extension. The extension is deployed to the test targets specified by the user and a real-time collection is executed. Afterwards, the metric extension is automatically undeployed. The results and any errors are added to the Test Results region.
Repeat the edit /test cycle until the metric extension returns data as expected.
Click Finish.

Creating a New Metric Extension (Create Like)

To create a new metric extension based on an existing metric extension:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
From the Metric Extensions page, determine which extensions are accessible. The page displays the list of metric extensions along with target type, owner, production version and deployment information.
Select an existing metric extension.
From the Actions menu, select Create Like. Enterprise Manager will determine whether you have the Create Extension privilege and guide you through the creation process.
Make desired modifications.
From the Test page, add available test targets.
Click Run Test to validate the metric extension. The extension is deployed to the test targets specified by the user and a real-time collection is executed. Afterwards, the metric extension is automatically undeployed. The results and any errors are added to the Test Results region.
Repeat the edit /test cycle until the metric extension returns data as expected.
Click Finish.

Editing a Metric Extension

Before editing an existing metric extension, you must have Edit privileges on the extension you are editing or be the extension creator. Note: Once a metric extension is saved as a deployable draft, it cannot be edited, you can only create a new version.

To edit an existing metric extension:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
From the Metric Extensions page, determine which extensions are accessible. The page displays the list of metric extensions along with target type, owner, production version and deployment information.
Select the metric extension to be edited.
From the Actions menu, select Edit.
Update the metric extension as needed.
From the Test page, add available test targets.
Click Run Test to validate the metric extension. The extension is deployed to the test targets specified by the user and a real-time collection is executed. Afterwards, the metric extension is automatically undeployed. The results and any errors are added to the Test Results region.
Repeat the edit /test cycle until the metric extension returns data as expected.
Click Finish.

Creating the Next Version of an Existing Metric Extension

Before creating the next version of an existing metric extension, you must have Edit privileges on the extension you are versioning or be the extension creator.

To create next version of an existing metric extension:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
From the Metric Extensions page, determine which extensions are accessible. The page displays the list of metric extensions along with target type, owner, production version and deployment information.
Select the metric extension to be versioned.
From the Actions menu, select Create Next Version.
Update the metric extension as needed. The target type, and extension name cannot be edited, but all other general properties can be modified. There are also restrictions on metric columns modifications. See Note in Creating a New Metric Extension section for more details.
From the Test page, add available test targets.
Click Run Test to validate the metric extension. The extension is deployed to the test targets specified by the user and a real-time collection is executed. Afterwards, the metric extension is automatically undeployed. The results and any errors are added to the Test Results region.
Repeat the edit /test cycle until the metric extension returns data as expected.
Click Finish.

Importing a Metric Extension

Metric extensions can be converted to portable, self-contained packages that allow you to move the metric extension to other Enterprise Manager installations, or for storage/backup. These packages are called Metric Extension Archives (MEA) files.

MEA files are zip files containing all components that make up the metric extension: metric metadata, collections, and associated scripts/jar files. Each MEA file can contain only one metric extension. To add the metric extension back to your Enterprise Manager installation, you must import the metric extension from the MEA.

To import a metric extension from an MEA file:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
Click Import.
Browse to file location, and select the MEA file. Enterprise Manager checks if the target type and metric extension name combination is already used in the system. If not, the system will create a new metric extension. If the extension name is already in use, the system will attempt to create a new version of the existing extension using the MEA contents. This will require the MEA to contain a superset of all the existing metric extension's metric columns. You also have the option to rename the metric extension.
Clicking on OK creates the new metric extension or the new version of an existing metric extension.
From the Actions menu, select Edit to verify the entries.
From the Test page, add available test targets.
Click Run Test to validate the metric extension. The extension is deployed to the test targets specified by the user and a real-time collection is executed. Afterwards, the metric extension is automatically undeployed. The results and any errors are added to the Test Results region.
Repeat the edit /test cycle until the metric extension returns data as expected.
Click Finish.

Exporting a Metric Extension

Existing metric extensions can be package as self-contained zip files (exported) for portability and/or backup and storage.

To export an existing metric extension:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
From the Metric Extensions page, determine which extensions are accessible. The page displays the list of metric extensions along with target type, owner, production version and deployment information.
Select the metric extension to be exported.
From the Actions menu, select Export. Enterprise Manager prompts you to enter the name and location of the MEA file that is to be created.
Enter the name and location of the package. Enterprise Manager displays the confirmation page after the export is complete.

Note: You can only export Production, Deployable Draft and Published metric extension versions.
Confirm the export file is downloaded.

Deleting a Metric Extension

Initiating the deletion of a metric extension is simple. However, the actual deletion triggers a cascade of activity by Enterprise Manager to completely purge the metric extension from the system. This includes closing open metric alerts, and purging collected metric data (if the latest metric extension version is deleted).

Before a metric extension version can be deleted, it must be undeployed from all targets, and removed from all monitoring templates (including templates in pending apply status).

To delete a metric extension:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
From the Metric Extensions page, determine which extensions are accessible. The page displays the list of metric extensions along with target type, owner, production version and deployment information.
Select the metric extension that is to be deleted.
From the Actions menu, select Delete. Enterprise Manager prompts you to confirm the deletion.
Confirm the deletion.

Deploying Metric Extensions to a Group of Targets

A metric extension must be deployed to a target in order for it to begin collecting data.

To deploy a metric extension to one or more targets:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
From the Metric Extensions page, determine which extensions are accessible. The page displays the list of metric extensions along with target type, owner, production version and deployment information.
Select the metric extension that is to be deployed.
From the Actions menu, select Manage Target Deployments. The Manage Target Deployments page appears showing you on which target(s) the selected metric extension is already deployed.
Return to the Metric Extensions page.
Select the metric extension.
From the Actions menu, select Deploy to Targets. Enterprise Manager determines whether you have "Manage Target Metrics" privilege, and only those targets where you do show up in the target selector.
Add the targets where the metric extension is to be deployed and click Submit. Enterprise Manager submits a job deploying the metric extension to each of the targets. A single job is submitted per deployment request.
You are automatically redirected to the Pending Operations page, which shows a list of currently scheduled, executing, or failed metric extension deploy operations. Once the deploy operation completes, the entry is removed from the pending operations table.

Creating an Incident Rule to Send Email from Metric Extensions

One of the most common tasks administrators want Enterprise Manager to perform is to send an email notification when a metric alert condition occurs. Specifically, Enterprise Manager monitors for alert conditions defined as incidents. For a given incident you create an incident rule set to tell Enterprise Manager what actions to take when an incident occurs. In this case, when an incident consisting of an alert condition defined by a metric extension occurs, you need to create an incident rule to send email to administrators. For instructions on sending email for metric alerts, see "Sending Email for Metric Alerts".

For information incident management see Using Incident Management.

Updating Older Versions of Metric Extensions Already Deployed to a Group of Targets

When a newer metric extension version is published, you may want to update any older deployed instances of the metric extension.

To update old versions of the metric extension already deployed to targets:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
From the Metric Extensions page, determine which extensions are accessible. The page displays the list of metric extensions along with target type, owner, production version and deployment information.
Select the metric extension to be upgraded.
From the Actions menu, select Manage Target Deployments. The Manage Target Deployments page appears showing a list of targets where the metric extension is already deployed.
Select the list of targets where the extension is to be upgraded and click Upgrade. Enterprise Manager submits a job for the deployment of the newest Published metric extension to the selected targets. A single job is submitted per deployment request.
You are automatically redirected to the Pending Operations page, which shows a list of currently scheduled, executing, or failed metric extension deploy operations. Once the deploy operation completes, the entry is removed from the pending operations table.

Creating Repository-side Metric Extensions

Beginning with Enterprise Manager Release 12.1.0.4, you can create repository-side metric extensions. This type of metric extension allows you to use SQL scripts to extract information directly from the Enterprise Manager repository and raise alerts for the target against which the repository-side extension is run. For example, you can use repository-side metric extensions to raise an alert if the total number of alerts for a host target is greater than 5. Or perhaps, raise an alert if the CPU utilization on that host is greater than 95% AND the number of process running on that host is greater than 500. Repository-side metrics allows you to monitor your Enterprise Manager infrastructure with greater flexibility.

To create a repository-side metric:

From the Enterprise menu, select Monitoring, then select Metric Extensions.
From the Create menu, select Repository-side Metric Extension. Enterprise Manager will determine whether you have the Create Extension privilege and guide you through the creation process.
Decide on a target type and metric extension name. Be aware that the name (and Display Name) must be unique across a target type.
Enter the general parameters.

Collection Schedule

You defined the frequency with which metric data is collected and how it is used (Alerting Only or Alerting and Historical Trending) by specifying collection schedule properties.
Create the SQL query to be run against the Enterprise Manager Repository. Explicit instructions for developing the query as well as examples are provide on the SQL Query page.

Click Validate SQL to test the query.

If you already have a SQL script, you can click Upload to load the SQL from an external file.
From the Columns page, you can view/edit columns returned by the SQL query. You may edit the columns, however, you cannot add or delete columns from this page.
- Column Type
  
  A column is either a Key column, or Data column. A Key column uniquely identifies a row in the table. For example, employee ID is a unique identifier of a table of employees. A Data column is any non-unique data in a row. For example, the first and last names of an employee. You can also create rate and delta metric columns based on an existing data column. See Rate and Delta Metric Columns below.
- Value Type
  
  A value type is Number or String. This determines the alert comparison operators that are available, and how Enterprise Manager renders collection data for this metric column.
- Alert Thresholds
  
  The Comparison Operation, Warning, and Critical fields define an alert threshold.
- Alert Thresholds By Key
  
  The Comparison Operation, Warning Thresholds By Key, and Critical Thresholds By Key fields allow you to specify distinct alert thresholds for different rows in a table. This option becomes available if there are any Key columns defined. For example, if your metric is monitoring CPU Usage, you can specify a different alert threshold for each distinct CPU. The syntax is to specify the key column values in a comma separated list, the "=" symbol, followed by the alert threshold. Multiple thresholds for different rows can be separated by the semi-colon symbol ";". For example, if the key columns of the CPU Usage metric are cpu_id and core_id, and you want to add a warning threshold of 50% for procecessor1, core1, and a threshold of 60% for processor2, core2, you would specify: procecessor1,core1=50;processor2,core2=60
- Manually Clearable Alert
  
  Note:
  
  You must expand the Advanced region in order to view the Manually Clearable Alert option.
  
  If this option is set to true, then the alert will not automatically clear when the alert threshold is no longer satisfied. For example, if your metric is counting the number of errors in the system log files, and you set an alert threshold of 50, if an alert is raised once the threshold is met, the alert will not automatically clear once the error count falls back below 50. The alert will need to be manually cleared in the Alerts UI in the target home page or Incident Manager.
- Number of Occurrences Before Alert
  
  The number of consecutive metric collections where the alert threshold is met, before an alert is raised.
- Alert Message / Clear Message
  
  The message that is sent when the alert is raised / cleared. Variables that are available for use are: %columnName%, %keyValue%, %value%, %warning_threshold%, %critical_threshold%
  
  You can also retrieve the value of another column by surrounding the desired column name with "%". For example, if you are creating an alert for the cpu_usage column, you can get the value of the core_temperature column by using %core_temperature%. Note that the same alert / clear message is used for warning or critical alerts.
  
  Note:
  
  Think carefully and make sure all Key columns are added, because you cannot create additional Key columns in newer versions of the metric extension. Once you click Save As Deployable Draft, the Key columns are final (edits to column display name, alert thresholds are still allowed). You can still add new Data columns in newer versions. Also be aware that some properties of existing Data columns cannot be changed later, including Column Type, Value Type, Comparison Operator (you can add a new operator, but not change an existing operator), and Manually Clearable Alert.
- Metric Category
  
  The metric category this column belongs to.
- Add Delta metric columns based on another metric column
  
  Example: You want to know the difference in the table space used since the last collection.
  
  Delta Calculation:
  
  current metric value - previous metric value
- Add Rate Per Minute metric column based on another metric column
  
  Example: You want to know the average table space usage per minute based on the table space column metric which is collected every 1 hr.
  
  Rate Per Minute Calculation:
  
  (current metric value - previous metric value)/ collection schedule
  
  where the collection schedule is in minutes.
- Add Rate Per Five Minutes metric column based on another metric column
  
  Example: You want to know the average table space usage every five minutes based on the table space column which is collected say every 1 hour]
  
  Rate Per Five Minute Calculation:
  
  [(current metric value - previous metric value)/ collection schedule ] * 5
  
  where the collection schedule is in minutes.
To create a rate/delta metric column, click on an existing data column in the table and then select one of the rate/delta column options from the Add menu.
From the Test page, add available test targets.
Click Run Test to validate the metric extension. The extension is deployed to the test targets specified by the user and a real-time collection is executed. Afterwards, the metric extension is automatically undeployed. The results and any errors are added to the Test Results region.
Repeat the edit /test cycle until the metric extension returns data as expected.
Click Finish.

Adapters

Oracle Integration Adapters provide comprehensive, easy-to-use monitoring connectivity with a variety of target types. The adapter enables communication with an enterprise application and translates the application data to standards-compliant XML and back.

The metric extension target type determines which adapters are made available from the UI. For example, when creating a metric extension for an Automatic Storage Management target type, only three adapters (OS Command-Single Column, OS Command-Multiple Columns, and SQL) are available from the UI.

A target type's out-of-box metric definition defines the adapters for which it has native support, and only those adapters will be shown in the UI. No other adapters are supported for that target type.

A complete list of all adapters is shown below.

OS Command Adapter - Single Column

Executes the specified OS command and returns the command output as a single value. The metric result is a 1 row, 1 column table.

Basic Properties

The complete command line will be constructed as: Command + Script + Arguments.

Command - The command to execute. For example, %perlBin%/perl. The complete command line will be constructed as: Command + Script + Arguments.
Script - A script to pass to the command. For example, %scriptsDir%/myscript.pl. You can upload custom files to the agent, which will be accessible under the %scriptsDir% directory.
Arguments - Additional arguments to be appended to the Command.

Advance Properties

Input Properties - Additional properties can be passed to the command through its standard input stream. This is usually used for secure content, such as username or passwords, that you don't want to be visible to other users. For example, you can add the following Input Property:

Name=targetName, Value=%NAME%

which the command can read through it's standard input stream as "STDINtargetName=<target name>".
Environment Variables - Additional properties can be accessible to the command from environment variables. For example, you can add Environment Variable: Name=targetType, Value="%TYPE%", and the command can access the target type from environment variable "ENVtargetType".

Note:
Value="%TYPE%" may not be applicable for certain target-types (for example: host, wls). For such target types, use Value=TYPE instead.

Credentials

Host Credentials - The credential used to launch the OS Command.
Input Credentials - Additional credentials passed to the OS Command's standard input stream.

Example 1

Read the contents of a log file, and dump out all lines containing references to the target.

Approach 1 - Use the grep command, and specify the target name using %NAME% parameter.

Command = /bin/grep %NAME% mytrace.log
Approach 2 - Run a perl script

Command = %perlBin%/perl

Script = %scriptsDir%/filterLog.pl

Input Properties:

targetName = %NAME%

targetType = %TYPE%

filterLog.pl:

require "emd_common.pl";

my %stdinVars = get_stdinvars();
my $targetName = $stdinVars{"targetName"};
my $targetType = $stdinVars{"targetType"};
open (MYTRACE, mytrace.log);
foreach $line (<MYTRACE >)
{
    # Do line-by-line processing
}

close (MYTRACE);

Example 2

Connect to a database instance from a PERL script and query the HR.JOBS sample schema table.

Approach 1 - Pass credentials from target type properties into using Input Properties:

Command = %perlBin%/perl

Script = %scriptsDir%/connectDB.pl

Input Properties:

EM_DB_USERNAME = %Username%

EM_DB_PASSWORD = %Password%

EM_DB_MACHINE = %MachineName%

EM_DB_PORT = %Port%

EM_DB_SID = %SID%

connectDB.pl

use DBI;
require "emd_common.pl";
 
my %stdinVars = get_stdinvars();
my $dbUsername = $stdinVars{"EM_DB_USERNAME"};
my $dbPassword = $stdinVars{"EM_DB_PASSWORD"};
my $dbMachine = $stdinVars{"EM_DB_MACHINE"};
my $dbPort = $stdinVars{"EM_DB_PORT"};
my $dbSID = $stdinVars{"EM_DB_SID"};
 
my $dbAddress = "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=$dbMachine)(Port=$dbPort))(CONNECT_DATA=(SID=$dbSID)))";
 
# Establish Target DB Connection
my $db = DBI->connect('dbi:Oracle:', "$dbUsername@".$dbAddress, "$dbPassword", 
    {PrintError => 0, RaiseError => 0, AutoCommit => 0})
    or die (filterOraError("em_error=Could not connect to $dbUsername/$dbAddress: $DBI::errstr\n", $DBI::err));
 
my $query = "SELECT JOB_TITLE, MIN_SALARY FROM HR.JOBS";
my $st = $db->prepare($query);
$st->execute();
 
while ( my ($job_title, $min_sal) = $st->fetchrow_array() ) 
{
    print "$job_title|$min_sal\n";
}
 
$db->disconnect
    or warn "disconnect $DBI::errstr\n";
 
exit 0;

Approach 2 - Pass monitoring credential set using Input Credentials

Command = %perlBin%/perl

Script = %scriptsDir%/connectDB.pl

Input Credentials:

dbCreds = MyCustomDBCreds

connectDB.pl

use DBI;

require "emd_common.pl";

 
my %stdinVars = get_stdinvars();
my $credType = getCredType("dbCred", \%stdinVars);
my %credProps = getCredProps("dbCreds", \%stdinVars);
my $dbUsername = $credProps{"DBUserName"};
my $dbPassword = $credProps{"DBPassword"};

Example 3

Overriding default monitoring credentials by creating and using a custom monitoring credential set for host target.

Creating host credentials for the host target type:

> emcli create_credential_set -set_name=myCustomCreds -target_type=host -auth_target_type=host -supported_cred_types=HostCreds -monitoring -description='My Custom Credentials'

When you go to the Credentials page of the Metric Extension wizard, and choose to "Specify Credential Set" for Host Credentials, you will see "My Custom Credentials" show up as an option in the drop down list.

Note that this step only creates the Monitoring Credential Set for the host target type, and you need to set the credentials on each target you plan on deploying this metric extension to. You can set credentials from Enterprise Manager by going to Setup, then Security, then Monitoring Credentials. Alternatively, this can be done from the command line.

> emcli set_monitoring_credential -target_name=target1 -target_type=host -set_name=myCustomCreds -cred_type=HostCreds -auth_target_type=host -attributes='HostUserName:myusername;HostPassword:mypwd'

OS Command Adapter- Multiple Values

Executes the specified OS command and returns each command output line as a separate value. The metric result is a multi-row, 1 column table.

For example, if the command output is:

em_result=out_x
em_result=out_y

then three columns are populated with values 1,2,3 respectively.

Basic Properties

Command - The command to execute. For example, %perlBin%/perl.
Script - A script to pass to the command. For example, %scriptsDir%/myscript.pl. You can upload custom files to the agent, which will be accessible under the %scriptsDir% directory.
Arguments - Additional arguments to be appended to the Command.
Starts With - The starting string of metric result lines.

Example: If the command output is:
```
em_result=4354
update
test
```
setting Starts With = em_result specifies that only lines starting with em_result will be parsed.

Advanced Properties

Input Properties - Additional properties to be passed to the command through its standard input stream. For example, you can add Input Property: Name=targetName, Value=%NAME%, which the command can read through its standard input stream as "STDINtargetName=<target name>". See usage examples in OS Command Adapter - Single Columns.
Environment Variables - Additional properties can be accessible to the command from environment variables. For example, you can add Environment Variable: Name=targetType, Value="%TYPE%", and the command can access the target type from environment variable "ENVtargetType". See usage examples in OS Command Adapter - Single Columns.

Note:
Value="%TYPE%" may not be applicable for certain target-types (for example: host, wls). For such target types, use Value=TYPE instead.

Credentials

Host Credentials - The credential used to launch the OS Command. See usage examples in OS Command Adapter - Single Columns.
Input Credentials - Additional credentials passed to the OS Command's standard input stream. See usage examples in OS Command Adapter - Single Columns.

OS Command Adapter - Multiple Columns

Executes the specified OS command and parses each command output line (delimited by a user-specified string) into multiple values. The metric result is a mult-row, multi-column table.

Example: If the command output is

em_result=1|2|3
em_result=4|5|6

and the Delimiter is set as "|", then there are two rows of three columns each:

Basic Properties

The complete command line will be constructed as: Command + Script + Arguments

Command - The command to execute. For example, %perlBin%/perl.
Script - A script to pass to the command. For example, %scriptsDir%/myscript.pl. You can upload custom files to the agent, which will be accessible under the %scriptsDir% directory.
Arguments - Additional arguments.
Delimiter - The string used to delimit the command output.
Starts With - The starting string of metric result lines.

Example: If the command output is
```
  em_result=4354  out_x  out_y
```
setting Starts With = em_result specifies that only lines starting with em_result will be parsed.
Input Properties - Additional properties can be passed to the command through its standard input stream. For example, you can add Input Property: Name=targetName, Value=%NAME%, which the command can read through it's standard input stream as STDINtargetName=<target name>. To specify multiple Input Properties, enter each property on its own line.
Environment Variables - Additional properties can be accessible to the command from environment variables. For example, you can add Environment Variable: Name=targetType, Value="%TYPE%", and the command can access the target type from environment variable "ENVtargetType".

Advanced Properties

Input Properties - Additional properties can be passed to the command through its standard input stream. For example, you can add Input Property: Name=targetName, Value=%NAME%, which the command can read through its standard input stream as STDINtargetName=<target name>. See usage examples in OS Command Adapter - Single Columns.
Environment Variables - Additional properties can be accessible to the command from environment variables. For example, you can add Environment Variable: Name=targetType, Value="%TYPE%", and the command can access the target type from environment variable "ENVtargetType". See usage examples in OS Command Adapter - Single Columns.

Note:
Value="%TYPE%" may not be applicable for certain target-types (for example: host, wls). For such target types, use Value=TYPE instead.

Credentials

Host Credentials - The credential used to launch the OS Command. See usage examples in OS Command Adapter - Single Columns.
Input Credentials - Additional credentials passed to the OS Command's standard input stream. See usage examples in OS Command Adapter - Single Columns.

SQL Adapter

Executes custom SQL queries or function calls supported against single instance databases and instances on Real Application Clusters (RAC).

Properties

SQL Query - The SQL query to execute. Normal SQL statements should not be semi-colon terminated. For example, SQL Query = "select a.ename, (select count(*) from emp p where p.mgr=a.empno) directs from emp a". PL/SQL statements are also supported, and if used, the "Out Parameter Position" and "Out Parameter Type" properties should be populated.
SQL Query File - A SQL query file. Note that only one of "SQL Query" or "SQL Query File" should be used. For example, %scriptsDir%/myquery.sql. You can upload custom files to the agent, which will be accessible under the %scriptsDir% directory.
Transpose Result - Transpose the SQL query result.
Bind Variables - Declare bind variables used in normal SQL statements here. For example, if the SQL Query = "select a.ename from emp a where a.mgr = :1", then you can declare the bind variable as Name=1, Value=Bob.
Out Parameter Position - The bind variable used for PL/SQL output. Only integers can be specified.

Example: If the SQL Query is
```
     DECLARE         l_output1 NUMBER;         l_output2 NUMBER;     BEGIN         .....         OPEN :1 FOR             SELECT l_output1, l_output2 FROM dual;     END;
```
you can set Out Parameter Position = 1, and Out Parameter Type = SQL_CURSOR
Out Parameter Type - The SQL type of the PL/SQL output parameter. See comment for Out Parameter Position

Credentials

Database Credentials - The credential used to connect to the database.

Example

Overriding default monitoring credentials by creating and using a custom monitoring credential set for database target.

Creating host credentials for the database target type:

> emcli create_credential_set -set_name=myCustomDBCreds -target_type=oracle_database -auth_target_type=oracle_database -supported_cred_types=DBCreds -monitoring -description='My Custom DB Credentials'

When you go to the Credentials page of the Metric Extension wizard, and choose to "Specify Credential Set" for Database Credentials, you will see "My Custom DB Credentials" show up as an option in the drop down list.

Note that this step only creates the Monitoring Credential Set for the host target type, and you need to set the credentials on each target you plan on deploying this metric extension to. You can set credentials from Enterprise Manager by going to Setup, then selecting Security, then selecting Monitoring Credentials. Alternatively, this can be performed using the Enterprise Manager Command Line Interface.

> emcli set_monitoring_credential -target_name=db1 -target_type=oracle_database -set_name=myCustomDBCreds -cred_type=DBCreds -auth_target_type=oracle_database -attributes='DBUserName:myusername;DBPassword:mypwd'

SNMP (Simple Network Management Protocol) Adapter

Allow Enterprise Manager Management Agents to query SNMP agents for Management Information Base (MIB) variable information to be used as metric data.

Basic Properties

Object Identifiers (OIDs): Object Identifiers uniquely identify managed objects in a MIB hierarchy. One or more OIDs can be specified. The SNMP adapter will collect data for the specified OIDs. For example, 1.3.6.1.4.1.111.4.1.7.1.1

Advanced Properties

Delimiter - The delimiter value used when specifying multiple OID values for an OID's attribute. The default value is space or \n or \t
Tabular Data - Indicates whether the expected result for a metric will have multiple rows or not. Possible values are TRUE or FALSE. The default value is FALSE
Contains V2 Types - Indicates whether any of the OIDs specified is of SNMPV2 data type. Possible values are TRUE or FALSE. The default value is FALSE. For example, if an OID value specified is of counter64 type, then this attribute will be set to TRUE.

JMX Adapter

Retrieves JMX attributes from JMX-enabled servers and returns these attributes as a metric table.

Properties

Metric -- The MBean ObjectName or ObjectName pattern whose attributes are to be queried. Since this is specified as metric metadata, it needs to be instance- agnostic. Instance-specific key properties (such as servername) on the MBean ObjectName may need to be replaced with wildcards.
ColumnOrder -- A semi-colon separated list of JMX attributes in the order they need to be presented in the metric.

Advanced Properties

IdentityCol -- The MBean key property that needs to be surfaced as a column when it is not available as a JMX attribute. For example:
```
com.myCompany:Name=myName,Dept=deptName, prop1=prop1Val, prop2=prop2Val
```
In this example, setting identityCol as Name;Dept will result in two additional key columns representing Name and Dept besides the columns representing the JMX attributes specified in the columnOrder property.
AutoRowPrefix -- Prefix used for an automatically generated row. Rows are automatically generated in situations where the MBean ObjectName pattern specified in metric property matches multiple MBeans and none of the JMX attributes specified in the columnOrder are unique for each. The autoRowId value specified here will be used as a prefix for the additional key column created. For example, if the metric is defined as:
```
com.myCompany:Type=CustomerOrder,* columnOrder
```
is
```
CustomerName;OrderNumber;DateShipped
```
and assuming CustomerName;OrderNumber;Amount may not be unique if an order is shipped in two parts, setting autoRowId as "ShipItem-" will populate an additional key column for the metric for each row with ShipItem-0, ShipItem-1, ShipItem-2...ShipItem-n.
Metric Service -- True/False. Indicate whether MetricService is enabled on a target Weblogic domain. This property would be false (unchecked) in most cases for Metric Extensions except when metrics that are exposed via the Oracle DMS MBean needs to be collected. If MetricService is set to true, then the basic property metric becomes the MetricService table name and the basic property columnOrder becomes a semicolon-separated list of column names in the MetricService table.

Note:

Refer to the Monitoring Using Web Services and JMX chapter in the for an in-depth example of creating a JMX-based Metric Extension.

Metric Extension Command Line Verbs

Metric extensions can be manipulated outside the UI via the Enterprise Manager Command Line Interface (EM CLI). Two categories of verbs are available:

Metric Extension Verbs
- export_metric_extension: Export a metric extension to an archive file
- get_unused_metric_extensions: Get a list of unused metric extensions.
- import_metric_extension: Import a metric extension archive file.
- publish_metric_extension: Publish a metric extension for use by all administrators.
- save_metric_extension_draft: Save a deployable draft of a metric extension.
User-defined Metric Migration Verbs
- abort_udmmig_session: Abort (partially) user-defined metric migration session.
- analyze_unconverted_udms: Analyze the unconverted user-defined metrics.
- create_udmmig_session: Create a user-defined metric migration session.
- list_unconverted_udms: List the user-defined metrics that are not yet in a migration session.
- udmmig_list_matches: List the matching metrics per user-defined metric in a specific user-defined metric migration session.
- udmmig_request_udmdelete: Request deletion of user-defined metrics from targets.
- udmmig_retry_deploys: Retry deployment of metric extensions to targets.
- udmmig_session_details: Retrieve the details of a specific user-defined metric migration session.
- udmmig_submit_metricpicks: Select the metrics to replace user-defined metrics in a session.
- udmmig_summary: Summarize the status of all user-defined metric migration sessions.
- udmmig_update_incrules: Update user-defined metric incident rules to include replacement metric references.

Metric Extension Verbs

  emcli export_metric_extension
       -file_name=<name of the metric extension archive>
       -target_type=<target type of the metric extension>
       -name=<name of the metric extension
       -version=<version of the metric extension>

  Description:
    Export a metric extension archive file.

  Options:
    -file_name=<file name>
      The name of the metric extension archive file to export into.
    -target_type=<target type>
      Target type of the metric extension.
    -name=<name>
      Name of the metric extension.
    -version=<version>
      Version of the metric extension to be exported.


  emcli get_unused_metric_extensions

  Description:
    Get a  list of metric extensions that are deployed to agents but not attached to any targets.


  emcli import_metric_extension
        -file_name=<name of the metric extension archive>
        -rename_as=<name of the metric extension to import as>

  Description:
    Import a metric extension archive file.

  Options:
    -file_name=<file name>
      The name of the metric extension archive file to be imported.
    -rename_as=<metric extension name>
      Import the metric extension using the specified name, replacing the name given in the archive.


  emcli publish_metric_extension
       -target_type=<target type of the metric extension>
       -name=<name of the metric extension
       -version=<version of the metric extension>

  Description:
    Publish a metric extension for use by all administrators. 
  The metric extension must currently be a deployable draft.

  Options:
    -target_type=<target type>
      Target type of the metric extension.
    -name=<name>
      Name of the metric extension.
    -version=<version>
      Version of the metric extension to be published.


  emcli save_metric_extension_draft
       -target_type=<target type of the metric extension>
       -name=<name of the metric extension
       -version=<version of the metric extension>

  Description:
    Save a deployable draft of a metric extension. The metric
  extension must currently be in editable state. Once saved as 
  draft, the metric extension will no longer be editable.

  Options:
    -target_type=<target type>
      Target type of the metric extension.
    -name=<name>
      Name of the metric extension.
    -version=<version>
      Version of the metric extension to be saved to draft.

User-Defined Metric Verbs

  emcli abort_udmmig_session
        -session_id=<sessionId>
        [-input_file=specific_tasks:<complete path to file>]

  Description:
    Abort the migration of user-defined metrics to MEs in a session

  Options:
    -session_id=<id of the session>
      Specify the id that was returned at time of session created,
      or from the output of udmmig_summary
    [-input_file=specific_tasks:<complete file path>]
      This optional parameter points at a file name that contains a
         target, user-defined metric,
      one per line in the following format:
      <targetType>,<targetName>,<collection name>
      Use targetType=Template to indicate a template
      Use * for collection name to abort all user-defined metrics for a target


  emcli analyze_unconverted_udms [-session_id=<sessionId>]

  Description:
    Analyze user-defined metrics and list unique user-defined metrics, any possible matches, and
    templates that can apply these matching metric extensions
  Options:
    -session_id=<id of a session to be reanalyzed>
      Not specifying a session id causes the creation of a analysis
      session that contains all unconverted user-defined metrics. You can specify 
      this session id in future invocations to get fresh analysis.


  emcli create_udmmig_session
      -name=<name of the session>
      -desc=<description of the session>
      [-udm_choice=<specific udm to convert>]*
      {-target=<type:name of the target to migrate> }* 
      | {-input_file=targetList:<complete path to file>};      {-template=<name of the template to update> }* 
      | {-input_file=templateList:<complete path to file>}
      [-allUdms]

  Description:
    Creates a session to migrate user-defined metrics to metric extensions for targets.

  Options:
    -name=<session name>
      The name of the migration session to be created.
    -desc=<session session description>
      A description of the migration session to be created.
    -udm_choice=<udm name>
      If the session should migrate specific user-defined metrics, specify them
      Otherwise, all user-defined metrics will be migrated
    -target=<type:name of target to migrate>
      The type:name of the target to be updated.
      Multiple values may be specified.
    -input_file=targetList:<complete file path>
      This takes a file name that contains a list of targets,
      one per line in the following format:
      <targetType>:<targetName>
    -template=<name of template to migrate>
      The name of the template to update.Multiple values may be specified
    -input_file=templateList:<complete file path>
      This takes a file name that contains a list of templates,
      one name per line
    -allUdms
      This forces the session to contain all user-defined metrics from targets and 
      templates (default behavior just picks those not in a session)

  emcli list_unconverted_udms [-templates_only]

  Description:
    Get the list of all user-defined metrics that are not yet in a migration session

  Options:
    -templates_only
      Only lists unconverted user-defined metrics in templates.


  emcli udmmig_list_matches
        -session_id=<sessionId>

  Description:
    Lists the matching metrics per user-defined metric in a migration session
  Options:
    -session_id=<id of the session>
      Specify the id that was returned at time of session created,
      or from the output of udmmig_summary


  emcli udmmig_request_udmdelete
        -session_id=<sessionId>
        -input_file=metric_tasks:<complete path to file>

  Description:
    Delete the user-defined metrics that have been replaced by Metric Extenions

  Options:
    -session_id=<id of the session>
      Specify the id that was returned at time of session created,
      or from the output of udmmig_summary
    -input_file=metric_tasks:<complete file path>
      This takes a file name that contains a target, user-defined metric,
      one per line in the following format:
      <targetType>,<targetName>,<collection name>


  emcli udmmig_retry_deploys
        -session_id=<sessionId>
        -input_file=metric_tasks:<complete path to file>

  Description:
    Retry the deployment of metric extensions to a target

  Options:
    -session_id=<id of the session>
      Specify the id that was returned at time of session created,
      or from the output of udmmig_summary
    -input_file=metric_tasks:<complete file path>
      This takes a file name that contains a target, user-defined metric,
      one per line in the following format:
      <targetType>,<targetName>,<collection name>


  emcli udmmig_submit_metricpicks
        -session_id=<sessionId>
        -input_file=metric_picks:<complete path to file>

  Description:
    Supply the metric picks to use to replace user-defined metrics per target in a session

  Options:
    -session_id=<id of the session>
      Specify the id that was returned at time of session created,
      or from the output of udmmig_summary
    -input_file=metric_picks:<complete file path>
      This takes a file name that contains a target, user-defined metric, metric pick,
      one per line in the following format:
      <targetType>,<targetName>,<collection name>,[N/E],<metric>,<column>
       using N if a new metric should be created or E if an existing 
       metric is referenced.


  emcli udmmig_summary
      [-showAll]

  Description:
    Gets the summary details of all migration sessions in progress

  Options:
    -showAll
      This prints out all sessions including those that are complete.
      By default, only in-progress sessions are listed.


  emcli udmmig_update_incrules
        -session_id=<sessionId>
        -input_file=udm_inc_rules:<complete path to file>

  Description:
    Update Incident Rules that reference user-defined metrics with a reference to
    replacing metric extension.

  Options:
    -session_id=<id of the session>
      Specify the id that was returned at time of session created,
      or from the output of udmmig_summary
    -input_file=udm_inc_rules:<complete file path>
      This takes a file name that contains rule, user-defined metric, metric,
      one per line in the following format:
      <ruleset id>,<rule id>,<udm name>,<metric name>