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.

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.

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.

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 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, Elapsed Duration. 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 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:

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.

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.