SignalFx Developers Guide

union()

union merges one ore more timeseries streams into a single timeseries stream.

Syntax

union(<timeseries>, <timeseries> [, <timeseries>…​])

Each argument must be a timeseries stream. The streams must be aggregated by the same property names, or not aggregated at all. You must specify at least one timeseries name, but the function has no effect if you specify only one.

Table 1. Parameter definitions
Parameter Type Description

timeseries

timeseries stream

A metric timeseries

Returns a timeseries. The return value is the union of all timeseries streams specified in the input arguments.

Throws

invalid argument
  • An argument is not a time series stream

  • Input time series streams are not of the same type (for example, one is numeric and another is boolean)

input grouping error

The input streams are not similarly aggregated.

Use cases

  • Use union function for any computation based on partial results from subsets of the timeseries. Some examples of this type of computation are max, min, sum, count, top and bottom (see the Examples section).

  • union is only required for top and bottom, because you can calculate the others using alternatives. For example, you can directly invoke max and min functions over partially aggregated streams.

  • You can’t use union to calculate the global mean, because the global mean is not the mean of the subset means. Instead, use the following code

1
2
3
total = S1.sum() + S2.sum() +  + Sn.sum()
count = S1.count() + S2.count() +  + Sn.count()
(total / count).publish(global mean)

You can’t make other computations from partial results, either, so you can’t use union. For example, these calculations can’t use union:

  • Percentiles

  • Median (a kind of percentile)

  • Standard deviation

  • Mean plus standard deviation

Stream size limits

SignalFlow computations have a limit on the maximum number of time series that can be processed in a stream. This limit is 5000 timeseries per stream, unless your organization has a different limit configured. The merged stream from the union is also subject to this limit. If the total number of time series across all arguments exceeds the limit, the merged stream is filled to capacity in order of the specified arguments.

Time series identity and uniqueness

If you include a timeseries more than once in the arguments to union() only the first instance of the time series in the argument list is included in the union.

For example, the following program will not work as might be expected:

1
2
3
A = data('jvm.cpu.load', filter=filter('region', 'east')).max(by='aws_instance_type')
B = data('jvm.cpu.load', filter=filter('region', 'west')).max(by='aws_instance_type')
union(A, B).max(by='aws_instance_type').publish('max loads')

If the two regions have common aws instance types, only the corresponding instances from the "east" region are included. Aggregating by region as well as instance type ensures that the identities of the time series are unique. For example:

1
2
3
A = data('jvm.cpu.load', filter=filter('region', 'east')).max(by=['region', 'aws_instance_type'])
B = data('jvm.cpu.load', filter=filter('region', 'west')).max(by=['region', 'aws_instance_type'])
union(A, B).max(by='aws_instance_type').publish('max loads')

Examples

Use the union function to process more timeseries than the stream size limit, by following these steps:

  1. Partition the computation over smaller sub-populations.

  2. Compute aggregations over the partitions.

  3. Merge the aggregations using union.

  4. Calculate the final answer from the merged stream.

For example, to find the top 10 loaded instances across an environment:

1
2
3
4
5
east_top_ten = data('jvm.cpu.load', filter=filter('region', 'east')).top(10)
west_top_ten = data('jvm.cpu.load', filter=filter('region', 'west')).top(10)
north_top_ten = data('jvm.cpu.load', filter=filter('region', 'north')).top(10)
south_top_ten = data('jvm.cpu.load', filter=filter('region', 'south')).top(10)
union(east_top_ten, west_top_ten, north_top_ten, south_top_ten).top(10).publish(global top 10)

© Copyright 2019 SignalFx.

Third-party license information