Analytics

Firmware metrics collected into periodic heartbeats. More...

Modules
	Analytics backends
	Interface implemented by analytics backends.

Data Structures
struct	pbl_analytics_collector
	A function that refreshes metrics right before each heartbeat. More...

Macros
#define	PBL_ANALYTICS_KEY(key_name)   PBL_ANALYTICS_KEY__##key_name
	Key of a metric declared in analytics.def.
#define	PBL_ANALYTICS_SET_SIGNED(key_name, signed_value)   ((void)(signed_value))
#define	PBL_ANALYTICS_SET_UNSIGNED(key_name, unsigned_value)   ((void)(unsigned_value))
#define	PBL_ANALYTICS_SET_STRING(key_name, value)   ((void)(value))
#define	PBL_ANALYTICS_TIMER_START(key_name)   ((void)0)
#define	PBL_ANALYTICS_TIMER_STOP(key_name)   ((void)0)
#define	PBL_ANALYTICS_ADD(key_name, amount)   ((void)(amount))
#define	PBL_ANALYTICS_COLLECTOR_DEFINE(_collect)

Enumerations
enum	pbl_analytics_key { PBL_ANALYTICS_KEY_COUNT }
	Metric keys, one per entry in analytics.def. More...
enum	pbl_analytics_drv_init_fail_flag { PBL_ANALYTICS_DRV_INIT_FAIL_HRM = 1U << 0U }
	Bits of the drv_init_fail_flags metric. More...

Functions
void	pbl_analytics_init (void)
	Initialize the backends and start the hourly heartbeat timer.
void	sys_pbl_analytics_set_signed (enum pbl_analytics_key key, int32_t signed_value)
	Set a signed metric.
void	sys_pbl_analytics_set_unsigned (enum pbl_analytics_key key, uint32_t unsigned_value)
	Set an unsigned metric.
void	sys_pbl_analytics_set_string (enum pbl_analytics_key key, const char *value)
	Set a string metric.
void	sys_pbl_analytics_timer_start (enum pbl_analytics_key key)
	Start a timer metric.
void	sys_pbl_analytics_timer_stop (enum pbl_analytics_key key)
	Stop a timer metric, adding the elapsed time in milliseconds to it.
void	sys_pbl_analytics_add (enum pbl_analytics_key key, int32_t amount)
	Add to an integer metric.

Detailed Description

Firmware metrics collected into periodic heartbeats.

Metrics are declared in analytics.def as unsigned, signed, scaled, timer or string metrics. Values accumulate over a heartbeat period (one hour) and are then handed to the analytics backends, which log them and reset them for the next period. Running timers keep running across heartbeats. Without CONFIG_ANALYTICS the macros only evaluate their value.

The functions are syscalls, so they may be used from apps as well as from the kernel. Keys out of range are ignored.

Metrics that are only worth computing once per period are refreshed by a collector, which runs right before each heartbeat on the system task.

PBL_ANALYTICS_ADD(button_pressed_count, 1);
 
PBL_ANALYTICS_TIMER_START(backlight_on_time_ms);
...
PBL_ANALYTICS_TIMER_STOP(backlight_on_time_ms);
 
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);

Macro Definition Documentation

PBL_ANALYTICS_ADD

#define PBL_ANALYTICS_ADD	(		key_name,
			amount
	)		((void)(amount))

PBL_ANALYTICS_COLLECTOR_DEFINE

#define PBL_ANALYTICS_COLLECTOR_DEFINE

(

_collect

)

Value:

  [[maybe_unused]] static const struct pbl_analytics_collector \
      pbl_analytics_collector_##_collect = {.collect = (_collect)}

PBL_ANALYTICS_KEY

#define PBL_ANALYTICS_KEY

(

key_name

)

PBL_ANALYTICS_KEY__##key_name

Key of a metric declared in analytics.def.

Parameters

key_name

Metric name.

PBL_ANALYTICS_SET_SIGNED

#define PBL_ANALYTICS_SET_SIGNED	(		key_name,
			signed_value
	)		((void)(signed_value))

PBL_ANALYTICS_SET_STRING

#define PBL_ANALYTICS_SET_STRING	(		key_name,
			value
	)		((void)(value))

PBL_ANALYTICS_SET_UNSIGNED

#define PBL_ANALYTICS_SET_UNSIGNED	(		key_name,
			unsigned_value
	)		((void)(unsigned_value))

PBL_ANALYTICS_TIMER_START

#define PBL_ANALYTICS_TIMER_START

(

key_name

)

((void)0)

PBL_ANALYTICS_TIMER_STOP

#define PBL_ANALYTICS_TIMER_STOP

(

key_name

)

((void)0)

Enumeration Type Documentation

pbl_analytics_drv_init_fail_flag

enum pbl_analytics_drv_init_fail_flag

Bits of the drv_init_fail_flags metric.

Only the first heartbeat after boot carries them.

Enumerator
PBL_ANALYTICS_DRV_INIT_FAIL_HRM	The heart rate monitor driver failed to initialize.

pbl_analytics_key

enum pbl_analytics_key

Metric keys, one per entry in analytics.def.

Enumerator
PBL_ANALYTICS_KEY_COUNT	Number of metric keys.

Function Documentation

pbl_analytics_init()

void pbl_analytics_init

(

void

)

Initialize the backends and start the hourly heartbeat timer.

sys_pbl_analytics_add()

void sys_pbl_analytics_add	(	enum pbl_analytics_key	key,
		int32_t	amount
	)

Add to an integer metric.

Parameters

key	Metric key.
amount	Amount to add, may be negative.

sys_pbl_analytics_set_signed()

void sys_pbl_analytics_set_signed	(	enum pbl_analytics_key	key,
		int32_t	signed_value
	)

Set a signed metric.

Parameters

key	Metric key.
signed_value	New value.

sys_pbl_analytics_set_string()

void sys_pbl_analytics_set_string	(	enum pbl_analytics_key	key,
		const char *	value
	)

Set a string metric.

The string is copied and truncated to the length declared for the metric. Strings passed from an app must lie in the app's memory region.

Parameters

key	Metric key.
value	NUL-terminated string.

sys_pbl_analytics_set_unsigned()

void sys_pbl_analytics_set_unsigned	(	enum pbl_analytics_key	key,
		uint32_t	unsigned_value
	)

Set an unsigned metric.

Parameters

key	Metric key.
unsigned_value	New value.

sys_pbl_analytics_timer_start()

void sys_pbl_analytics_timer_start

(

enum pbl_analytics_key

key

)

Start a timer metric.

Has no effect if the timer is already running.

Parameters

key	Metric key.

sys_pbl_analytics_timer_stop()

void sys_pbl_analytics_timer_stop

(

enum pbl_analytics_key

key

)

Stop a timer metric, adding the elapsed time in milliseconds to it.

Has no effect if the timer is not running.

Parameters

key	Metric key.