Time Windows

A time window is defined as a range of time covering the boundaries of a specific time to a specific time dimension. For example, [2015-01-01T00:30:00.000Z, 2015-01-01T00:31:00.000Z] would be a time window of January 1, 2015 at 12:30 A.M.

Abacus uses time windows in its report data to provide the clients with info about the usage in several dimensions. These time windows use UTC time with the dimensions of a second, minute, hour, day, and month.

The windows structure is an array of arrays. The outer array is always five elements that stand for the dimensions for which the usage would be accumulated.

The inner array of each of these dimensions is in the format of:

[
  current time in the dimension unit,
  current time in the dimension unit - 1 dimension unit,
  ...,
  current time in the dimension unit - N dimension units
]

If the windows was pulled from January 31st, then the object will look like the one below:

[
  [31],
  [1, 1, 1, 1, 1],
  [null],
  [null],
  [null],
]

A conceptual representation as a JSON of the above object may look like:

{
  "Second": {},
  "Minute": {},
  "Hour": {},
  "Day": {
    "0": 1,
    "-1": 1,
    "-2": 1,
    "-3": 1,
    "-4": 1
  },
  "Month": {
    "0": 31
  }
}

Note: The structure above does not exist, it is used to make things easier to explain. Abacus provides a few helpful functions in the timewindow module.

In the month dimension, we have a quantity of 31 for the whole month of January. In the day usage, we have a quantity of 1 for the day of January 31st, 30th, 29th, 28th, and 27th. A null means that there is no quantity in that particular time.

The purpose of keeping track of the previous days is to allow a submission of usage up to several days late. When usage is retrieved, it has a processed time in milliseconds. Those previous indices are saying "I know of all this usage at the processed time". If Abacus allows submission up to 5 days late, the date when a Report Consumer can get the most up-to-date data for the whole month of January is February 4th.

Note: Abacus supports only months and day windows. The seconds, minutes and hours windows are disabled and left for backward compatibility. That's why they'll always contain null.

Example: Charting usage

If our x-axis is the time dimension, we may want to consider to what granularity we want to show our data. Is it quantity over an entire month? If so, we would want to use the values from the month dimension. The same applies for any other dimensions.

If we want to chart the monthly quantity of a particular resource that submits every 4 hours. Given that we have roughly 6 submissions a day, and there are 31 days in July, that makes around 186 submissions for the month of July for this example.

We'll get events like:

{
  ...
  "processed": 1467331200000,
  "windows": [[1], [null], [null], [null], [null]]
  ...
}

We can chart the processed time as the x-axis, and the y-axis would take the current month value.

If we assume that with each submission, the quantity for the month is incremented by 1, this would give a linear chart of 186 points where:

• the 1st point has an x-axis of value 1467331200000 and y-axis of value 1
• the last point has an x-axis value of 1470009600000 and y-axis value of 186