Time Series

Introduction

A time series is a set of data points that associates a quantity with a time or period of time. In web publishing, a typical time series reports the number of page hits per month, bandwidth consumed per month, or average disk space used per month.

../../../_images/time-series.png

Brightspot’s Time Series plugin provides several Java APIs for updating and reporting usage statistics over time. For example, you can use functions to increment hit counts for every generated View, and then retrieve average hit counts over a seven-day period.

Using Time Series

Developers perform theses tasks.

A TimeSeries object is a time series associated with an item in your Brightspot project. When using TimeSeries as a standalone plugin, you add an entry to the time series when necessary, and then retrieve the aggregated counts to generate a report. (Higher-level plugins that use TimeSeries perform these operations for you.)

The following example builds a time series that adds an entry every time Brightspot generates its View, and also returns an updated ten-hour hit count.

Time Series Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
package content.article;

import com.psddev.cms.view.ViewModel;
import com.psddev.cms.view.PageEntryView;
import com.psddev.cms.view.ViewResponse;
import com.psddev.timeseries.TimeSeries;
import com.psddev.timeseries.TimeSeriesValues;
import styleguide.content.article.ArticleView;

import java.util.UUID;

public class ArticleViewModel extends ViewModel<Article> implements ArticleView, PageEntryView {

    private Integer numberViews;

    @Override
    protected void onCreate(ViewResponse response) {
        UUID contentID = model.getId();
        TimeSeries timeSeries = new TimeSeries("pageCounter");
        timeSeries.changeNow(contentID, 1);
        float numberViewsRaw = TimeSeriesValues.ofHours(10, contentID, timeSeries).sum();
        numberViews = new Integer(Math.round(numberViewsRaw));
    }

    /* Other Getters */
}

In the previous snippet—

  • Line 14 declares the variable holding the counter.
  • Line 18 retrieves the current Model’s content ID.
  • Line 19 instantiates a time series.
  • Line 20 adds an entry to the time series for the current content ID. The time for the entry is now, and the value for the entry is 1.
  • Line 21 retrieves the counter’s value accumulated over the past 10 hours.

The following table lists the primary methods for incrementing and retrieving counters in the classes TimeSeries and TimeSeriesValues

Method Description
Class TimeSeries
changeNow(UUID contentId, float amount) Immediately adds an entry to the time series using the specified amount.
change(UUID contentId, long time, float amount) Adds an entry to the time series using the specified time and amount.
Class TimeSeriesValues
TimeSeriesValues ofHours(int hours, UUID contentId, TimeSeries series) Retrieves the specified time series for the past number of hours.
TimeSeriesValues ofDays(int days, UUID contentId, TimeSeries series) Retrieves the specified time series for the past number of days.
TimeSeriesValues ofMonths(int months, UUID contentId, TimeSeries series) Retrieves the specified time series for the past number of months.
TimeSeriesValues ofYears(int years, UUID contentId, TimeSeries series) Retrieves the specified time series for the past number of years.
float sum() Returns the time series’s sum. Useful for reporting hit counts.
float min() Returns the time series’s minimum. Useful for identifying low-utilization hours or days.
float max() Returns the time series’s maximum. Useful for identifying peak hours or days.
float average() Returns the time series’s average.

The snippet Time Series Example implemented a time series for page views. You can have several time series for a given content ID, such as one for page views and another for click-throughs.

UUID contentID = model.getId();
TimeSeries pageViews = new TimeSeries("pageViews");
TimeSeries clickThroughs = new TimeSeries("clickThroughs");

/* Adds entry to the content's page-view time series. */
pageViews.changeNow(contentID, 1);

/* Adds entry to the content's click-through time series. */
clickThroughs.changeNow(contentID, 1);

See also: