Reference to the aliasMetric() function

Summary

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

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

aliasMetric (<expression>, "<newMetricName>")

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 the new metric name from.
  • 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 key.
    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 metric.
zeroBasedNodeIndex, "delimiterDefinition" Use these parameters if you want to extract a single node from an existing source name, metric name, or point tag value and use it as the new metric name.
  • zeroBasedNodeIndex - Node to extract from the selected source name, metric name, or point tag value. This node is then used as the new metric name.
  • 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 if you want to use regular expression search and replacement patterns from an existing source name, metric name, or point tag value as the new metric name.
  • "regexSearchPattern" - A regular expression pattern to match against the source name, metric name or point tag value.
  • "replacementPattern" - The replacement string. If capturing groups are used in regexSearchPattern, they can be referred to as $1, $2, etc.
"newMetricName" Use this parameter to specify a new static value to use as the new metric name.

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.

Improving Readability by Manipulating the Output

All metadata functions support inserting the value of the metric, source or tags in replacement strings via the <entity> syntax.

For example:

aliasSource(ts(aws.instance.price), "{{Region}}-{{source}}")

Adds the value of the region tag and a hyphen to the original source.

That means mycluster-2c-ha2-i-00e421d1bef7fb88e is converted to us-west-2-mycluster-2c-ha2-i-00e421d1bef7fb88e if the source is us-west-2.

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.