Custom call metrics (public preview)

You can annotate calls of your application with custom call metrics (numeric values) through manual instrumentation with language-specific Instana SDKs. By using these call metrics in the Unbounded analytics view, you can filter calls by numeric conditions (less or greater than) and also graph aggregates of these values over time.

Purpose and usage examples

With custom call metrics, you can analyze call-related numeric data that Instana does not collect by default. They can be used for technical metrics, such as data sizes or timings, or even for business-related metrics, such as the total value of items in a shopping cart. The values must be integers, so you need to use appropriate scaling.

Custom call metrics extend the existing support for annotating calls in the instrumented code with custom call tags, which allow to filter and categorize calls according to user-defined string values. As custom metrics are numeric values, you can not only use them for filtering and grouping, but you can also aggregate the numbers over groups of calls.

The following tasks present some examples how you can make use of call metrics in the Unbounded analytics view:

  • Annotate calls with the size of some processed data and then filter on that size to see calls where that size exceeds a certain threshold.
  • Use the same data size annotations to view how the maximum data size in calls changes over time.
  • Track timings inside a call, if you are interested in a certain processing phase in addition to the overall call latency that Instana records by default.
  • Track access to some cache by calls, representing a cache hit as 100 and a cache miss as 0, and then use the mean aggregation to see a chart of cache hit percentage for calls over time.

Sending custom call metrics to Instana

To send custom call metrics to Instana, complete the following steps:

  1. Annotate application calls in your code with the same tracing SDK methods that are used to annotate the calls with string key-value data for call tags.
  2. If you want the annotation to be stored as a numeric call metric instead of a string call tag, use the metrics. prefix for the key.
  3. Make sure the value can be parsed as an integer. Depending on the language and SDK, pass integers directly or convert them to strings to fit the API definitions.

For the Java Trace SDK, you can annotate a call with custom call metrics as shown in the following example:

SpanSupport.annotate("metrics.processingTime", String.valueOf(1234));

Analyzing custom call metrics

You can use call metrics for the following tasks:

Filtering calls by using call metrics

To filter calls using call metrics, complete the following steps in the Unbounded analytics view:

  1. From the sidebar of the Instana UI, select Analytics.
  2. On the Analytics page, click the arrow on the Applications breadcrumb trail, and then select Calls.
  3. Click Add filter.
  4. Select Calls > Custom call metrics, and then provide a metric key, value, and comparison operator for the filter.

The keys for call metrics are case sensitive, like those for call tags. So a filter on processingtime > 1000 (lower-case t) will not match the a call with the sample SDK annotation shows in the preceding example, which uses processingTime as the key.

You can also use call metrics in the filter conditions for application perspectives, just like any other filter on calls.

Grouping calls by using call metrics

You can use call metrics as a grouping field in the Unbounded analytics view. As querying calls with a large number of groups may perform badly, you should only use a call metric for grouping when you know that the range of possible values sent by your application is restricted to at most a few 100 different values.

Displaying charts for custom call metrics

You can also show charts for custom call metrics in Unbounded analytics for calls. To display charts, complete the following steps:

  1. From the sidebar of the Instana UI, select Analytics.
  2. On the Analytics page, click the arrow on the Applications breadcrumb trail, and then select Calls.
  3. In the Chart widget, select Custom call metrics from the list and then, enter a metric key and the aggregation that should be used to combine metrics in each time bucket.

Currently, only bar charts and stacked bar charts (for grouped analytics) are supported.

Performance note

Just like for string key-value annotations, keep the set of keys that you use small (up to a few 100 keys) and don't put any frequently changing parts, such as process IDs, in the key strings. Excessive use of different keys may degrade performance.

Known limitations

The following aspects of call metrics are not fully supported:

  • Call metrics can not be used in filter conditions for smart alerts. You can, however, use string value call tags in smart alert filters.
  • Call metrics can not be used in custom dashboards. You can chart call metrics only in the Unbounded analytics view.
  • Charting of call metrics in the Unbounded Analytics view does not properly display negative numbers. The Y-axis always starts at 0, just like for any of the other pre-defined metrics.