Reference to the aliasMetric() function

Summary

aliasMetric (<expression>, [metric|source|{tagk, <pointTagKey>}, <newPointTagKey>},]
         [<zeroBasedNodeIndex> [, "<delimiterDefinition>"])

aliasMetric (<expression>, [metric|source|{tagk, <pointTagKey>}], “<regexSearchPattern>”,
         “<replacementPattern>” | "<replacementString>"])

Extract a string from an existing metric name, source name, or point tag value and rename the metric in expression with that string. If you don’t specify the second parameter (metric|source|{tagk, <pointTagKey>}), it defaults to metric.

Here are some sample scenarios:

  • You want to group by a given parameter that is only found within a metric, source, or point tag value.
  • You want to clean up the view of the Tabular View chart columns
  • The complexity of your metric name is too much for the end users and you want to make it easier for them to digest what is being captured.
  • You use derived metrics

Parameters

ParameterDescription
expression The ts() expression to extract a string from.
metric|source|{tagk,<pointTagKey>} The set of data to extract a node from. This node is then used to rename one or more metrics.
  • Use {tagk, <pointTagKey> } if you want to extract a node from an existing point tag value. To use this approach, enter tagk followed by the point tag value.
    For example, if you have point tag Region=us-west-2b, and you want to replace the existing metric name with the entire point tag value, enter tagk, Region and set zeroBasedNodeIndex to 0.
  • If you don't specify metric, source, or tagk, this parameter defaults to source.
zeroBasedNodeIndex The node to extract from the selected source name(s), metric name(s), or point tag value(s). This node is then used to rename one or more metric(s). You either use a zeroBasedNodeIndex or a regx to specify the node.
"delimiterDefinition" Use this optional parameter to specify a delimiter other than period ("."). For example, to extract total_environment from disk.space-total_environment, set zeroBasedNodeIndex to 2 and "delimiterDefinition" to ".-". If no "delimiterDefinition" is specified, then only periods (".") are considered delimiters.
"regexSearchPattern", "replacementPattern" Use these parameters to use a regular expression to specify the node that you want to extract with aliasMetric().
  • "regexSearchPattern" - A regular expression pattern to match against the extraction node specified above (metric is the default).
  • "replacementPattern" - The replacement string. If capturing groups are used in regexSearchPattern, they can be referred to as $1, $2, etc.

Description

aliasMetric() lets you replace one or more existing metric names in a ts() expression with a string extracted from metric name(s), source name(s), or point tag value(s). For example, let’s say you have a metric in your environment that tracks the number of total users of your product by customer:

ts("customer.user.total")

The series associated with this metric includes a customer point tag key to “group by” when applying an aggregate function.

sum(ts("customer.user.total"),customer)

If you want to display this information as a column on a tabular view chart, the current aggregate metric does not display properly. However, you can use aliasMetric() to rename the aggregate metric, and to apply a column header of Total Users.

You can use the aliasMetric() function using the zeroBasedNodeIndex, regular expression replacement, or simple string replacement approach.

zeroBasedNodeIndex Approach

If you use the zeroBasedNodeIndex approach for aliasMetric(), you extract a single node from an existing source name, metric name, or point tag value for the purpose of renaming a metric. Nodes are separated by delimiters such as periods or hyphens. Suppose you have the following naming convention for a metric namespace:

<datacenter>.<customerName>_latency.<idNumber>

e.g. pdx.customerA_latency.i49f21a72

The aliasMetric() function assigns a number to each node. The node numbers are associated with the zeroBasedNodeIndex parameter. For the example above:

node node number
pdx 0
customerA_latency 1
i49f21a72 2

By default, Wavefront identifies items separated by a (“.”) delimiter as nodes. This is why customerA_latency is considered a single node.

If the data you want to extract a node from includes delimiters such as a hyphen (“-“) or underscore (“_”), then you can use the "delimiterDefinition" parameter.

See the examples below for details.

Regex Approach

You can also use a regular expression with aliasMetric() to transform an existing source name, metric name, or point tag value. This approach works as a “search-replace” functionality—everything that matches regexSearchPattern is replaced with replacementPattern. See the examples below for details.

Examples

The following example illustrates the zeroBasedNodeIndex approach. More detailed examples are on the aliasSource page. The examples for aliasMetric are similar.

aliasMetric Using a zeroBasedNodeIndex - Example

In this example, you rename metric(s) with an existing point tag value.

Assume that you have a set of metric names that are very long and clutter your hover legend:

<datacenter>.<version>.<customer>_latency.<id>

The information you want from the metric name is <customer>_latency. <datacenter> and <version> are sent as optional point tag key values, so you don’t need them in the hover legend. aliasMetric() lets you rename each metric to declutter your hover legend:

aliasMetric(ts("<datacenter>.<version>.<customer>_latency.<id>"), 2)

In this case, you are extracting from a metric name, so you don’t need to specify ',metric' before applying the zeroBasedNodeIndex value.