Getting started with Cohort Analysis

How to write queries on your data, and build metrics and KPIs


Cohort Analysis is DevicePilot's query engine that allows you to understand your telemetry data. It will allow you define Uptime % KPIs, break out fault codes by firmware revision, and show trends of user interaction over time.

First however, some basics. A KPI is made up of several elements

  • Metric
  • Grouping
  • Filter

Let's get started with the simplest example - we'll count the number of messages stored. This tutorial assumes you have devices posting into your account.


Metrics are the first part of a KPI - you use them to define what you care about so you can measure it.

Counting messages

Head to the Cohort page, and in the Metric section, choose Count of $id:


Ensure the time Click Run KPI and see your results, which will be something like


What does this mean? $id is set on every message we receive (it's the unique Id of the device), so by counting them, we see how messages there are.

Counting Devices

What if we wanted to know how many different devices we had? We just change the Metric to Count distinct values of and run again.


You'll now see the number of unique device that have posted a message.

For a complete list of metrics, see What Metrics can I measure with Cohort.


In order to understand our device estate better, we can group the Metrics by different dimensions.

For instance, if we group by time to see how our metric changes through the day:


then we'll see how the number of unique devices changes hour by hour:


Scope Filter

Use the scoping filter at the bottom to limit your query to a subset of devices. Like everything else in Cohort, this is much more powerful than it first appears because instead of selecting devices based on their current state, it is actively selecting which devices to include in the analysis moment by moment throughout the analysis timespan.


  • At any moment in time some of your devices may not be deployed - perhaps because they're R&D devices, or are sitting waiting to be deployed. You probably don't want to include them in an "uptime" metric. So set the scope filter to "deployed=true". If your query spans a month and a device gets deployed half way through that month, it will only be measured for the time that it was actually deployed.
  • You may want to Scope to limit your analysis to a particular software version. For example, you might want to measure reliability of just v0.3 software. However software version is a property which changes occasionally as a device gets upgraded, in a somewhat irregular way (devices won't all be upgraded at the same time). So set your scope to "software_version='v0.3'" and it will select only the devices and only the times when a device was running v0.3.