Topics

Time Series


In This Guide

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.

Time series intro.png
Page hits by month example

Brightspot's Time Series integration 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

A TimeSeries object is a time series associated with an item in your Brightspot project. When using TimeSeries as a standalone integration, you add an entry to the time series when necessary, and then retrieve the aggregated counts to generate a report. (Higher-level integrations 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.

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;

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));
    }

}
  • Declares the variable holding the counter.
  • Retrieves the current object's content ID.
  • Instantiates a time series.
  • 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.
  • Retrieves the counter's value accumulated over the past 10 hours.

The Time Series code example above, 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:


Methods for incrementing and retrieving counters

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.