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 + Create New in the navigation menu and then select Segmentation from the API Analytics section.

This creates a new Segmentation workspace for you.

Filters

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

For more information about the available filters, see Reference: Analytics Filters.

You can chain multiple filters together by selecting Where and OR.

Filter By Cohorts

You can further refine your segmentation analysis by selecting a user or company cohort from the Performed By list:

This allows you to perform segmentation analysis on specific customer cohorts—for example, new users that have been encountering errors or events for enterprise customers. For example, selecting the cohort NonEnterprise customers will only consider non-enterprise customers in the Segmentation analysis.

Inline Cohorts

Use inline cohorts to define a cohort criteria directly in your Segmentation workspace. This allows you to instantly refine your analysis when you don’t already have an existing cohort to filter by.

To define an inline cohort, select Performed By and then select + Inline User Cohort or + Inline Company Cohort. It opens up a new dialog where you can define a cohort criteria using customer and event filters.

Named Variables for Filters

You can define named variables that hold filter values and then use it across filters.

To add filter variables, select Variables. Then select Add Variables to define a variable. After defining your variables, select Save.

To use a variable, enter the variable name enclosed in double curly braces in a filter value. For example:

You must manually enter the variable name this way to use it. You can quickly check defined variables by hovering over Variables—the tooltip shows the defined variables and their values.

This feature allows you to avoid manually updating filter values in complex and dynamic filtering scenarios.

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 request URI route and company domain. It defines a custom metric to get a breakdown of top users for different endpoints.

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
Maximum available balance for subscriptions
Maximum pending activity for subscriptions

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 and specify how to compute the metric from the field.
Add a custom formula that computes a metric from other metrics.

Add Another Event Field

Select + Add Metric and then select { } Select Field.
Select an event field from the Select a field list—for example, Duration (Milliseconds). Alternatively, write a script that computes the event field.
Select a computation method for the values of the event field. For example, if you’ve selected Duration (Milliseconds), 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
- sum of count avg of count, min of count, max of count (in case of arrays in request or response body, count is number of elements in the array).
- sum of key count, etc. (in case of object in request or response body, key count is number of keys in the object).

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:

Select + Add Metric and then select { } Select Field.
Select <> Scripted Field.
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.

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.

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:

Select + Add Metric and then select Enter Formula.
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:

Bar chart
Line chart
Pie chart
Table

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.

For each metric in the Metrics pane, select … Configuration and Shortcuts to further customize your chart.

Custom Name

Select the Custom Name checkbox to set a custom name for the metric.

Sampling Weights

Select the Weighted checkbox to enable sampling weights for the metric.

This option is enabled by default and Moesif extrapolates the metric using any sampling rules you have defined in Dyanamic Sampling. If you don’t have any dynamic sampling enabled, weighted and unweighted have no difference.

Combo Charts

A combo chart combines line and bar charts. Combo charts allow you to represent multiple metrics in the same chart for better visualization and comparison.

To create a combo chart, open the … Configuration and Shortcuts menu and then select Combo Chart.

Customize Vertical Axis

When you have more than one metric in a chart, you may want to use independent Y-axes for each. Metrics on separate Y-axes can vertically scale independently of one another within the same chart. This proves useful in scenarios such as comparing values at very different scales.

To use a different Y-axis for your metric, open the … Configuration and Shortcuts menu and then select Assign to Y-Axis. The following Y-axis types are available:

Y-Axis A: The default Y-axis.
It’s always on the left side of the chart. If you select a different Y-axis for a metric, the Y-axis appears on the right side. When you select the Log Scale option, it only affects this default Y-axis.
Y-Axis B: Expresses a metric with a decimal ratio as a whole number percentage—for example, 0.5 as 50%. This axis multiplies the values by 100 and adds a percentage sign to the chart units.
Y-Axis C: Adds a new Y-axis on the right side of the chart based on the metric values.
Y-Axis D: Adds a new Y-axis on the right side of the chart based on the metric values.

Duplicate a Metric

Select Duplicate to duplicate the corresponding metric in the same chart.

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.

AI Explain : Use AI to Get Insights About Segmentation Metrics

AI Explain gives you an AI-powered conversational interface where you can ask questions and gain insights about event analytics data.

In a Segmentation workspace, select Ask AI to open up the interface.

To get started, you can choose from the sample prompts. Otherwise, type in your query and press Enter.

Download Chart Data

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

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