SignalFx Developers Guide

dimensions()

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

The output from dimensions() is the input stream with the specified dimensions either cloned or renamed, or both. dimensions() only returns timeseries that include the cloned or renamed dimensions, so any timeseries that doesn’t have these dimensions aren’t in the output.

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 dimension with the specified key and the same value as the cloned dimension.

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.

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 a data 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 a data 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 data 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 the input data stream with cloned or renamed dimensions, or both. dimensions() ignores dimensions that that don’t exist in the input.

  • If allow_missing= is omitted or set to False, dimensions() returns a data stream that clones or renames dimensions, but only if all of 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.

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
data('cpu.load').dimensions(aliases={'server':'host', 'node':'server'}).publish()

#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()

Notes

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.

dimensions() only returns timeseries that include the aliased or renamed dimensions, so any timeseries that doesn’t have these dimensions aren’t in the output. For example, if you want to rename "host" to "server", a time series that doesn’t have the "host" dimension won’t be in the output stream.

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:

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

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

To rename the dimension project to both service and team:

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

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

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

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():

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

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

© Copyright 2020 Splunk, Inc.

Third-party license information