Heatmap Reports

This document explains how to use Geo Heatmap in the Moesif’s API Analytics suite.

Overview

A heatmap visualizes frequency of data at geographic locations using a range of different colors. Heatmaps are a great way to understand your product, its users, and how both correlate when geographic location is an important part of your analytics requirements.

Moesif’s Geo Heatmap supports supports GeoJSON and the full range of filters available in other metric types such as Live Event Log, Time Series, and Segmentation.

Use Cases and Benefits

If your product has a large customer base spread across different regions, Moesif’s Geo Heatmap can help you quickly pinpoint regional issues.

For example, the following heatmap filters by the number of declined transactions globally.

The heatmap shows a large portion of 401 Unauthorized response status codes coming from the Eastern US. The aggregate stats get updated as you apply more filters. In this case, the majority of 401 Unauthorized status codes come from the /availabilities endpoint.

Heatmaps use color coding to illustrate the intensity profile of data. The use of different colors to communicate metrics makes heatmaps easier to consume. Use of colors also helps distinguish between different states rather than raw numbers. The simple but powerfully multifaceted nature of heatmaps makes them a potent analysis tool in various situations. .

Create a Geo Heatmap

To create a geo heatmapt, select + New in the navigation menu and then select Geo Heatmap from the API Analytics section.

Filters

You can refine a heatmap 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 plot heatmaps only for users or companies who’ve made their first API call within the time period you specify.

Use GeoJSON

Instead of using IP addresses to plot heatmaps, you can use GeoJSON-formatted shapes from API body fields or request query parameters. Select Select a GeoJSON Field to get started.

Configure Metrics and Chart

Moesif Geo Heatmap offers different ways to specify, configure, and visualize heatmaps.

Select the Metrics to Plot

By default, Geo Heatmap plots only the Event Count metric. A heatmap can contain only one metric at a time.

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.

Create Custom Metric

To create a custom metric for the heatmap, follow these steps:

Select + Event Count 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 + Event Count 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.

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.

Moesif gives you several options to share a Geo Heatmaps 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.