Analytics

Firmware metrics collected into periodic heartbeats. More...

Modules
	Analytics backends
	Interface implemented by analytics backends.

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)    sys_pbl_analytics_set_signed(PBL_ANALYTICS_KEY(key_name), signed_value)
	Set a signed metric by name.
#define	PBL_ANALYTICS_SET_UNSIGNED(key_name, unsigned_value)    sys_pbl_analytics_set_unsigned(PBL_ANALYTICS_KEY(key_name), unsigned_value)
	Set an unsigned metric by name.
#define	PBL_ANALYTICS_SET_STRING(key_name, value)    sys_pbl_analytics_set_string(PBL_ANALYTICS_KEY(key_name), value)
	Set a string metric by name.
#define	PBL_ANALYTICS_TIMER_START(key_name)    sys_pbl_analytics_timer_start(PBL_ANALYTICS_KEY(key_name))
	Start a timer metric by name.
#define	PBL_ANALYTICS_TIMER_STOP(key_name)   sys_pbl_analytics_timer_stop(PBL_ANALYTICS_KEY(key_name))
	Stop a timer metric by name.
#define	PBL_ANALYTICS_ADD(key_name, amount)    sys_pbl_analytics_add(PBL_ANALYTICS_KEY(key_name), amount)
	Add to an integer metric by name.

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 a backend every call is a no-op.

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

PBL_ANALYTICS_ADD(button_pressed_count, 1);
 
PBL_ANALYTICS_TIMER_START(backlight_on_time_ms);
...
PBL_ANALYTICS_TIMER_STOP(backlight_on_time_ms);

Macro Definition Documentation

PBL_ANALYTICS_ADD

#define PBL_ANALYTICS_ADD	(		key_name,
			amount
	)		sys_pbl_analytics_add(PBL_ANALYTICS_KEY(key_name), amount)

Add to an integer metric by name.

Parameters

key_name	Metric name.
amount	Amount to add, may be negative.

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
	)		sys_pbl_analytics_set_signed(PBL_ANALYTICS_KEY(key_name), signed_value)

Set a signed metric by name.

Parameters

key_name	Metric name.
signed_value	New value.

PBL_ANALYTICS_SET_STRING

#define PBL_ANALYTICS_SET_STRING	(		key_name,
			value
	)		sys_pbl_analytics_set_string(PBL_ANALYTICS_KEY(key_name), value)

Set a string metric by name.

Parameters

key_name	Metric name.
value	NUL-terminated string.

PBL_ANALYTICS_SET_UNSIGNED

#define PBL_ANALYTICS_SET_UNSIGNED	(		key_name,
			unsigned_value
	)		sys_pbl_analytics_set_unsigned(PBL_ANALYTICS_KEY(key_name), unsigned_value)

Set an unsigned metric by name.

Parameters

key_name	Metric name.
unsigned_value	New value.

PBL_ANALYTICS_TIMER_START

#define PBL_ANALYTICS_TIMER_START

(

key_name

)

sys_pbl_analytics_timer_start(PBL_ANALYTICS_KEY(key_name))

Start a timer metric by name.

Parameters

key_name

Metric name.

PBL_ANALYTICS_TIMER_STOP

#define PBL_ANALYTICS_TIMER_STOP

(

key_name

)

sys_pbl_analytics_timer_stop(PBL_ANALYTICS_KEY(key_name))

Stop a timer metric by name.

Parameters

key_name

Metric name.

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.