Skip Headers
Oracle® Enterprise Manager Cloud Control Administrator's Guide
12c Release 3 (12.1.0.3)

E24473-27
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

9 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:

9.1 What are Metric Extensions?

Metric extensions also allow you to create metrics on any target type and customize metric thresholds and collections. 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. In the case of user-defined metrics, multiple pieces of data can be collected by creating multiple user-defined metrics, however, it is not possible to refer to the related data when alerts are generated because they are collected separately.

  • 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, making it impossible to associate suspending of monitoring (blackouts) on these targets when servers are undergoing maintenance periods.

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.

9.2 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.

Graphic shows the test page with a single selected target

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 you can edit can be opened 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.

Graphic shows the Save as Deployable Draft menu option

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.

Graphic shows the Publish menu option selected.

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.

9.3 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.

9.3.1 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.

9.3.2 Granting Create Metric Extension Privilege

To grant create metric extension privileges to another administrator:

  1. From the Setup menu, select Security, then select Administrators.

  2. Choose the Administrator you would like to grant the privilege to.

  3. Click Edit.

  4. Go to the Resource Privileges tab, and click Manage Privilege Grants for the Metric Extension resource type.

  5. Under Resource Type Privileges, click the Create Metric Extension check box.

  6. Click Continue, review changes, and click Finish in the Review tab.

9.3.3 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:

  1. From the Setup menu, select Security, then select Administrators.

  2. Choose the Administrator you would like to grant access to.

  3. Click Edit.

  4. Go to Resource Privileges and click Manage Privilege Grants (pencil icon) for the Metric Extensions resource type.

  5. 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.

  6. 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.

  7. Click Continue, review changes, and click Finish in the review tab.

9.3.4 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.

9.3.4.1 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:

  1. From the Enterprise menu, select Monitoring, then select Metric Extensions.

  2. Choose a metric extension requiring update.

  3. From the Actions menu, select Manage Access.

  4. Click Add. The administrator selection dialog box appears. You can filter the list by administrator, role, or both.

  5. Choose one or more administrators/roles from the list.

  6. 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.

  7. Click OK.

9.3.4.2 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:

  1. From the Enterprise menu, select Monitoring, then select Metric Extensions.

  2. Choose a metric extension requiring update.

  3. From the Actions menu, select Manage Access.

  4. Choose one or more administrators/roles from the list.

  5. Click Remove. The chosen administrators/roles is deleted from the access list.

  6. 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.

9.3.4.3 Transferring Metric Extension Ownership

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.

9.3.5 Creating a New Metric Extension

To create a new metric extension:

  1. From the Enterprise menu, select Monitoring, then select Metric Extensions.

  2. Click Create New. Enterprise Manager will determine whether you have the Create Extension privilege and guide you through the creation process.

  3. Decide on a metric extension name. Be aware that the name (and Display Name) must be unique across a target type.

  4. 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.

      collection schedule
  5. 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.

    rate and delta column
    • 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.

  6. 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.

  7. From the Test page, add available test targets.

  8. 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.

  9. Repeat the edit /test cycle until the metric extension returns data as expected.

  10. Click Finish.

9.3.6 Creating a New Metric Extension (Create Like)

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

  1. From the Enterprise menu, select Monitoring, then select Metric Extensions.

  2. 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.

  3. Select an existing metric extension.

  4. 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.

  5. Make desired modifications.

  6. From the Test page, add available test targets.

  7. 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.

  8. Repeat the edit /test cycle until the metric extension returns data as expected.

  9. Click Finish.

9.3.7 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:

  1. From the Enterprise menu, select Monitoring, then select Metric Extensions.

  2. 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.

  3. Select the metric extension to be edited.

  4. From the Actions menu, select Edit.

  5. Update the metric extension as needed.

  6. From the Test page, add available test targets.

  7. 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.

  8. Repeat the edit /test cycle until the metric extension returns data as expected.

  9. Click Finish.

9.3.8 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:

  1. From the Enterprise menu, select Monitoring, then select Metric Extensions.

  2. 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.

  3. Select the metric extension to be versioned.

  4. From the Actions menu, select Create Next Version.

  5. 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.

  6. From the Test page, add available test targets.

  7. 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.

  8. Repeat the edit /test cycle until the metric extension returns data as expected.

  9. Click Finish.

9.3.9 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:

  1. From the Enterprise menu, select Monitoring, then select Metric Extensions.

  2. Click Import.

  3. 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.

  4. Clicking on OK creates the new metric extension or the new version of an existing metric extension.

  5. From the Actions menu, select Edit to verify the entries.

  6. From the Test page, add available test targets.

  7. 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.

  8. Repeat the edit /test cycle until the metric extension returns data as expected.

  9. Click Finish.

9.3.10 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:

  1. From the Enterprise menu, select Monitoring, then select Metric Extensions.

  2. 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.

  3. Select the metric extension to be exported.

  4. 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.

  5. 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.

  6. Confirm the export file is downloaded.

9.3.11 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:

  1. From the Enterprise menu, select Monitoring, then select Metric Extensions.

  2. 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.

  3. Select the metric extension that is to be deleted.

  4. From the Actions menu, select Delete. Enterprise Manager prompts you to confirm the deletion.

  5. Confirm the deletion.

9.3.12 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:

  1. From the Enterprise menu, select Monitoring, then select Metric Extensions.

  2. 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.

  3. Select the metric extension that is to be deployed.

  4. 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.

  5. Return to the Metric Extensions page.

  6. Select the metric extension.

  7. 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.

  8. 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.

  9. 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.

9.3.13 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:

  1. From the Enterprise menu, select Monitoring, then select Metric Extensions.

  2. 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.

  3. Select the metric extension to be upgraded.

  4. 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.

  5. 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.

  6. 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.

9.4 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. A complete list of all adapters is shown below.

9.4.1 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".

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:mypassword'

9.4.2 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.

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.

9.4.3 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:

Table 9-1 Multi-Column Output

1

2

3

4

5

6


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.

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.

9.4.4 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:mypassword'

9.4.5 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.

9.4.6 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 Oracle® Enterprise Manager Extensibility Programmer's Reference for an in-depth example of creating a JMX based Metric Extension.

9.5 Converting User-defined Metrics to Metric Extensions

For targets monitored by Enterprise Manager 12c Agents, both older user-defined metrics and metric extensions will be supported. After release 12c, only metric extensions will be supported. If you have existing user-defined metrics, it is recommended that you migrate them to metric extensions as soon as possible to prevent potential monitoring disruptions in your managed environment.

Migration of user-defined metric definitions to metric extensions is not automatic and must be initiated by an administrator. The migration process involves migrating user-defined metric metadata to metric extension metadata.

Note:

Migration of collected user-defined metric historic data is not supported.

After the user-defined metric is migrated to the metric extension and the metric extension has been deployed successfully on the target, the user-defined metric should be either disabled or deleted. Disabling the collection of the user-defined metric will retain the metadata definition of the user-defined metric) but will clear all the open alerts, remove the metric errors and prevent further collections of the user-defined metric. Deleting the user-defined metric will delete the metadata, historic data, clear open alerts and remove metric errors.

9.5.1 Overview

The User Defined Metric (UDM) to Metric Extension (ME) migration replaces an existing UDM with a new or existing ME. The idea behind the migration process is to consolidate UDMs with the same definition that have been created on different targets into a single ME. In addition, MEs support multiple metric columns, allowing the user to combine multiple related UDMs into a single ME.

This migration process is comprised of the following steps:

  1. Identify the UDMs that need to be migrated.

  2. Use the provided EM CLI commands to create or select a compatible metric extension.

  3. Test and publish the metric extension.

  4. Deploy the metric extension to all targets and templates where the original UDMs are located. Also update the existing notification rules to refer to the ME.

  5. Delete the original UDMs. Note that the historical data and alerts from the old UDM is still accessible from the UI, but the new ME will not inherit them.

Note that the credentials being used by the UDM are NOT migrated to the newly created ME. The user interface allows a user to specify the credential set required by the metric extension. If the ME does not use the default monitoring credentials, the user will need to create a new credential set to accommodate the necessary credentials through the relevant EM CLI commands. This set will then be available in the credentials page of the metric extension wizard.

The migration process is categorized by migration sessions. Each session is responsible for migrating one or more UDMs. The process of migrating an individual session is referred to as a task. Therefore, a session is comprised of one or more tasks. In general terms, the migration involves creating a session and providing the necessary input to complete each tasks within that session. The status of the session and tasks is viewable throughout the workflow.

9.5.2 Commands

A number of EM CLI commands are responsible for completing the various steps of this process. For a more detailed explanation of the command definition, please use the 'EM CLI help <command>' option.

  • list_unconverted_udms - Lists the UDMs that have yet to be migrated and not in a session

  • create_udmmig_session - Creates a session to migrate one or more UDMs

  • udmmig_summary - Lists the migration sessions in progress

  • udmmig_session_details - Provides the details of a specific session

  • udmmig_submit_metricpics - Provides a mapping between the UDM and the ME in order to create a new ME or use an existing one

  • udmmig_retry_deploys - Deploys the ME to the targets where the UDM is present. Note that the ME has to be in a deployable draft or published state for this command to succeed

  • udmmig_request_udmdelete - Deletes the UDM and completing the migration process

Usage Examples

The following exercise outlines a simple use case to showcase the migration

Consider a system with one host (host1) that has one host UDM (hostudm1) on it. The goal is to create a new ME (me1) that represents the UDM. The sequence of commands would be as follows

$ emcli list_unconverted_udms

-------------+----------------------+-----------+--------------------
Type         | Name                       | Metric    | UDM                
-------------+----------------------+-----------+--------------------
host         | host1                             |UDM        | hostudm1           

The command indicates that there is only one UDM that has not been migrated or in the process of migration at this stage. Now proceed with the creation of a session.

$ emcli create_udmmig_session -name=migration1 -desc="Convert UDMs for host target" -udm_choice=hostudm1 -target=host:host1
 
Migration session created - session id is 1

The command creates a migration session with name migration1 and the description "convert UDMs for host target". The udm_choice flag indicates the UDM chosen and the target flag describes the target type and the target on which the UDM resides. Migration sessions are identified by session IDs. The current session has an ID of 1.

$ emcli udmmig_summary

------+--------------+------------------+------+------+--------+------+--------
ID    | Name         | Description      |#Tgts |Todo  |#Tmpls  |Todo  |IncRules
------+--------------+------------------+------+------+--------+------+--------
1     |migration1    |Convert UDMS      |      | 1/1  |  0     | -/0  | -/0    
------+--------------+------------------+------+------+--------+------+--------

The command summarizes all the migrations sessions currently in progress. The name and description fields identify the session. The remaining columns outline the number of targets, templates and incident rules that contain references to the UDM that is being converted to a metric extension. The 'Todo' columns indicate the number of targets, templates and incident rules whose references to the UDM are yet to be updated. Since a migration session can be completed over a protracted period of time, the command provides an overview of the portion of the session that was been completed.

$ emcli list_unconverted_udms

There are no unconverted udms

Since the UDM is part of a migration session, it no longer shows up in the list of unconverted UDMs.

$ emcli udmmig_session_details -session_id=1
 
Name: migration1
Desc: Convert UDMs for host target
Created: <date> <time>
UDM Pick: [hostudm1]
UDMs being converted:
----------+----------+---------+------+------------+---------+---------+-----
Type      |Name      |UDM      |#MC   |Metric      |Column   |DepS     |DelS
----------+----------+---------+------+------------+---------+---------+-----
host      |host1     |hostudm1 |  0   |            |         |WAIT     |WAIT
----------+----------+---------+------+------------+---------+---------+-----

The command provides the status of a single migration session. It lists the name of the UDM and the target type and name of the target on which the UDM resides. In addition, it also outlines the metric extensions currently in the EM instance that match the UDM. The user can elect to use one of the existing choices or create an entirely new metric extension.

The system attempts to find compatible metric extensions by matching the properties of the UDM. For example, in the case of a host UDM, the system tries to find a metric extension that has the same command, script and argument fields. In the case of a database UDM, the system attempts to match the SQL query.

Finally, the DepS column indicates whether the metric extension that was matched to the UDM has been deployed to the target on which the UDM is defined. The DelS column tells the user whether the UDM has been deleted after the metric extension has been deployed. As the user proceeds with the migration, the above table is updated from left to right. When the delete status column is set to complete, the migration session has ended.

$ emcli udmmig_submit_metricpicks -session_id=1 -input_file=metric_picks:filename
 
Successfully submitted metric picks for migration session

The command instructs the Enterprise Manager instance to use an existing metric extension or create a new one to replace the UDM. The various options are presented through a file, which is filename in the above command. The contents of the file are shown below

"host,host1,hostudm1,N,ME$me1,Usage"

Each line in the file represents a mapping from n UDM to an ME. The line provides the target type, the name of the target, the name of the UDM, a flag to indicate whether the metric extension is new (N) or existing (E), the name of the metric extension (note that ME$ must be prefixed) and the column name.

The types of UDMs supported are:

  • Host (host)

  • Database (oracle_database)

  • RAC (rac_database)

A user can only specify the names of the data columns via the collection item portion of the file. A metric extension created through migration will always have two columns to represent the structure of the UDM. The first column is an index column for single column UDMs while the second column uses the column name mentioned in the file. In the case of two column UDMs, the first column of the ME is termed as the 'KEY' column and the collection name is used for the second column.

At this stage, the metric extension has been created and is visible in the metric extensions library.

$ emcli udmmig_session_details -session_id=1
 
Name: migration1
Desc: Convert UDMs for host target
Created: <date> <time>
UDM Pick: [hostudm1]
Udms being converted:
----------+--------+---------+------+----------+------------+---------+-----
Type      |Name    |UDM      |#MC   |Metric    |Column      |DepS     |DelS
----------+--------+---------+------+----------+------------+---------+-----
host      |host1   |hostudm1 |   1  | ME$me1   | Usage      |WAIT     |WAIT
----------+--------+---------+------+----------+------------+---------+-----

        #MC : There are 1 matches for udms in this session.
        Use emcli udmmig_list_matches to list available matches

The session details command indicates that there is one matching metric extension for this UDM (the value of the MC column is 1) and that metric extension is named as ME$me1. At this stage, we are ready to test the metric extension through the library page. Once the testing is complete and the user is satisfied with the metric extension that has been created, it is ready to be deployed. In order to deploy, the metric extension has to be minimally saved as a deployable draft.

$ emcli udmmig_retry_deploys -session_id=1 -input_file=metric_tasks:filename2
 
Metric Deployments successfully submitted

Note that the system will trigger a job to automatically deploy the metric extension to all targets where the UDM was present once the metric extension is published. If the user is interested in manually controlling the operation, the above command will perform the necessary steps. The command is similar to the submit_metricpicks option in that a file with the UDM to target mapping is provided. It is referred to by filename2 above. The contents of the file are as follows

"host,host1,hostudm1"

Each line in the file is a mapping from the UDM to the targets type and target on which it resides. Once the command is executed, jobs to deploy the metric extensions to various targets have been launched and can be tracked through the user interface.

$ emcli udmmig_request_udmdelete -session_id=1 -input_file=metric_tasks:demo_tasks
 
Udm deletes successfully submitted

The final command deletes the UDMs that were migrated to metric extensions. Note that this command might partially finish based on how many of the deployments were completed when the command was run.

$ emcli udmmig_session_details -session_id=1
 
Name: migration1
Desc: Convert UDMs for host target
Created: <date > <time>
Completed: <date > <time>
UDM Pick: [hostudm1]
Udms being converted:
--------+----------+---------+------+------------+------------+---------+-----
Type    |Name      |UDM      |#MC   |Metric      |Column      |DepS     |DelS
--------+----------+---------+------+------  ----+------------+---------+-----
host    |host1     |hostudm1 |  1   | ME$me1     | Usage      |COMP   |COMP
--------+----------+---------+------+------------+------------+---------+-----
 
        #MC : There are 1 matches for udms in this session.
          Use emcli udmmig_list_matches to list available matches

The session details command shows that the migration process is indeed complete.

9.6 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>