aliasMetric Function

Summary

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

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

aliasMetric(<tsExpression>, [metric|source|{tagk, <pointTagKey>}],
        "<regexSearchPattern>", "<replacementPattern>")

Replaces the metric name for each time series with an alias, which can be a specified string or derived from existing metadata.

To replace the source name with an alias, use aliasSource().

Parameters

Description

The aliasMetric() metadata function lets you replace the metric name of each time series described by tsExpression with an alias. The alias can be a specified string or a string that is derived from the metric name, the source name, an existing point tag value, or a combination of these.

Here are some sample scenarios:

• You want to clarify the column headings in a Table chart.
• You want an aggregation function to group by a given parameter that is only found within a metric, source, or point tag value.
• You want to make complex metric names easier for end users to understand.
• You use derived metrics.

aliasMetric() lets you replace metric names with:

• A simple replacement string.
• A replacement string that contains variables.
• A single node that is extracted from the original metric name, the source name, or a point tag value.
• Substrings that are matched by regular expressions from the original metric name, the source name, or a point tag value.

Simple Replacement String

You can specify a simple replacement string if you want to use the same metric name for all time series described by tsExpression.

Suppose you have a metric ts("customer.user.total") in your environment that tracks the number of total users of your product by customer. 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 Table 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.

aliasMetric(sum(ts("customer.user.total"),customer), "Total Users")

Replacement String With Variables

You can specify a replacement string with variables if you want the new metric name for each time series to contain one or more metadata values from that series. You can use any combination of variables and embed them in text. The following variables obtain the actual metric name, the source name, or the value of a specified point tag:

"{{metric}}" "{{source}}" "{{<pointTagKey>}}"

Suppose you have a metric ts(aws.instance.price) that has a region point tag, and you want to display a chart in which the metric name of each time series consists of the string Price, followed by the value of the region tag and the source name, separated by slashes. The following function accomplishes this:

aliasMetric(ts(aws.instance.price), "Price/{{region}}/{{source}}")

The specified replacement string acts like a template, in which VMware Aria Operations for Applications (formerly known as Tanzu Observability by Wavefront) replaces each variable with the requested string value. If ts(aws.instance.price) describes a time series that has a point tag region=us-west-2, that time series is displayed with a metric name like Price/us-west-2/mycluster-2c-ha2-i-00e421d1bef7fb88e.

Single Extracted Node

A common practice is to use naming conventions that provide structure to metric names, source names, or point tag values. Naming conventions typically subdivide metadata values into nodes, which are substrings that are delimited by certain characters. By default, Operations for Applications uses periods (“.”) as node delimiters, but your naming conventions might use other characters.

You can use aliasMetric() with a zeroBasedNodeIndex to extract a single node from an existing metadata value and use just the extracted node as the metric name for your time series. For example, you might want to simplify a metric name like pdx.customerA_latency.i49f21a72 by displaying it as customerA_latency.

zeroBasedNodeIndex specifies the node to extract by counting nodes from left to right, starting with 0. By default, aliasMetric() extracts the node from the existing metric name. To extract a node from the source name or a specified point tag value, you must explicitly include source or tagk, <pointTagKey>.

For example, suppose you use the following naming convention for a metric namespace, and you consider periods (“.”) to be node delimiters: <datacenter>.<customerName>_latency.<idNumber>

Under these conventions, the nodes in the metric name pdx.customerA_latency.i49f21a72 are numbered as follows:

The following query extracts customerA_latency from the existing metric name and uses it as the new metric name:

aliasMetric(ts(pdx.customerA_latency.i49f21a72), 1)

customerA_latency is a single node because it does not contain a period (“.”), which is the default delimiter. You can specify a nondefault set of delimiters to change how names are divided into nodes. For example, the following query extracts just customerA from the existing metric name by redefining the delimiter set to include both periods (“.”) and underscores (“_”):

aliasMetric(ts(pdx.customerA_latency.i49f21a72), 1, "._")

Matched Substrings

You can use aliasMetric() with a regular expression "regexSearchPattern" to match one or more substrings from an existing metadata value, and then construct the new metric name "replacementPattern" from one or more matched substrings. You can combine these substrings with text and variables.

By default, aliasMetric() applies the regular expression to the existing metric name. To apply the regular expression to the source name or to a specified point tag value, you must explicitly include source or tagk, <pointTagKey>.

For example, assume your metric comes from sources whose names follow the pattern db-1, db-2, and so on. The following query renames the metric for each time series by combining the numeric part of the source name with the value of the env point tag, and prefixing it with the string connect:

aliasMetric(ts(~sample.db.connections.*), source, "db-([0-9]*)", "connect-$1-{{env}}")

Examples

Here is a summary of the sample aliasMetric() queries from the examples in the sections above.

• Replace metric names with a simple string:

  aliasMetric(sum(ts("customer.user.total"),customer), "Total Users")
  

• Replace the metric name with a string that contains metadata variables:

  aliasMetric(ts(aws.instance.price), "{{region}}/{{source}}")
  

• Replace the metric name with a single node extracted from it:

   aliasMetric(ts(pdx.customerA_latency.i49f21a72), 1)
   aliasMetric(ts(pdx.customerA_latency.i49f21a72), 1, "._")
  

• Replace the metric name by combining text, a matched substring, and a point tag value:

  aliasMetric(ts(~sample.db.connections.*), source, "db-([0-9]*)", "connect-$1-{{env}}")
  

Learn More!

• For an in-depth discussion, see Metadata (Label Manipulation) Functions
• For additional examples, see the aliasSource() Function.