1. Using Oracle Infrastructure Monitoring
  2. Expand Monitoring Capability with Custom Metrics
  3. Working with Custom Metrics

Working with Custom Metrics

Most all custom metric operations can be carried out from the Custom Metrics UI.

Important: You must have Oracle Management Cloud Administrator privileges in order to create, edit, view, test, delete, publish, deploy or undeploy custom metrics.

Create a New Custom Metric

  1. From the Oracle Management Cloud console navigation menu, select Monitoring, then Monitoring Admin, and finally Custom Metrics. The Custom Metrics page displays.
  2. Click Create. The Create Custom Metric page displays.
  3. Decide on a custom metric name. Be aware that both the Metric Name and Display Name must be unique across an entity type.
  4. Enter the remaining general properties.
    The selected adapter type defines the properties you must specify in Adapter Properties page. The following adapter types are available:
    • OS Command Adapter: 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).

      Note:

      This applies to Oracle Databases only.

      To create custom metrics based on SQL queries for MySQL and Microsoft SQL Server databases, see Creating Custom Metrics for MySQL and SQL Server Databases.

    • JMX (Java Management Extensions) Adapter: Retrieves JMX attributes from JMX-enabled servers and returns these attributes as a metric table.
  5. Set the Collection Schedule. You defined the frequency with which metric data is collected by specifying collection schedule properties.
  6. On the Metric Columns page, you add metric columns defining the data returned from the adapter. From the Add menu, select New metric column. The Add Metric Column dialog displays.

    Enter the required metric column properties and click Submit when you are done.

    Note:

    The column order should match the order with which the adapter returns the data.

    Compute Expressions (Advanced)

    You use compute expressions to calculate the value of a metric column based on mathematical or logical operations performed on other metric columns. Compute expressions require at least one other metric column to be defined first, and can only include those metric columns that are listed before this metric column in order. You can use the up and down arrows to re-order metric columns.

    The following table shows operators which can be used while defining compute expression.

    Operator Example Explanation
    + Column1 + Column2 Returns the sum of the values of Column1 and Column2.
    - (Column1 + Column2) - Column3 First add Column1 and Column2 values, then subtract Column3 value and return the result.
    * (Column1*Column2) + Column3 First multiply Column1 and Column2 values, then add Column3 value and return the result.
    / (Column1 + Column2) / 2 Returns the average of Column1 and Column2 values.
    __ceil __ceil Column1 Returns the value of Column1 rounded off to the largest integer.
    __floor __floor Column1 Returns the value of Column1 rounded off to the lowest integer.
    __round __round Column1 This expression will round the value of Column1 to the nearest integer, away from zero.
    == Column1 == 1 Returns true if the value of Column1 is 1, else returns false.
    != Column1 != 1 Returns false if the value of Column1 is 1, else returns true.
    () ? : ; (Status == 1) ? "UP": "DOWN" This operator is equivalent to if then else statement. This expression will return "UP" if Status value is 1 otherwise it will return "DOWN"
    __is_null __is_null Column1 Returns true if the value of Column1 is NULL, else returns false.
    __delta __delta Column1 Returns the difference between the current value and the previous value of Column1.
    __contains Column1 __contains "ORA-" Returns true if the value of Column1 contains the string "ORA-", else returns false.
    __beginswith Column1 __beginswith "ORA-" Returns true if the value of Column1 starts with the string "ORA-", else returns false.
    __matches Column1 __matches "UP" Returns true if the value of Column1 is equal to "UP", else returns false.
    __length __length Column1 Returns the length of string value of Column1.
    __to_upper __to_upper Column1 Returns the upper case of string value of Column1
    __to_lower __to_lower Column1 Returns the lower case of string value of Column1.
    __interval Column1 / __interval Returns the Column1 value divided by the collection interval.

    The value of the column is calculated using the given compute expression.

    Usage:

    This attribute specifies the formula for calculating the value of the column. Columns previously defined can participate in the calculation.

    Refer to the examples for details about the expression grammar and usage.

    Predefined special values:

    • __interval: collect interval.
    • __sysdate: current system time.
    • __GMTdate: current GMT time.
    • __contains: tests a given string expression for presence of a string expression.
    • __beginswith: tests whether a given string expression begins with a specified string expression.
    • __endswith: tests whether a given string expression ends with the specified string expression.
    • __matches: tests whether a given string expression matches a specified string expression.
    • __delta: computes the difference between the current value and the previous value.
    • __leadingchars: returns the leading characters in the specified string.
    • __trailingchars: returns the trailing characters in the specified string.
    • __substringpos: returns the position of the occurrence of the pattern within a specified string.
    • __is_null: tests whether the expression is NULL
    • __length: returns the length of the string expression.
    • __to_upper: converts the string to upper case.
    • __to_lower: converts the string to lowercase.
    • __ceil: returns the smallest integral value not less than identifier.
    • __floor: returns the largest integral value not greater than the identifier.
    • __round: rounds to nearest integer, away from zero.

    Examples:

    • NAME="Average" COMPUTE_EXPR="(Column1 + Column2 )/ 2"

      The value of the column is the average of the columns Column1 and Column2.

    • NAME="Version" COMPUTE_EXPR="(Column1 __contains 'NetApp Release 7.') ? '7.X':'6.X'"

      The value of the column Version is computed as 7.X if column Column1 contains the String NetApp Release 7..

    • NAME="Column1" COMPUTE_EXPR="(Column2 - Column3)"

      The value of the column Column1 is the difference of the columns Column2 and Column3.

    • NAME="Status" COMPUTE_EXPR="State __matches 'STARTED'"

      The value of the column Status is 1 if the value of column State matches the String STARTED and 0 otherwise.

    • NAME="Column1" COMPUTE_EXPR="(__is_null Column2)?'yes':'no'"

      The value of the column Column1 is yes if the value of column Column2 is null and no otherwise.

    • NAME="Source" COMPUTE_EXPR="((__length result) == 0) ? 'lanplus' : result"

      The value of the column Source is lanplus if the length of string value of column result is 0; el e it is the value of the column result.

    • NAME="Rate" COMPUTE_EXPR="(__ceil (Column1/__interval))"

      The value of the column Rate is the value of column Column1 divided by the collection interval, rounded up to the largest integer.

    • NAME="Column1" COMPUTE_EXPR="((Column2 == 0) ? 0 : ((Column3 / (Column2 / 8)) * 100.0))"

      The value of the column is the Column1 when Column2 and Column3 are existing metric columns.

    • NAME="PERCENTAGE_VALUE" COMPUTE_EXPR="(Column1 != 0) ? 100.0*(Column2/Column1) : 0"

      The value of the column is the total percentage of disk available where Column1 and Column2 are existing metric columns

    Rate and Delta Metric Columns

    You can create additional metric columns based on an existing data column that measure the rate at which data changes or the difference in value (delta) since the last metric collection. After at least one metric column has been created and the metric column row is selected in the table, two additional options appear in the Add menu:
    • Delta metric column on <selected metric column>
    • Rate (per min) metric column on <selected metric column>

    To create a rate/delta metric column, click on an existing data column in the metric columns table and then select one of the rate/delta column menu options from the Add menu.

    Usage Examples

    • 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

  7. Once you're done, click Review to see your custom metric definition. If you need to change any properties or metric columns, go back to any of the previous pages and make the modifications.
  8. Click Submit to create the custom metric. The new custom metric appears in the list on the Custom Metrics page.

Edit, Test, Delete or Publish of Your Custom Metric

After you click Submit, your custom metric is saved in draft status. When you select a draft status metric on the Custom Metrics page, you can edit, test, delete, or publish the custom metric. Also, the custom metric is only viewable by you, the custom metric owner.

When you're ready to push your custom metric to a production environment, it must first be published. You will no longer be able to edit or test the metric. You can only deploy the metric to production target entities at this point.

Edit a Custom Metric

  1. Choose a custom metric in draft status from the list on the Custom Metrics page.
  2. Click Edit. The custom metric property pages display.
  3. Modify the custom metric properties.
  4. Click Submit to save the changes.

Test Deploy a Custom Metric to One or More Entities

  1. Choose a custom metric in draft status from the list on the Custom Metrics page.
  2. Click Test. The Test Custom Metric page displays.
  3. Click Add Entity. The Select Entities dialog displays.
  4. Add one or more entities then click Select.
  5. Click Test to begin the test deployment process. While the test deployment job is running, test status will be updated in the Test Results region.

    IMPORTANT: DO NOT use your browser's refresh/reload function or navigate away from this page. Doing so will erase the test result data. You can set the auto-refresh rate by using the refresh drop-down menu.

Delete a Custom Metric

  1. Choose a custom metric in draft status from the list on the Custom Metrics page.
  2. Click Delete. The Confirmation dialog displays.
  3. Click Yes.

Publish a Custom Metric

  1. Choose a custom metric in draft status from the list on the Custom Metrics page.
  2. Click Publish.

Deploy or Undeploy a Custom Metric

Once your custom metric has been published, you can deploy the metric to production target entities. If the custom metric has already been deployed, you have ability to undeploy the metrics from production target entities.

Deploy a Custom Metric to One or More Entities

  1. Choose a custom metric in published status from the list on the Custom Metrics page.
  2. Click Deploy. The Deploy Custom Metric page displays.
  3. Click Add Entity. The Select Entities dialog displays.
  4. Add one or more entities then click Select.
  5. Click Deploy to begin the deployment process. While the deployment job is running, deployment status will be updated in the Deployment Sesults region.

    IMPORTANT: DO NOT use your browser's refresh/reload function or navigate away from this page. Doing so will erase the deployment status data. You can set the auto-refresh rate by using the refresh drop-down menu.

Undeploy a Custom Metric from One or More Entities

  1. Choose a custom metric in published status from the list on the Custom Metrics page.
  2. Click Undeploy. The Undeploy Custom Metric page displays.
  3. Select one or more deployed entities.
  4. Click Undeploy to begin the undeployment process. While the undeployment job is running, its status will be updated in the Undeployment Status region.

    IMPORTANT: DO NOT use your browser's refresh/reload function or navigate away from this page. Doing so will erase the undeployment status data. You can set the auto-refresh rate by using the refresh drop-down menu.

    Delete a Published Custom Metric from the UI

    After you have published a custom metric, if you later wanted to remove the custom metric, it was not possible to delete the custom metric from the UI. This release addresses this by allowing you to delete published custom metrics from the UI. You will be able to delete the published custom metric only if:

    • You have been granted the OMC Administrator role.
    • The custom metric has been undeployed from all entities.