Working with metadata functions - aliasSource, aliasMetric and taggify

This article applies to:

Visualizing Data

 

Overview

Metadata functions like aliasSource, aliasMetric and taggify enable users to temporarily rename a source, a metric or create a synthetic point tag for display purposes in charts or dashboards.

This article describes how to use the functions with some use cases and examples.

 

All three metadata functions operate with the options:

  • To specify a string,
  • To use a numeric zeroBasedNodeIndex
  • To use a regex search/replace pattern. 
Parameter options:
aliasSource(<tsExpression>, [metric|source|{tagk,<pointTagKey>},]zeroBasedNodeIndex[, "delimiterDefinition"] |"regexSearchPattern", "replacementPattern" |"replacementString")
aliasMetric(<tsExpression>, [metric|source|{tagk,<pointTagKey>},]zeroBasedNodeIndex[, "delimiterDefinition"] |"regexSearchPattern", "replacementPattern" |"replacementString")
taggify(<tsExpression>, metric|source|{tagk,<pointTagKey>}, <newPointTagKey>, zeroBasedNodeIndex[, "delimiterDefinition"] | "regexSearchPattern", "replacementPattern" | "replacementString")

 

In order to demonstrate the metadata functions in action, vsphere and sample metric data will be used. For example see screenshot below which uses metric : "vsphere.host.cpu.used.summation".

vsphere.JPG

Simple string replacement

aliasSource:  To change the displayed source name to an alternative name, the syntax:

aliasSource(<tsExpression>, "replacementString") is used.

For example, to rename the source from "esxi-11" to "esxi-11-to-be-decommissioned":

aliasSource(ts("vsphere.host.cpu.used.summation", source=esxi-11),"esxi-11-to-be-decommissioned")

aliasSource.JPG

 

aliasMetric:  To change the displayed metric name to an alternative name, the syntax: aliasMetric(<tsExpression>, "replacementString") is used.

For example, to rename the metric from "vsphere.host.cpu.used.summation" to "vsphere-esxi-cpu-used-summation":

aliasMetric(ts("vsphere.host.cpu.used.summation"),"vsphere-esxi-cpu-used-summation")

aliasMetric.JPG

taggify: To add a displayed point tag using taggify, the syntax:

taggify(<expression>, <newPointTagKey>, "<newPointTagValue>") is used. 

For example, to add a point tag "Physical location", "Site B":

taggify("vsphere.host.cpu.used.summation" and source="esxi-11", "Physical location", "Site B") 

taggify-site.JPG

Simple string replacement with variables

You can also specify a replacement string using variables from the time series to contain one or more metadata values from that series.

For example, using aliasSource, the source name below, is altered to include the value of the specified point tag for physical location (where variable ${A} is: taggify("vsphere.host.cpu.used.summation" and source="esxi-11", "Physical location", "Site B")):

aliasSource(${A},"{{source}}-{{Physical location}}")

esxi-source-pointtag.JPG

The following example uses aliasMetric, to alter the metric name,to the value of the specified point tag for physical location (where variable ${A}: is taggify("vsphere.host.cpu.used.summation" and source="esxi-11", "Physical location", "Site B")):

aliasMetric(${A},"vsphere.host.cpu.used.summation-{{Physical location}}")

metric-variable.JPG

 

The following example,using taggify, adds a new point tag, using an existing specified point tag in combination with the source, for source and physical location (where variable ${A} is: taggify("vsphere.host.cpu.used.summation" and source="esxi-11", "Physical location", "Site B")):

taggify(${A},"Host/Site","{{source}}/{{Physical location}}")

host-site.JPG

 

Numeric zeroBasedNodeIndex

When using any of the metadata function, it is possible to extract a single node from an existing source name, metric name, or point tag value and use it as a new value. Nodes are indexed from left to right, starting with 0. A delimiter (".") is used to differentiate between the nodes. For example with the sample metric, vsphere.host.cpu.used.summation, vsphere would be node 0, host would be node 1, cpu would be node 2, used would be node 3 and summation would be node 4 etc. All three metadata functions operate a single node extraction in the same way. For brevity, only an aliasSource zeroBasedNodeIndex example will be used. 

aliasSource:  To change the displayed source name to an alternative name, using zeroBasedNodeIndex the syntax:  aliasSource(<tsExpression>, [metric|source|{tagk, <pointTagKey>},] <zeroBasedNodeIndex> [, "<delimiterDefinition>"]) is used.

For example, to rename the source from "version.7.esxi101" to "esxi101":

aliasSource(ts("vsphere.host.cpu.used.summation", source="version.7.esxi101"), 2). Where 2 is the 3rd node from the left as per delimiter.

version-7-esxi.JPG

Should the delimiter be something other than ("."), the delimiter definition can be used.

For example, to rename the source from "version-7-esxi101" to "esxi101":

aliasSource(ts("vsphere.host.cpu.used.summation", source="version-7-esxi101"), 2,"-"). 

version7-delim.JPG

To rename the source name from the metric name using the zeroBasedNodeIndex. For example, to rename a source to esxi150, from the metric name, "vsphere-version7-esxi150-cpu-used", using the 3rd node: aliasSource("vsphere-version7-esxi150-cpu-used"},metric, 2,"-").

aliasSourceMetricName.JPG

To rename the source name from a point tag using the zeroBasedNodeIndex, specify the point tag with "tagK", and the point tag name. For example, to rename the source to esxi1750, from the point tag, "hostname", which has a value "esxi1750.vmware.com" using the zeroBasedNodeIndex :

aliasSource(ts("vsphere.host.cpu.used.summation",tagK,hostname,0) ,where node 0 is esxi1750

aliasSourcePointtag.JPG

An error message will be displayed if a node that doesn't exist is referenced, for example: aliasSource(ts("vsphere.host.cpu.used.summation",tagK,hostname,5), the following error message is received:
globalFilter() removed all query keys
Cannot access node: 5 from source value: vsphere.host.cpu.used.summation

Regex search and replace patterns

Regexes in aliasSource, aliasMetric and taggify work as “search/replace”;  if there is no match during the search, there is nothing to replace, so the original displayed values remain.
aliasSource:  To change the displayed source name to an alternative name, using a search and replace regex, the syntax:  aliasSource(<tsExpression>, [metric|source|{tagk,<pointTagKey>},"regexSearchPattern", "replacementPattern" ) is used.

For example, to rename all the sources beginning with "perf18" to "Performance-Machine-#" , capture everything after the perf18 that is a number and put that into the capture group. The replacement pattern then is the $1 variable, for example, "Performance-Machine-$1"). 

aliasSource(ts("vsphere.vm.cpu.usagemhz.average",source=perf18*), "perf([0-9]*)", "Performance-Machine-$1")

vm-perf.JPG

aliasMetric:  To change the displayed metric name to an alternative name, using a search/replace regex, the syntax:  aliasMetric(<tsExpression>, [metric|source|{tagk,<pointTagKey>},"regexSearchPattern", "replacementPattern" ) is used.

For example, to rename the metric, "CPU-Used-VM-11-verylongmetricname" to "CPU-Used-VM-11"; the following regex searches/captures the 1st 14 characters and uses that in the replacement metric: aliasMetric(${Original metric},"(.{0,14}).*", "$1"), (where ${Original metric} is: ts("CPU-Used-VM-11-verylongmetricname")).

 

vm-longmetricname.JPG

taggify: To change the displayed point tags, using a search and replace regex, the syntax:  taggify(<tsExpression>, [metric|source|{tagk,<pointTagKey>},"regexSearchPattern", "replacementPattern" ) is used.

For example, to search and replace the values for point tag "clustername", from "Test-cluster" to "Test_cluster"; use the expression: taggify(${A}, tagk, clustername, clustername, "-", "_") ,

(where variable ${A} is: ts("vsphere.host.cpu.used.summation" and source="esxi-150")).

clustername.JPG

In the above example the taggify search/replace operated on the point tag "clustername". It is also possible to use the search/replace on a point tag and create a new point tag from the results, for example to create a new point tag called "clustertype" using point tag values found in "clustername":

taggify(${B}, tagk, clustername, clustertype, "(.{0,4}).*", "$1"),

(where variable ${B} is: (taggify(${A}, tagk, clustername, clustername, "-", "_")).

clustertype.JPG

Nesting metadata functions

As well as working independently, aliasSource, aliasMetric and taggify can all be nested to provide flexible manipulation of the content displayed on screen in the charts and dashboards. For ease of use, it would be recommended to build a query, then add that query to a new query and so on until desired outcome had been achieved.

For example, consider the metric "~sample.cpu.usage.user.percentage", which has sources db-[0-9] and app[0-9]. If a user wanted to alter the displayed sources in the format of "app-x-production", "db-x-dev" etc and the metric name as "CPU.Usage.Production.User.Percentage", along with some additional point tags like build version:11.3 and abbreviate env point tag the following flow could be implemented. 

A: aliasSource(ts(~sample.cpu.usage.user.percentage), "app-([0-9]*)", "app$1-{{env}}")

B: aliasSource(${A}, "db-([0-9]*)", "db$1-{{env}}")

C: aliasMetric(${B},"CPU.Usage.Production.User.Percentage") 

D: taggify(${C},"Build Version", "11.3") 

E: taggify(${D},tagK,env,env,"(.{0,4}).*", "$1") 

 

Where ts expression A, converts the source names for application machines, app-[0-9] to app-[0-9]-dev, app-[0-9]-production etc.

The expression B, converts the source names for the db machines, db-[0-9] to db-[0-9]-dev, db-[0-9]-production etc.

The expression C, converts the metric name "~sample.cpu.usage.user.percentage" to "CPU.Usage.Production.User.Percentage".

The expression D, adds a "Build Version" point tag of value "11.3"

Finally the expression E, shortens the env point tag to max 4 characters.

nested.JPG

 

For further details and information please see:

 Metadata-functions

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk