API Analytics - Time Series Reports

A Time Series analysis allows you to view aggregate trends for your API traffic over a time period. You can use all of your favorite search filters to create a time series chart.

API Time Series chart

To create a Time Series chart in Moesif, you’ll need to navigate to the Events screen and select Time Series from the Chart Type selector.

Time series screen with chart type selector displayed

Defining Filters

Time series screen filters

Filters enable you to filter data by specific properties such as a certain _User Id_or only a particular route of interest. As a filter is created, Moesif will parse through your data to assist in building the query. An example would be if you filtered by URI Route, Moesif would find all of the URI routes within your data and present you with those options to more easily create the filter.

For example, you can filter traffic for a specific route such as GET /items, or even from a specific User Agent such as only including requests from Python clients.

All the filters that work on Live API Log also work for filtering events on Time Series charts as well.

Using Group By

Time series analysis also supports Group By to aggregate the data in your Time Series analysis around a specific property. An example of common Group By clauses include grouping events by Response Status Code or Company Domain.

On the Time Series screen, you can configure which metrics to group by via the Group By input.

Time series screen with group by input

The above example shows us grouping data by Company Domain. You’ll also see that we are displaying the Top 10 terms to limit the data displayed on the chart.

If the chart gets cluttered when plotting many time series, you can select the key name in legend underneath chart to toggle hiding/showing a time series.

Selecting Metric to Plot

By default, time series will plot metrics based on event count. If you want to derive additional metrics, such as plotting the average latency, you can click one of the predefined options under Metrics or create a customized metric to plot.

Time series screen with Metric selection

Available options include being able to plot metrics by:

  • Event Count (default)
  • Event Accumulation
  • Unique Users
  • Unique Companies
  • Unique Sessions/API Keys
  • Avg Latency
  • Max Latency
  • P90 Latency
  • Req Body Count
  • Res Body Count
  • Sum Req Content-Length
  • Custom Metric
  • Custom Formula

You can plot additional metrics on the same chart by clicking the button + Add Metric again.

So we can plot both avg and max duration via the following:

API Time Series Picking Metrics

Creating a Custom Metric

To create a Custom Metric, select the Custom Metric option under the Add Metric dropdown.

Once Custom Metric is selected, select a field that you’d like to use. Available field will display in the dropdown.

Custom Metric select a field

Once the field is selected, you can select the metric to apply against the selected field. Depending on the variables type, certain options may or may not be available.

Custom Metric select a metric

Fields that are numeric type such as Elapsed Time supports average, sum, min, max, distinct, percentiles. Fields that are string types such as HTTP headers supports distinct.

You can also apply a function to the metric as well. This can be done by clicking on the Function dropdown.

Custom Metric add a function

Functions that can be used in the metric plotting include:

  • Rolling Window
    • Returns the metric for X previous windows. For example, use this when you want to see a 7-day rolling window of unique users.
  • Rolling Sum
    • Returns the sum of X previous intervals. For example, use this when you want to see the sum of the 2 previous periods.
  • Rolling Max
    • Returns the rolling maximum value of the metric for each overlapping window
  • Rolling Min
    • Returns the rolling minimum value of the metric for each overlapping window
  • Rolling Unweighted Average
    • Returns the rolling average for each overlapping window. For example, You may use this function to see how your customers; usage is trending vs their trend line. You could use the formula to subtract a customers daily event count from their 7-day rolling average to see how their usage is trending.
  • Rolling Linear Weighted Average
    • Returns the weighted average for each overlapping window where older data points contribute a linearly less amount to the total average.
  • Rolling Standard Deviation
    • Returns the standard deviation of a rolling average for each overlapping window. The averaging function can be either the unweighted average or the linear related average.
  • Exponentially Weighted Rolling Average
    • Returns the single exponential rolling average for each overlapping window where older data points become exponentially less important.
  • Double Exponentially Weighted Rolling Average
    • Returns the double exponential rolling average for each overlapping window where older data points become exponentially less important.

Once the function is selected, you can also specify how many intervals the function should be calculated over.

Custom Metric set interval for function

Lastly, you can also shift the metric as well.

Custom Metric set shift for function

Options for shifting include:

  • None
    • By default, functions do not include the currently interval
  • Shift Forward 1
    • This can be used to include the current interval
  • Shift Forward 2

Once the function is configured as you’d like, click Apply.

Custom Metric apply function

Adding a Custom/Scripted Field

If a field does not exist in your request or response that you’d like to bill upon, you can create the field as a Scripted Field. A Scripted Field has the follow capabilities and limitations:

  • Write a script that retroactively creates a custom field using other fields, formulas, arithmetic, and more.
  • Only numbers, booleans, and dates (treated as a number, milliseconds since epoch) are supported.
  • [field.path.field_name] is a reference to a field
  • If field value does not exists, for numbers it defaults to 0, and for dates it will default to epoch. You can use [field.path.field_name|50] to set default value.
  • Most mathematical functions are supported and if, else, then, end are supported. (detailed docs coming soon).
  • Only expression are supported, no other variables or statements are supported.
  • Scripted fields with body fields may take several minutes to query.

With Custom Metric selected, in the Field selector, select the Scripted Field option.

select a scripted field in Moesif

In the modal that appears, you can input your Scripted Field expression. To add a field from Moesif into the expression, you can select it from the Add a reference to or freely type into the expression field.

scripted field modal in Moesif

Once your expression is input, click the Set button to add the field as a metric.

Creating a Custom Formula

Creating a Custom Formula allows you to use the values from other metrics or segments that you’ve defined. When you select the metrics you want to plot, each is assigned a letter to represent it. This can be used in the formula. You can also refer to Segments in the custom formula as well by using the Segment Name.

To create and plot the results of a Custom Formula, use the Custom Formula option in the Metrics dropdown. Once selected, a text input will appear to create the formula in.

To use the metrics in the formula, simply type the metrics’ assigned letter into your calculation. For example, if you have two metrics you are plotting, denoted as a and b, you can use them in the custom formula like this:

Custom Formula with metric values

To use Segments as part of your formula, use the following syntax:

[SEGMENT_NAME].[METRIC_LETTER]

For example, if you have 2 segments defined, denoted as API and All, you can use them like this:

Custom Formula with Metric Segments

Note that Metrics and Metric Segments can’t be mixed within the same formula.

Changing Chart Style

To change how a Time Series chart is rendered to the screen, you can toggle between different styles. These styles include:

  • Bar
  • Line
  • and Table

To select a chart style, click the option displayed in the top left of the Time Series rendering. This gives users multiple ways to view their data in a Time Series format.

Time series screen with chart style selector displayed

A Line style rending will display a plotted-line chart. This is the default when the page is loaded.

Time series screen with Line chart shown

A Bar style rending will display a bar chart.

Time series screen with Bar chart shown

A Table style rending will display a spreadsheet-style breakdown.

Time series screen with table chart shown

Downloading Data

You can select Download to download a CSV of your time series data. This can be used if you need to create custom charts or want to play with the data more.

API Time Series export data

How Intervals Are Calculated

Moesif will align the intervals to the top and bottom of the interval. So if you select and interval of Daily, then each metric equals the time from 12:00 AM to 11:59pm per day in your chosen timezone.

By default, the browser time is used as the timezone, but you can change your global time zone by going to Apps and Team settings.

Because Moesif always aligns to the calendar interval, the very last one may not be fully complete. For example if the current time is 5:55pm and you select an interval of Daily, then the last interval will only contain partial data from 12:00 AM to 5:55pm.

Updated: