As I’m going through the statistics module and documenting it, one
thing that occurs to me is for the case where STATS_NAME_ENABLE = 0, and
statistic names are omitted, we should create the statistic name ->
number mapping, in the target’s directory, in a machine parseable
format (i.e. JSON.) I’m thinking we should put this into the
manifest.json when we create an image, that way if a management system
wants to ingest this data, it can easily take this information, along
with the created image.
I thought about versioning the structure, however decided against it,
because:
- Manually updating the statistics version when it changes is error
prone, because people forget to change version numbers
- I think it is likely that any management system or user who wants to
interpret these values, will likely have the image definition for that
image, _AND_ will probably not do an exhaustive search of all images, to
find one that has a matching definition of version of statistics that
are found on that device. (likely:)
Comments welcome. Below is the documentation I’ve written at the top
of the module.
NOTE: Newt does not yet support generating statistics mappings in the
manifest.json, I’m adding that support to create-image now.
Best,
Sterling
/**
* Declare an example statistics section, which is fittingly, the
number
* statistics registered in the system. There are two, largely
duplicated,
* statistics sections in order to provide the optional ability to
* name statistics.
*
* STATS_SECT_START/END actually declare the statistics structure
definition,
* STATS_SECT_DECL() creates the structure declaration so you can
declare
* these statistics as a global structure, and STATS_NAME_START/END are
how
* you name the statistics themselves.
*
* Statistics entries can be declared as any of the following values,
however,
* all statistics in a given structure must be of the same size, and
they are
* all unsigned.
*
* - STATS_SECT_ENTRY(): default statistic entry, 32-bits. This
* is the good stuff. Two factors to consider:
* - With 16-bit numbers, rollovers happen, frequently. Whether
its
* testing a pathological condition, or just a long time since
you've
* collected a statistic: it really sucks to not have a crucial
piece
* of information.
* - 64-bit numbers are wonderful things. However, the gods did
not see
* fit to bless us with unlimited memory. 64-bit statistics are
useful
* when you want to store non-statistics in a statistics entry
(i.e. time),
* because its convenient...
*
* - STATS_SECT_ENTRY16(): 16-bits. Smaller statistics if you need to
fit into
* specific RAM or code size numbers.
*
* - STATS_SECT_ENTRY32(): 32-bits, if you want to force it.
*
* - STATS_SECT_ENTRY64(): 64-bits. Useful for storing chunks of data.
*
* Following the statics entry declaration is the statistic names
declaration.
* This is compiled out when STATS_NAME_ENABLE is set to 0. This
declaration
* is const, and therefore can be located in .text, not .data.
*
* In cases where the system configuration variable STATS_NAME_ENABLE
is set
* to 1, the statistics names are stored and returned to both the
console
* and management APIs. Whereas, when STATS_NAME_ENABLE = 0, these
statistics
* are numbered, s0, s1, etc. The newt tool will create a list of
statistic #
* -> statistic name in the
* bin/targets/<your-target>/app/apps/<your-app>/manifest.json file.
* That way, in cases where you want to save on code size, you can
store the
* manifest file for the image you've generated, and management tools
will
* be able to display the named statistic from the map.
*/
STATS_SECT_START(stats)
STATS_SECT_ENTRY(num_registered)
STATS_SECT_END
STATS_SECT_DECL(stats) g_stats_stats;
STATS_NAME_START(stats)
STATS_NAME(stats, num_registered)
STATS_NAME_END(stats)
