Custom Metrics

About Custom Metrics

Allow users to configure how metrics for their spans are collected depending on their reporting needs.
Users can set up their own definitions of metrics based on properties of the spans, which enables them to configure customized ways of monitoring their applications.
Custom metrics use span filters to select the spans for which metrics are to be computed. This allows users to define different sets of metrics for different types of spans.
For fine-grained reporting, the metrics can be assigned dimensions which allows for grouping and filtering based on those dimensions. For example, reporting users per browser type or articles sold per country.
Custom Metrics are configured at APM Domain level.

Custom Metrics Example Use Cases

Example 1: Create a metric to track the number of errors that happen during the checkout step.

For this use case, you need to identify the spans which have failed during the checkout step. Assuming the URL for the checkout page ends with checkout.jsp, you can define a Span Filter that checks if the HttpUrl attribute ends with checkout.jsp, and also checks if the Error attribute is set to true.

HttpUrl like '%checkout.jsp' AND Error = 'true'

As value source, select the SpanErrorCount. This will have the value 1 if there was an error in the page and 0 otherwise. Additionally, it might be interesting to know if the errors only happen with specific browsers so you can add the BrowserName dimension.

Example 2: Create a metric to track the home page response time

In this scenario, we want to track the response time of our home page. For this, you can use the PageResponseTime value source. You can set up a Span Filter to match your home page called home.php.

HttpUrl like '%home.php' AND ApmrumType = 'PAGE'

Now, select PageResponseTime for the value source. Additionally, you can add dimensions as you see fit. For example, GeoCountry to get a breakdown on response times per country.

Manage Custom Metrics

To create a custom metric for a desired APM domain, do the following:

Go to the APM domains page and click on the desired APM domain.

The Domain details page is displayed.
Go to Resources, located at the bottom left and click Custom metrics

The Custom metrics pane is displayed.
From the Custom metrics pane, click Create custom metric.

The Create custom metric window is displayed.
- Enter the Metric name of the new custom metric.
- From the Span filter box, choose a predefined (global) span filter or type in a local span filter definition.
- From the Metric value source dropdown list, select a metric.
- Optional: From the Dimension(s) dropdown list, select one or multiple dimensions. The maximum number of dimensions is 10.
- Optional: From the Metric unit dropdown list, select a metric unit.
- Optional: Click Validate custom metric to check if any recently ingested spans match the configured span filter. The validation tool allows for checking on ingested spans for up to 24 hours in the past.
- Click Next to proceed to the Choose metric storage options.
- From the Compartment dropdown list, select a compartment.
- From the Namespace field, enter a namespace.
  The default namespace for all custom metrics is oracle_apm_custom.
  
  Use a custom namespace: If preferred, you can provide a custom namespace to be used by the custom metric.
  
  When using a non-default namespace, a policy is required to get created for the new namespace.
  - From the Namespace field, edit the default value and enter the preferred namespace.
  - The Policy required for new namespace message is displayed indicating the following policy is required:
    Allow service applicationperformancemonitoring to manage metrics in compartment <compartment_name> where target.metrics.namespace=<custom_namespace_name>
    For example:
    Allow service applicationperformancemonitoring to manage metrics in compartment ABC where target.metrics.namespace=namespace2
    The above policy allows the OCI Application Performance Monitoring service to publish in the custom namespace.
    The following options are available:
    
    Copy policy: The policy gets copied to the clipboard and needs to get created manually using the OCI Console.
    Use this option if you don't have permissions to create policies in OCI. In most cases, an administrator user needs to create the policy.
    
    Validate policy: The policy gets validated by using a test metric and checking the permissions in the custom namespace.
    
    Apply policy: The policy gets created automatically.
    Use this option if you have permissions to create policies in OCI. For example, if you have administrator permissions.
    For information about how to create policies, see Creating a policy under the Identity Management documentation.
- Optional: From the Resource Group dropdown list, select a resource group.
- Click Create.
  If creation process fails when using custom namespace, check if the Application Performance Monitoring service has access to write to the custom namespace.

Use the action menu to edit or delete a custom metric.

If you have an existing custom metric and want to update it to start using a custom namespace (instead of using the default namespace oracle_apm_custom), ensure that the above policy is applied to the custom namespace.

Oracle Cloud Infrastructure Documentation