SignalFx Developers Guide

dimensions()

dimensions() clones or renames dimensions in an MTS input stream.

Operation

Scope

The dimensions() method scope is local:

  • dimensions() creates an MTS output stream that contains the aliased or renamed dimensions, but these aliases and renames are only visible in this specific stream. They aren’t visible to other computations that don’t consume the dimensions() output, even if the computations are in the same SignalFlow program.

  • dimensions() aliases and renames aren’t visible outside the chart in which they’re created. In particular, they’re not visible to other charts in the same dashboard.

  • dimensions() aliases and renames aren’t visible outside the detector in which they’re created.

To learn more about the scope of dimensions(), see the section Scope example.

Input processing

dimensions() doesn’t pass through MTS that aren’t specified in its parameters. If an MTS in the dimensions() input stream doesn’t contain the dimension names you’re aliasing or renaming, dimensions() drops it from the MTS output stream.

When you set allow_missing='true', dimensions() ignores attempts to alias or rename a dimension that doesn’t exist in the input MTS. If this occurs, dimensions() doesn’t provide any indication that it happened.

When you set allow_missing='false', all the dimension aliases and renames must exist in the input; otherwise, dimensions() returns an empty stream.

Syntax

dimensions([aliases=alias_map][, renames=renames_map][, allow_missing=allow_missing_flag])

Table 1. Parameter definitions
Parameter Type Description

alias_map

Map of string key-value pairs. Default is None.

Optional:

  • Format is {"<new_key>":"<cloned_key>", … }

  • <new_key> is a new dimension key name.

  • <cloned_key> is an existing dimension key name to clone.

For each pair, the result is a new alias with the specified key and the same value as the cloned dimension. The original dimension name still exists.

renames

Map of string key-value pairs. Default is None.

Optional:

  • Format is {"<new_dimension_name>":"<existing_dimension_name>", …}

  • <new_dimension_name> is a new dimension key name.

  • <existing_dimension_name> is an existing dimension key name that you want to rename. The original dimension name is deleted.

For each pair, the result is the existing dimension value with the specified new name.

allow_missing=allow_missing_flag

Python boolean
(True or False)

Optional:

  • True: dimensions() returns an MTS output stream that clones or or renames existing dimensions in the input. If you specify a dimension key that doesn’t exist in the input, dimensions() ignores it.

  • False: dimensions() returns an MTS output stream that clones or renames dimensions, but only if all of the specified dimension keys exist in the input. If you specify a dimension key that doesn’t exist in the input, dimensions() returns an empty MTS output stream.

Default is False.

Considerations

  • You must specify either aliases= or renames=.

  • The arguments must be maps in which both the key and the value are strings.

  • allow_missing= is optional, and defaults to False.

aliases=alias_map adds new dimension key names but doesn’t change existing ones, while the renames=rename_map argument replaces existing dimension keys with new names.

Return value

  • If allow_missing= is True, returns an output MTS stream with cloned or renamed dimensions, or both. dimensions() ignores dimensions that don’t exist in the input.

  • If allow_missing= is omitted or set to False, dimensions() returns an MTS data stream that clones or renames dimensions, but only if all the dimensions exist. If one or more don’t exist, dimensions() returns an empty data stream.

Errors

The following cause errors:

  • alias_map or rename_map value that isn’t a map in which both keys and values are strings

  • A key in either map that’s also a value in one of the maps.

Error examples

1
2
3
4
5
6
7
#counter example: this is an error, because you can't make server an alias to host and node an alias to server
#at the same time
"A=data('cpu.load').dimensions(aliases={'server':'host', 'node':'server'}).publish(label='A');"

#counter example: this is an error, because you create an alias to server and then rename node to server at the
#same time
`"data('cpu.load').dimensions(aliases={'server':'host'}, renames={'node':'server'}).publish()"`

Usage

SignalFx provides the dimensions() method so you can repair misnamed dimensions in place. For this reason, you usually use the renames argument.

You should assume that the aliasing and renaming occur simultaneously, so that none of the key-value pairs in the maps affect any of the others. This lets you alias or rename an existing dimension to multiple new dimensions.

Examples

Rename a dimension

If you want to publish an MTS with a server dimension but misreported the original MTS using host as the dimension name, use dimensions() to fix the problem:

"A=data('cpu.load').dimensions(renames={'server':'host'}, allow_missing=True).publish(label='A');"

In the publish() output stream, the metric cpu.load now has the dimension server.

To rename the dimension project to both service and team:

"A=data('cpu.load').dimensions(renames={'service':'project', 'team':'project'}, allow_missing=True).publish(label='A');"

If project isn’t a dimension in the input stream, and you set allow_missing=False, then the following SignalFlow publishes an empty stream:

"A=data('cpu.load').dimensions(renames={'service':'project', 'team':'project'}, allow_missing=False).publish(label='A')"

Alias a dimension

You can provide an alias to a dimension instead of renaming it. For example, you can assign to aliases to the host dimension, using dimensions():

"A=data('cpu.load').dimensions(aliases={'server':'host', 'server':'hostmachine'}, allow_missing=True).publish(label='A');"

In the publish() output stream, the metric cpu.load still has the dimension host, but you can refer to it using the aliases server and hostmachine.

Scope example

The following example demonstrates the focused scope of the dimensions() method.

Consider the following SignalFlow chart program:

1
2
"stream1 = data('cpu.usage.total', filter=filter('kubernetes_node', 'node5'), allow_missing=True).dimensions(aliases={'mynode':'kubernetes_node'}).publish('stream1');
stream2 = data('cpu.usage.total', filter=filter('mynode', 'node6'), allow_missing=True).publish('stream2');"

The first SignalFlow statement does the following:

  1. The data() function applies the filter kubernetes_node = node5 to the metric input stream cpu.usage.total. If incoming datapoints for cpu.usage.total also have the dimension kubernetes_node:node5, the data() function produces an output MTS stream.

  2. The dimensions() method ingests the MTS stream from data() and modifies it by assigning the alias mynode to the dimension kubernetes_node. The dimensions() call assumes that mynode isn’t an existing dimension. The result is an output MTS stream.

  3. The publish() method produces an output MTS stream with a reference stored in the variable stream1.

The second SignalFlow statement produces an empty MTS output stream because the filter() function doesn’t recognize mynode as a dimension. mynode is a dimension alias in the first statement, but its scope is limited to the first statement. In the second statement, filter() incorrectly assumes that mynode is an actual dimension name in the incoming metric stream.

© Copyright 2020 Splunk, Inc.

Third-party license information