Segmentation Reports

Segmentation allows you to analyze your API data into segments to find top X or bottom X. This is similar to GROUP BY in the SQL universe.

For example, to see who are the top customers of my API, we can group by “Company Domain” and select the metrics “Event Count”

Segmenting API Usage By Company

Moesif supports segmenting on any number of API and user/company filters. For example, we can expand on the first example to understand what is the most common response body label for each customer. To do this, we add a second group by for Response.Body.Label

Segmenting API calls

Using Custom Metadata

Besides the Moesif predefined fields, you can filter and group by any custom field set in the the event metadata or user metadata. You can also group by arbitrary request or response HTTP headers.

Types of Segmentation

So far we selected to show Top X Terms, but Moesif can perform a variety of segmentation on different types such as numeric histograms, date histograms and more.

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 or function to plot.

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.

Creating a Custom Metric

To create a Custom Metric, select the Custom Metric option under the Metrics 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 segment 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 expressions 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.

Updated: