Oracle Cloud Infrastructure Documentation

Metric Extensions

Introduction

Metric Extensions allow you to create full-fledged metrics on any resource type that is monitored by Stack Monitoring. Metric Extensions allow you to create custom metrics to monitor conditions specific to your IT environment. This provides you with a comprehensive view of your environment.

Creating Metric Extensions lets you simplify your IT organization's operational processes by leveraging Stack Monitoring as the single central monitoring tool for your entire environment instead of relying on other monitoring tools to provide this supplementary monitoring.

Metric Extension Lifecycle

Developing a Metric Extension follows the same phases you would expect from any programmatic customization.

Creating a Metric Extension involves the following phases:

  • Developing Metric Extensions:

    • Create
    • Test
    • Edit

    In this phase, after you create your Metric Extension, the Metric Extension is in draft status, which allows you to test it against resources and edit it accordingly.

  • Publishing Metric Extensions:

    Publishing a Metric Extension makes it available for general use, while edits are no longer possible.

  • Enabling Metric Extensions on Resources:

    With your Metric Extension published, it can be deployed and enabled on your resources.

Working with Metric Extensions

Prerequisites

The following policy is required to use Metric Extensions:

Policy Description
ALLOW DYNAMIC-GROUP StackMonitoringManagementAgentsEasyOnboarding TO USE METRICS IN COMPARTMENT <compartment_name> where any {target.metrics.namespace='oracle_metric_extensions_appmgmt', target.metrics.namespace='oracle_metric_extensions_appmgmt_test'} Allow the Management Agent to upload metrics to OCI Monitoring. Here, StackMonitoringManagementAgentsEasyOnboarding is a dynamic group of management agents in a compartment.

Users which are part of StackMonitoringAdminGrp created as part of Stack Monitoring's Easy Onboarding, have all the required permissions to do all operations related to Metric Extensions like create, update, test, delete, publish, enable, disable. If you want to create a new group of users who can only enable/disable already created and published Metric Extensions from the admin group, then such user can be made part of a new group, for example, MeOperatorGroup and can be setup by applying all below policies.

Policy Description
ALLOW GROUP OperatorGroup TO USE stack-monitoring-metric-extension IN COMPARTMENT <compartment_name> Allows the group OperatorGroup to be able to enable/disable a metric extension on specific resource instance.
ALLOW GROUP OperatorGroup TO {STACK_MONITORING_RESOURCE_UPDATE, DBMGMT_MANAGED_DB_UPDATE, DBMGMT_MANAGED_DB_CONTENT_WRITE, DBMGMT_EXTERNAL_DBSYSTEM_UPDATE, DBMGMT_EXTERNAL_DBSYSTEM_CONTENT_WRITE} IN COMPARTMENT <compartment_name> Allows the group OperatorGroup to have update permission on monitored resource instances like database, weblogic server instances in the compartment. This allows them to enable or disable Metric Extension on the monitored resources.

Developing Metric Extensions

  1. Creating Metric Extensions
  2. Test and Edit Metric Extensions

Creating Metric Extensions

  1. From the Stack Monitoring menu, select Metric Extensions.
  2. Click Create Metric Extension. The Create Metric Extension UI panel displays.

  3. Metric Extensions properties:

    1. Enter a Name for the Metric Extension. The Metric Extension name will always have an ME_ prefix.
      Note

      The Metric Extension name must be unique across a resource type.
    2. Enter a Display name for the Metric Extension.
    3. Enter a Description of the Metric Extension.

  4. Collection method properties specify the resource type for the Metric Extension being created and other collection properties:

    • Resource type: the resource type (e.g. Host, Container DB) for which you are creating the Metric Extension. For more information regarding resource types supported and their supported instance properties, see Resource Types supported and their supported instance properties.
    • Collection frequency: specify how often the Metric Extension should be collected.
    • Collection method: Specify the type of collection method needed to collect the Metric Extension. Following collection methods are supported. For details of each collection method and examples, see Collection Method Properties
      1. OS Command: This method executes the specified OS command or script and parses each command output line (delimited by a user-specified character) into multiple values. The metric result is a multi-row, multi-column table.
      2. SQL: This method executes custom SQL queries or function or SQL scripts against databases, returning results in a metric table.
      3. JMX: (Java Management Extensions) : this method retrieves JMX attributes from JMX-enabled servers and returns these attributes as a metric table.

  5. Metrics/dimensions:

    For each of the values returned by running a Metric Extension, identify if the value is a metric or dimension along with its associated properties.

    Note

    • Values returned by custom scripts are expected to result in a multi-row, multi-column table.
    • The output from each column should be identified as either a metric or dimension along with its associated attributes.
    • A metric data point must be a number.

    Metric dimensions should contain the following attributes:

    1. Name: specify the name of the metric or dimension having only english alphabets in PascalCase i.e. Every first letter of the word should be a capital letter with no spaces or numbers in between as per OCI monitoring requirements. Examples of a good metric name are CpuUtilization, TotalDatabaseSize , FileSystemUsage etc.
      Note

      Draft metrics can have the same names for the same resource type, but not in the case of published metrics . If a particular metric name for a resource type is already taken and is used in a published Metric Extension, then the same cannot be used by another metric which is part of any other published Metric Extension's name for the same resource type.

      For example, if there is a published Metric Extension ME_FirstMetricExtension for resource type host_linux and it has a metric named MetricFirst, then it is not allowed to publish another Metric Extension, ME_SecondMetricExtension for the same resource type, host_linux which has a metric with name MetricFirst.

      This constraint is not applicable to hidden metrics and dimensions.

    2. Display name (optional):specify the display name, if different from the name. Display name can carry spaces and numbers as well.
    3. Is dimension?: Choose No if you are defining a metric; choose Yes if you are defining a metric dimension.

      A dimension is a qualifier for a metric and it should be a unique value for each row in the metric collection results. For example, a metric could be the Filesystem Usage percentage, and the dimension is the Filesystem Name.

    4. Is hidden? (Advanced): Choose Yes if the metric will only be used in Compute expressions, i.e. if the metric is used only as a value to compute another metric or it is not required to be sent to OCI Monitoring. Otherwise, choose No.
    5. Value type: All non-hidden metrics must be numeric; A hidden metric or dimension can be String or Number.
    6. Unit : The unit associated with the metric. Possible units could be, depending on the metric, latency in seconds, milliseconds, microseconds, minutes, or frequency in Hertz or percentage.
    7. Category: Identify the type of metric data the metric is collecting: Availability, Capacity, Load, Utilization

    8. Compute expression: Use Compute expressions to calculate the value of a metric based on mathematical or logical operations performed on other metrics or dimensions within the same Metric Extension. Compute expressions require at least one other metric to be defined first, and can only include those other metrics that have already been defined in the Metric Extension. For additional details, see Compute Expressions.

  6. Create and test or Create the Metric Extension

    • Create and test allows you to test your Metric Extension against one or more resources and verify the values returned are correct. Based on the values returned, you can continue to edit and test in an iterative manner.

      Note

      When testing a Metric Extension the Management Agent will be restarted. As a result it is recommended to test Metric Extensions on non-production resources.

    • Create allows you to save the Metric Extension definition and test against resources at a later time.

Test and Edit Metric Extensions

  1. After creating the Metric Extension, it is in Draft status. While it is in Draft status, you can continue to edit the Metric Extension definition and test the Metric Extension against resources.
  2. Testing involves selecting a resource on which the metric can be tested. This process may take a few minutes as it involves deploying the Metric Extension to the resource's agents and running the metric collection against the resource.
    Note

    The resources on which you can test and later enable Metric Extensions need to be enabled with Stack Monitoring Enterprise Edition. For details, see Configuring Licensing.
    Note

    When testing a Metric Extension, follow these guidelines:
    • Do not test on production environments.
    • Allocate a test resource instance with its own Management Agent dedicated to testing. A query/script that is being tested in the Metric Extension could perform poorly and thus impact other Management Agent functionality.
    • If testing results in a failure, repeat the steps to create the Metric Extensions.
    • If testing is successful, verify that the metric values returned are correct.

Publishing Metric Extensions

Metric Extensions are not available for general use until they are published. After testing and verifying the results of your Metric Extension, you may now publish it. Once a Metric Extension is published, it can be enabled on your resources.

Note

Once a Metric Extension is published, it CANNOT be edited nor tested any longer.

Enabling Metric Extensions on Resources

Once your Metric Extension has been published, it can be enabled and deployed to intended resources. When enabling the Metric Extension, it is deployed to the agent that is monitoring the resource, which starts metric collection on the resource.

To enable Metric Extensions on resources:

  1. Choose the published Metric Extension from the list of Metric Extensions.
  2. From the row-level action menu select Enable.
  3. Choose the resources on which you want to start the metric collection.
    Note

    The resources on which you can enable Metric Extensions must have the Enterprise Edition license set on it. For details, see Configuring Licensing.
  4. The process of enabling a Metric Extension on a resource may take a few minutes as it involves deploying the Metric Extension to the agent, and starting the metric collection on the chosen resources. Make sure you stay on the page to track the status of the enable request.
    Note

    When deploying Metric Extension to agent for the first time (as part of enabling a Metric Extension on a resource), the deployment can take up to two minutes, this may result in the agent restarting, and hence you may see agent not reporting status for all of the resources monitored by that agent for the duration of the two minutes.

Viewing Metric Extensions

After the Metric Extension has been enabled on a resource, it will automatically show up in the performance charts of its homepage. You can identify the Metric Extension by locating the * symbol next to the metric name.

Metric data from the Metric Extension is stored in the same compartment as the resource on which it is enabled under the namespace oracle_metric_extensions_appmgmt.


stack monitoring homepage with metric extensions

In the Enterprise Summary UI, to show the Metric Extension in any of the charts:

  1. Customize the chart by clicking on the pencil icon.
  2. In the edit dialog that comes up, choose:
    1. Namespace: oracle_metric_extensions_appmgmt
    2. Resource type: the type of the resource on which the Metric Extension was created.
    3. Metric name: the metric from your Metric Extension.

    adding metric extensions to enterprise manager

Metric Extension Parameters

Resource Types supported and their supported instance properties

Resource Type Display Name Resource Type Supported Collection Methods Instance Properties
Host - Linux host_linux OS Command compartmentId, hostType, osType
Apache Tomcat apache_tomcat OS Command, JMX compartmentId, service_url
EBS ebs_instance OS Command, SQL hostname, db_port, db_sid, db_host,db_service, allowed_logon_version, app_schema
Elasticsearch elastic_search OS Command es_base_url
Host - Solaris host_solaris OS Command compartmentId ,hostType, osType
EBS Concurrent Processing oracle_ebs_conc_mgmt_service OS Command, SQL db_host, db_port ,db_sid, app_schema, allowed_logon_version
EBS Forms System oracle_ebs_forms_system OS Command, SQL db_host, db_port, db_sid, app_schema, allowed_logon_version
EBS Workflow Agent Listener oracle_ebs_wf_agent_lsnr OS Command, SQL db_host, db_port, db_sid, app_schema, allowed_logon_version
EBS Workflow Background Engine oracle_ebs_wf_bkgd_engine OS Command, SQL db_host, db_port, db_sid, app_schema, allowed_logon_version
EBS Workflow Notification Mailer oracle_ebs_wf_notification_mailer OS Command, SQL db_host, db_port, db_sid, app_schema, allowed_logon_version
PSFT Application oracle_psft OS Command, SQL hostname, db_port, db_sid, db_host, db_service_name, peoplesoft_json_file, allowed_logon_version, pt_version
PSFT Application Server Domain oracle_psft_appserv OS Command, JMX hostname, jmx_url, ps_cfg_home, app_server_domain, pt_version
PSFT Application Server Group oracle_psft_appserv_group OS Command hostname, db_port, db_host, db_service, pt_version
PSFT PIA oracle_psft_pia OS Command, JMX hostname, jmx_url, ps_cfg_home, pia_domain, pt_version
PSFT PIA Group oracle_psft_pia_group OS Command hostname, db_port, db_host, db_service, pt_version
PSFT Process Monitor oracle_psft_prcm OS Command, SQL db_host, db_port, db_service_name, pt_version
PSFT Process Scheduler Domain oracle_psft_prcs OS Command, JMX hostname, jmx_url, ps_cfg_home, prcs_domain, pt_version
PSFT Process Scheduler Group oracle_psft_prcs_group OS Command hostname, db_port, db_host, db_service, pt_version
Microsoft SQL Server sql_server OS Command, SQL compartmentId, inst_name, hostname, port, root_dir, os_platform, os_distro, os_release, time_zone, version
Oracle WebLogic Cluster** weblogic_cluster OS Command, JMX compartmentId, service_url, server_names, name, version, dms_spy
Oracle WebLogic Domain** weblogic_domain OS Command, JMX admin_server_host, admin_server_port, admin_server_protocol, admin_service, admin_service_url
Oracle WebLogic Server** weblogic_j2eeserver OS Command, JMX compartmentId, service_url, name, version, dms_spy
SOA Infrastructure** oracle_soainfra OS Command, JMX compartmentId, name, server_name, version, service_url
Oracle Managed File Transfer** oracle_mft OS Command, SQL server_name, service_url, db_schema_name, db_port, db_sid, db_host, db_service_name
Container DB oci_oracle_cdb OS Command, SQL N.A.
Non-Container DB oci_oracle_db OS Command, SQL N.A.
Pluggable DB oci_oracle_pdb OS Command, SQL N.A.
Listener oci_oracle_lsnr OS Command oracleHome, lsnrType, alias
ASM oci_oracle_asm OS Command, SQL N.A.
Cluster Instance oci_oracle_cluster_instance OS Command oracleHome
Oracle Identity Manager Cluster** oracle_oim_cluster OS Command, JMX service_url, app_name, server_names, version
Oracle Identity Manager** oracle_oim OS Command, JMX hostname, service_url, app_name, server_names, version, weblogic_home
Oracle Access Management Cluster** oracle_oam_cluster OS Command, JMX service_url, app_name, server_names
Oracle Access Management** oracle_oam OS Command, JMX service_url, app_name, server_names, weblogic_home
Apache HTTP Server apache_http_server OS Command compartmentId, metric_endpoint, httpd_conf_path, httpd_bin_path, httpd_pid_path, protocol
GoldenGate Admin Service oracle_goldengate_admin_server OS Command compartmentId, process_name, api_process_name, pm_server_url
GoldenGate Distribution Path oracle_goldengate_distribution_path OS Command compartmentId,distribution_server_url, path_name,
GoldenGate Distribution Service oracle_goldengate_distribution_server OS Command compartmentId, process_name, api_process_name, pm_server_url
GoldenGate Extract oracle_goldengate_extract OS Command pm_server_url, process_name, api_process_name, compartmentId
GoldenGate Performance Metric Service oracle_goldengate_pm_server OS Command compartmentId, pm_server_url, process_name, api_process_name
GoldenGate Receiver Service oracle_goldengate_receiver_server OS Command compartmentId, process_name, api_process_name, version, pm_server_url
GoldenGate Replicat oracle_goldengate_replicat OS Command compartmentId, pm_server_url, api_process_name, process_name
GoldenGate Receiver Path oracle_goldengate_receiver_path OS Command compartmentId, path_name, receiver_server_url
GoldenGate Service Manager oracle_goldengate_service_manager OS Command ogg_url, ogg_hostname,ogg_port, compartmentId, service_manager_url
Oracle Service Bus (OSB)** oracle_servicebus OS Command, JMX compartmentId, name, server_name, version, service_url
Oracle HTTP Server oracle_http_server OS Command compartmentId, name, service_url

** Some resource types also support remote monitoring. However, they support local monitoring as well, hence OS Command is available only for those resource instances that are being monitored locally by their respective management agent.

Collection Method Properties

OS Command collection method
  • Command: The command to execute. For example, /bin/bash.

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

    Before using any script, ensure the command/script being invoked is not destructive.

    Note

    Use shell commands inside the script content, as they cannot be directly used as part of command value.
  • Delimiter for output: The string used to delimit the command output. An example delimiter could be | .
  • Arguments: Arguments to the script or command separated by a space.
    Note

    Instance property of a resource type can be passed as argument by placing it inside two % symbols. For example in case of host_linux resource type, osType is an applicable instance property. In case, you are required to pass value of this instance property as argument to the script then argument property can be set to %osType%. List of available instance properties is given in the Resource Types supported and their supported instance properties table.
  • Prefix for output: The starting string of metric result lines.

    For example, if the command output is: sm_result= 3454 | abc | def setting the Prefix for output = sm_result specifies that only lines starting with sm_result will be used to gather metric data.

  • Script file: Custom script executed to generate the metric data .
Example:

The creation parameters of a Metric Extension for a listener resource type which captures the handler load, maxload, established, refused, handler ids and connection rate for every service using an OS Command collection method is described bellow:

  • Metric Extension properties:

    Property Name Property Value
    Name ME_GetListenerDetails
    Display name Get Listener Details
    Description

    A Metric Extension for listener resource type which captures the handler load, maxload, established, refused, handler ids and connection rate for every service

  • Collection method properties:

    oracleHome , alias and lsnrType are instance properties of Listener resource type used in the Arguments property inside % symbols. Here % symbols are used to hold the instance property references

    Property Name Property Value on UI Property Value on API (ONLY if different from UI)
    Resource type Listener oci_oracle_lsnr
    Collection method OS Command OS_COMMAND
    Collection frequency 15 Minutes FREQ=MINUTELY;INTERVAL=15
    Command /bin/bash  
    Delimiter |  
    Arguments %oracleHome% %alias% %lsnrType%  
    Prefix for output result=  
    Script file

    services.sh

    • "content" - Should carry base64 encoded content of services.sh

    • "name" : services.sh

  • Metrics/dimensions:

    Metric/dimension Metric/dimension Properties
    TotalRefusedConnections

    • Value type: Number

    • Is dimension?: No

    • Is hidden?: No
    TotalEstablishedConnections

    • Value type: Number

    • Is dimension?: No

    • Is hidden?: No
    MaxConnections

    • Value type: Number

    • Is dimension?: No

    • Is hidden?: No

    • Unit: Connections
    HandlerId

    • Value type: String

    • Is dimension?: Yes

    • Is hidden?: No
    EstablishedConnectionsRate

    • Value type: Number

    • Is dimension?: No

    • Is hidden?: No

    • Compute Expression: (TotalEstablishedConnections > _TotalEstablishedConnections) ? ((TotalEstablishedConnections - _TotalEstablishedConnections) / __interval) : 0

    • Unit: Connections per second

    • __interval can be used to derive rate metrics. Please note __interval is always equal to "seconds" representation of the "Collection frequency" field. For example, if Collection frequency is 15 minutes then __interval is 15x60 i.e. 900 seconds.
    • "_" when prefixed to a Metric name has a special meaning. Such representation in compute expressions can be used to refer to the value of a metric as calculated in the last collection of a Metric Extension. This can be used in compute expressions to derive change in a particular metric's value in comparison to its last collected value. This special prefix can be used to derive delta metrics.
    ActiveConnections

    • Value type: Number

    • Is dimension?: No

    • Is hidden?: No

    • Unit: Connections

SQL Collection Method

  • SQL query: The sql query to execute. For example, 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. Bind variables can be passed to sql query using In parameter properties.

  • SQL Script: Upload the required sql script to execute and provide the relevant In parameter and Out parameter properties. You can use either of SQL query or SQL script.
  • In parameter (optional) - These can be used provide the bind variable for SQL query case or in parameters for SQL script case.
    Note

    This property supports use of instance property place holder which can be used to replace the placeholder with actual value of instance property of the resource for which metric is being collected. For example for oracle_psft , db_service_name is an instance property. It can be passed inside an In parameter value within a pair of % (percentage) symbols, such as %db_service_name%.
  • Out parameter position (optional) - This is the position number of out parameter
  • Out parameter type (optional) - This is the type of out parameter.
Example:

The creation parameters of a Metric Extension for Non-container DB resource type which captures the Wait Time for different wait classes using a SQL collection method is described below:

  • Metric Extension properties:

    Property Name Property Value
    Name ME_GetWaitTime
    Display name Get Wait Time
    Description

    A Metric Extension for Non-container DB resource type which captures the

    Wait Time for different wait classes

  • Collection method properties:

    Property Name Property Value on UI Property Value on API (ONLY if different from UI)
    Collection frequency 1 Hours FREQ=HOURLY;INTERVAL=1
    Collection method SQL  
    Resource type Non-Container DB oci_oracle_db
    SQL query 
    WITH wait_stats AS (
SELECT
inst_id,
wait_class,
time_waited_fg
FROM
TABLE ( gv$(CURSOR(
SELECT
to_number(userenv('INSTANCE')) AS inst_id,
wait_class,
time_waited_fg / 100 AS time_waited_fg
FROM
v$system_wait_class
WHERE
wait_class <> 'Idle'
)) )
), inst_list AS (
SELECT
instance_number,
instance_name,
host_name
FROM
TABLE ( gv$(CURSOR(
SELECT
instance_number,
instance_name,
host_name
FROM
v$instance
)) )
)
SELECT
inst.instance_number instance_number,
inst.instance_name instance_name,
inst.host_name host_name,
ws.wait_class wait_class,
ws.time_waited_fg time_waited_fg
FROM
wait_stats ws,
inst_list inst
WHERE
inst.instance_number = ws.inst_id

    • "content" - Should carry base64 encoded content of services.sh

    • sqlType : STATMENT

  • Metric/dimensions:

    Metric/dimension Metric/dimension Properties
    InstanceNumber

    • Value type: Number

    • Is dimension?: Yes

    • Is hidden?: No
    InstanceName

    • Value type: String

    • Is dimension?: Yes

    • Is hidden?: No
    HostName

    • Value type: String

    • Is dimension?: Yes

    • Is hidden?: No
    WaitClass

    • Value type: String

    • Is dimension?: Yes

    • Is hidden?: No
    TimeWaitedSeconds

    • Value type: Number

    • Is dimension?: No

    • Is hidden?: No

    • Unit: Seconds

JMX collection method

  • MBean name - JMX MBean ObjectName or Metric Service table name.
    Note

    This property supports use of instance property place holder which can be used to replace the placeholder with actual value of instance property of the resource for which metric is being collected. For example for weblogic_j2eeserver , service_url is an instance property. It can be passed inside MBean name value string within % symbols, such as %service_url%.

    JMX attributes and Identity column also support use of instance property placeholder.

  • JMX attributes - Java Management Extensions (JMX) attributes. List of JMX attributes or Metric Service columns, separated by semi-colon.
  • Identity column (Optional) - Semi-colon separated list of key properties from Managed Bean ObjectName to be used as key metrics.
  • Auto row prefix (Optional) - This is prefix used for an automatically generated row as key metrics. For example : if it is set to ShipItem-, then values will be set as ShipItem-0, ShipItem-1 and so on.
  • Metric service Enabled on Server domain ? (Optional) - Indicates whether Metric Service is enabled on server domain. If set to true, then the basic property MBean name should represent the Metric Service table name and the basic property JMX attributes will represent a semi colon separated list of column names for MetricService table.
    Note

    Check this option only when you have Metric Service applicable to the resource type and enabled on the server domains.
Example:

The creation parameters of a Metric Extension for an oracle weblogic server resource type which captures the collection time of the Garbage Collector using JMX collection method.

  • Metric Extension properties:

    Property Name Property Value
    Name* ME_TotalGcExecutionTime
    Display name* Get Total Garbage Collection Time
    Description

    A Metric Extension for oracle weblogic server resource type which captures the

    total garbage collection execution time

  • Collection method properties:

    Here name is an instance property of Oracle Weblogic Server and is being used inside % instance property placeholder inside Mbean name attribute of JMX type Metric Extension definition.

    Property Name Property Value on UI Property Value on API (ONLY if different from UI)
    Resource type Oracle WebLogic Server weblogic_j2eeserver
    Collection method JMX  
    Collection frequency 1 Days FREQ=DAILY;INTERVAL=1
    Mbean name java.lang:Location=%name%,type=GarbageCollector,*  
    JMX attributes CollectionTime  
    Identity column name;Location  

  • Metrics/dimensions:

    Metric/dimension Metric/dimension Properties
    ServerName

    • Value type: String

    • Is dimension?: Yes

    • Is hidden?: No
    ServerRuntime

    • Value type: String

    • Is dimension?: Yes

    • Is hidden?: No
    TotalGCExecTime

    • Value type: Number

    • Is dimension?: No

    • Is hidden?: No

    • Unit: milliseconds

Compute Expressions

To create valid compute expressions, you must give space between operators and operands/metric names.

Example:

((MetricA * MetricB) / MetricC)

Please note the use of space between MetricA and the * symbol. Similarly, a space is important between * and MetricB, between closing parenthesis and / symbol and / symbol and MetricC.

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

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

Usage of Operators:

This attribute specifies the formula for calculating the value of the metric. Metrics previously defined in the Metric Extension can participate in the calculation.

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

Predefined special values:

Note

For string expression inputs required for certain operators, provide the input value inside single quotes ( ' ).

  • __interval: collect interval. Its collection frequency is represented in seconds.
  • __sysdate: current system time.
  • _metricName : Refers to value of metric during its previous collection. While metricName needs to be replaced with actual metric's name.
  • __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
  • __is_notnull : tests whether the expression is NOT 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="(MetricA + MetricB )/ 2"

    The value of the metric is the average of the other two metrics MetricA and MetricB.

  • NAME="Version" COMPUTE_EXPR="(MetricA __contains 'NetApp Release 7.') ? 7.0 : 6.0"

    The value of the metric Version is computed as 7.0 if metric MetricA contains the String NetApp Release 7.

  • NAME="MetricA" COMPUTE_EXPR="(MetricB - MetricC)"

    The value of the metric MetricA is the difference of the columns MetricB and MetricC.

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

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

  • NAME="MetricA" COMPUTE_EXPR="(__is_null MetricB)?'yes':'no'"

    The value of the column MetricA is yes if the value of Metric2 is null and no otherwise.

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

    The value of the metric Source is string empty if the length of string value of metric result is 0, else it is the value of the metric result itself.

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

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

  • NAME="MetricA" COMPUTE_EXPR="((MetricB == 0) ? 0 : ((MetricC / (MetricB / 8)) * 100.0))"

    The value of the MetricA is 0 if MetricB is equal to 0 , else value of MetricA is 100* MetricC divided by 1/8th of MetricB the computed based on MetricB and MetricC are using above formula when MetricB is not equal to 0, otherwise it is 0.

  • NAME="PERCENTAGE_VALUE" COMPUTE_EXPR="(Metric1 != 0) ? 100.0*(Metric2/Metric1) : 0"

    The value of the column is the total percentage of disk available where Metric1 and Metric2 are existing metrics in the Metric Extension.

  • NAME="RATE_OF_CHANGE" COMPUTE_EXPR="((MetricA - _MetricA) / __interval)"

    The delta and rate of a metric can be generated inside a compute expression by subtracting its previously collected value from current collected value to get the delta and dividing the delta by __interval to get the rate.

Creating Alarms on Metric Extensions

You can create alarm rules to trigger alarms when metric values from your Metric Extensions cross thresholds. Use the same general workflow that you would follow to create an alarm rule for built-in metrics for your resources. The main difference is in the Metric description section.

In the Metric description section of the Alarm rule:

  • Compartment: choose the compartment of the resource on which the Metric Extension was enabled
  • Metric namespace: select oracle_metric_extensions_appmgmt
  • Resource group: the resource type of the resource on which the Metric Extension was enabled.

Creating an Alarm rule for a Metric Extension of a host is shown in the image below:


creating alarm rules for metric extensions