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 MTS that include the cloned or renamed dimensions, so any MTS that doesn’t have these dimensions aren’t in the output.

 Syntax

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

 Parameter definitions

 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:

• An <alias_map> or <rename_map> that contains either a key or value that isn't a string
• A key in either map that’s also a value in one of the maps.

 Error examples

#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

SignalFlow 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 MTS that include the aliased or renamed dimensions, so an MTS that doesn’t have these dimensions isn't in the output. For example, if you want to rename "host" to "server", an MTS 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.