TimeseriesParams

Parameters that control how we construct the time series for each slice.

JSON representation
{
  "forecastHistory": string,
  "granularity": string,
  "metricAggregationMethod": enum (AggregationMethod),
  "minDensity": number,
  "metric": string
}
Fields
forecastHistory

string (Duration format)

Required. How long should we go in the past when fetching the timeline used for forecasting each slice.

This is used in combination with the detectionTime parameter. The time series we construct will have the following time range: [detectionTime - forecastHistory, detectionTime + granularity].

The forecast history might be rounded up, so that a multiple of granularity is used to process the query.

NOTE: Make sure there are enough events in the data set to cover the time interval: if the detectionTime is set to T, the data set should have enough events from "T - forecastHistory" to allow forecasting and anomaly detection. If too few events are found in this range, no anomaly will be reported. Users can use [datasets.evaluateSlice][datasets.evaluateSlice] to check the (approximate) count of events for each point of time in the range, by not setting metric.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

granularity

string (Duration format)

Required. The time granularity of the time series (on the x-axis). Each time series point starting at time T will aggregate all events for a particular slice in [T, T + granularity) time windows.

NOTE: The aggregation is decided based on the metric parameter.

This granularity defines the query-time aggregation windows and is not necessarily related to any event time granularity in the raw data (though we do recommend that the query-time granularity is not finer than the ingestion-time one).

Currently, the minimal supported granularity is 10 seconds.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

metricAggregationMethod

enum (AggregationMethod)

Optional. Together with the metric field, specifies how we will aggregate multiple events to obtain the value of a time series point. See the metric documentation for more details.

If the metric is not specified or "", then this field will be ignored.

minDensity

number

Optional. Minimum density percentage of the input time series for it to be evaluated.

Must be in the [0, 100] range.

If unsure, leave this unset.

metric

string

Optional. Denotes the name of a numerical dimension that will have its values aggregated to compute the y-axis of the time series.

The aggregation method must also be specified by setting the [metricAggregationMethod][TimeseriesParams.metricAggregationMethod] field.

Note: Currently, if the aggregation method is unspecified, we will default to SUM for backwards compatibility reasons, but new implementations should set the [metricAggregationMethod][TimeseriesParams.metricAggregationMethod] explicitly.

If the metric is unspecified, we will use the number of events that each time series point contains as the point value.

Example: Let's assume we have the following three events in our data set:

{
  eventTime: "2020-12-27T00:00:00Z",
  dimensions: [
    { name: "d1" stringVal: "v1" },
    { name: "d2" stringVal: "v2" }
    { name: "m1" longVal: 100 }
    { name: "m2" longVal: 11 }
  ]
},
{
  eventTime: "2020-12-27T00:10:00Z",
  dimensions: [
    { name: "d1" stringVal: "v1" },
    { name: "d2" stringVal: "v2" }
    { name: "m1" longVal: 200 }
    { name: "m2" longVal: 22 }
  ]
},
{
  eventTime: "2020-12-27T00:20:00Z",
  dimensions: [
    { name: "d1" stringVal: "v1" },
    { name: "d2" stringVal: "v2" }
    { name: "m1" longVal: 300 }
    { name: "m2" longVal: 33 }
  ]
}

These events are all within the same hour, spaced 10 minutes between each of them. Assuming our QueryDataSetRequest had set slicingParams.dimensionNames to ["d1", "d2"] and timeseriesParams.granularity to "3600s", then all the previous events will be aggregated into the same timeseries point.

The time series point which they are all part of will have the time set to "2020-12-27T00:00:00Z" and the value populated based on this metric field:

  • If the metric is set to "m1" and metricAggregationMethod to SUM, then the value of the point will be 600.
  • If the metric is set to "m2" and metricAggregationMethod to SUM, then the value of the point will be 66.
  • If the metric is set to "m1" and metricAggregationMethod to AVERAGE, then the value of the point will be 200.
  • If the metric is set to "m2" and metricAggregationMethod to AVERAGE, then the value of the point will be 22.
  • If the metric field is "" or unspecified, then the value of the point will be 3, as we will simply count the events.

AggregationMethod

Methods by which we can aggregate multiple events by a given metric.

Enums
AGGREGATION_METHOD_UNSPECIFIED Unspecified.
SUM Aggregate multiple events by summing up the values found in the metric dimension.
AVERAGE Aggregate multiple events by averaging out the values found in the metric dimension.