Segmentation Reports

This document explains how to use Segmentation metrics in the Moesif’s API Analytics suite.

Overview

Segmentation allows you to analyze your API data and divide it into segments. Each segment contains similar data based on specific criteria. This is similar to the SQL GROUP BY statement.

Use Cases and Benefits

Moesif’s Segmentation offers you a powerful way to find meaningful and useful categories in your API data. Being able to group and categorize your product usage based on different criteria helps identify different kinds of customers and usage patterns. This allows your teams to tailor communication, outreach, and customer support strategies to different audiences. For example, say you roll out a new version of your API. You can keep an eye on the usage of different versions to better strategize deprecating the older version.

Create Segmentation Chart

To create a Segmentation chart, select + New in the navigation menu and then select Segmentation from the API Analytics section.

Creating new Segmentation chart

This creates a new Segmentation workspace for you.

Filters

You can refine a time-series chart using filters. To access the filters, select the Select field list in the Filters pane.

Accessing filters in a Segmentation chart

For more information about the available filters in Live Event Log, see Reference: Analytics Filters.

You can chain multiple filters together by selecting Where and OR. You can further refine your search by selecting a user or company cohort from the Performed By list.

Include Data of New Users and Companies Only

To take only new users and companies into consideration, enable the New Users Only and New Companies Only filters respectively. These two filters allow you to perform segmentation analysis only for users or companies who’ve made their first API call within the time period you specify.

Group Data

Moesif Segmentation charts support grouping data by categories. Use the Group By option to group data by a specific criteria. You can group by HTTP response status code, company domain, or user ID. For example, the following Segmentation chart groups by company domain and response body label and selects Event Count as the metric. This lets us understand the most common response body label for each customer.

Example of using the 'Group By' option in a Segmentation chart

Segment Data

If you want to use your own criteria to segment data by custom groups, use the Segmentation option.

For example, to segment by country, select + Segment and then select Request.GeoIP.Country from the Select Field list.

After selecting + Segment, Moesif generates a unique name for the segment that you can change—for example, segmentcd635fbb. You can reference this name when you define a custom metric formula.

Configure Metrics and Chart

Moesif Segmentation offers different ways to specify, configure, and visualize metrics.

Select the Metrics to Plot

By default, Segmentation plots only the Event Count metric. You can always plot more than one metric in the same chart by selecting + Add Metric.

The following predefined metrics are available:

  • Event count
  • Event accumulation
  • Unique users
  • Unique companies
  • Unique sessions or API keys
  • Average latency
  • Maximum latency
  • P90 latency
  • Request body count
  • Response body count

You can also add custom metrics by selecting a new event field or specifying a custom formula that references other metrics.

Create Custom Metric

You can create custom metrics in two ways:

Add Another Event Field

  1. Select + Add Metric and then select { } Select Field. Add custom metric by selecting a custom field in a Segmentation chart
  2. Select an event field from the Select a field list—for example, Elapsed Duration. Alternatively, write a script that computes the event field.
  3. Select a computation method for the values of the event field. For example, if you’ve selected Elapsed Duration, you can select avg to display the average elapsed duration of API requests over time.

    The computation methods available depend on the data type of the event field. For example, numeric types have the following computation methods available:

    • sum
    • avg
    • min
    • max
    • accumulate
    • percentile
    • distinct
Add a Scripted Field

If a field does not exist in your request or response, you can compute the field using a script. The script retroactively creates a custom field from other fields, using formulas, arithmetic, and conditional expressions. A scripted field has the following capabilities and limitations:

  • Only numbers, booleans, and datetime data types (treated as a number, milliseconds since epoch) are supported.
  • [field.path.field_name] references a field.
  • If field value does not exist, for numbers it defaults to 0, and for dates it defaults to the epoch. You can use [field.path.field_name|50] to set the default value.
  • Most mathematical functions are supported. Conditional expressions using if, else, then, and end operators are supported.
  • Only expressions are supported. No other variables or statements are supported. Scripted fields with body fields may take several minutes to query.

To add a scripted field, follow these steps:

  1. Select + Add Metric and then select { } Select Field. Add custom metric by selecting a custom field in a Segmentation chart
  2. Select <> Scripted Field. Add a scripted field in a Segmentation chart
  3. Write the script and then select Set. The field list following the script text box contains all the existing fields so that you can easily reference them in your script. Scripted field dialog

Add a Custom Formula

Moesif allows you to create a custom arithmetic formula to use the values from other metrics or segments that you’ve defined. Moesif assigns a unique letter to each metric you plot. You can then reference those letters to build an arithmetic expression that computes a custom metric. You can also refer to segments in the custom formula as well by using the segment name.

The following example defines the custom metric formula a/b where a corresponds to an Event Count metric and b corresponds to a Unique Users metric.

A custom formula example in a Segmentation chart

To use segments as part of your formula, use the syntax SEGMENT_NAME.METRIC_LETTER. For example, if you have two segments API and All, and a metric a, you can define the formula (API.a/All.a)*100.

To add a custom formula and plot its metric, follow these steps:

  1. Select + Add Metric and then select Enter Formula. Creating a custom formula in a Segmentation chart
  2. Enter your formula. The following operators are supported for a formula:
    • Addition (+)
    • Subtraction (-)
    • Division (/)
    • Multiplication (*)
    • Exponentiation (^)
    • Square root (sqrt)
    • Natural logarithm (ln, log)
    • Base-10 or common logarithm (log10)
    • Base-2 or binary logarithm (log2)

Change Chart Style

You can change how Moesif plots segmentation charts and toggle from one style to another. This allows you to view the metrics in multiple ways.

The following styles are available:

Selecting chart style for a Segmentation chart

Bar Chart

A bar chart represents data with rectangular bars. The height of each bar corresponds to a quantity of the metric data and each bar belongs to a category. The categories come from the grouping you specify and each bar represents a single category. For example, if you plot the Event Count metric in a bar chart for the past 12 weeks and group the data by URI routes , each bar represents data for a URI route. The height of each bar changes in proportion to the number of events associated with a URI route.

Line Chart

A line chart plots your metrics by connecting the data points with lines. Each data point represents a value of the metric at a specific time period. Line charts help you visualize and understand how metrics change over time.

Pie Chart

Pie chart uses a circular graph to represent how a total amount of your data is divided into categories. Each radial portion of the chart corresponds to the amount that belongs to a category. Pie charts help you visualize how each category or group contributes to the entirety of your data. For example, a pie chart can help you visualize how your customers are using your products across different countries and regions.

Table

The table view shows the metrics data in a tabular format, similar to a spreadsheet.

Save and Share

Moesif gives you several options to share a Segmentation workspace. Before you can share, you must first save the workspace to a dashboard.

After saving, follow the instructions in Sharing Workspaces to share your workspace.

Download Chart Data

You can download your Segmentation chart data in CSV format for further processing in tools like Microsoft Excel:

  1. Select Export.
  2. Select Download Chart - Current View or Download Chart - All Terms.

Updated: