---
title: "Analytics"
canonical_url: https://developer.repebble.com/pebbleos/docs/subsystems/analytics/
last_updated: 2026-11-09
sdk_version: 4.44
---
# Analytics

Source: https://developer.repebble.com/pebbleos/docs/subsystems/analytics/

`subsys/analytics/` collects firmware metrics into hourly heartbeats. Its public API is `include/pbl/analytics/analytics.h`. `CONFIG_ANALYTICS` enables it in normal firmware; recovery firmware has no data logging and leaves it out, which compiles the macros below to nothing beyond evaluating their values.

## Metrics

Metrics are declared in `include/pbl/analytics/analytics.def` as unsigned, signed, scaled, timer or string metrics, and updated by name from anywhere, apps included, since the functions behind the macros are syscalls:

```
PBL\_ANALYTICS\_ADD(button\_pressed\_count, 1);PBL\_ANALYTICS\_TIMER\_START(backlight\_on\_time\_ms);PBL\_ANALYTICS\_TIMER\_STOP(backlight\_on\_time\_ms);
```

## Collectors

A metric that is only worth computing once per period comes from a collector: a function next to the state it reads, called on the system task right before each heartbeat. Collectors are gathered at link time, so analytics does not know about them and a firmware without the code has no collector to stub:

```
static void prv\_collect\_pfs\_stats(void) {PBL\_ANALYTICS\_SET\_UNSIGNED(pfs\_space\_free\_kb, get\_available\_pfs\_space() / 1024);}PBL\_ANALYTICS\_COLLECTOR\_DEFINE(prv\_collect\_pfs\_stats);
```

They run in no particular order, so a collector must not depend on another.

## Heartbeats

The native backend, `subsys/analytics/native.c`, keeps the current values. Each heartbeat it writes them as one packed record to a data logging session, which sends it to the phone, and resets them for the next period. Running timers keep running across heartbeats.

The record’s layout follows `analytics.def`, and it carries the firmware’s build ID. `tools/analytics_heartbeat_layout.py` extracts the layout from the matching ELF file, for parsers.

## Shell

| 

Command

 | 

Description

 |
| --- | --- |
| 

`analytics heartbeat`

 | 

Collect and log a heartbeat now

 |
| 

`analytics metrics`

 | 

Dump the current metrics

 |

Generated from PebbleOS [88634f016](https://github.com/coredevices/pebbleos/commit/88634f01610250b37c84b609c00ee2be8518a393). This page is maintained in the pebbleos repository: [docs/subsystems/analytics.md](https://github.com/coredevices/pebbleos/blob/88634f01610250b37c84b609c00ee2be8518a393/docs/subsystems/analytics.md).