d/numam-dpdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc: guidelines for library statistics

Browse Source 
Signed-off-by: Cristian Dumitrescu <cristian.dumitrescu@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
This commit is contained in:
Cristian Dumitrescu 2015-06-16 14:35:57 +01:00 committed by Thomas Monjalon
parent 753836b7a2
commit 55cf939a4f
1 changed files with 105 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
doc/guides/guidelines/design.rst
View File

@ -52,3 +52,108 @@ The following config options can be used:
* CONFIG_RTE_EXEC_ENV is a string that contains the name of the executive environment.
* CONFIG_RTE_EXEC_ENV_BSDAPP or CONFIG_RTE_EXEC_ENV_LINUXAPP are defined only if we are building for this execution environment.
Library Statistics
------------------
Description
~~~~~~~~~~~
This document describes the guidelines for DPDK library-level statistics counter
support. This includes guidelines for turning library statistics on and off and
requirements for preventing ABI changes when implementing statistics.
Mechanism to allow the application to turn library statistics on and off
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each library that maintains statistics counters should provide a single build
time flag that decides whether the statistics counter collection is enabled or
not. This flag should be exposed as a variable within the DPDK configuration
file. When this flag is set, all the counters supported by current library are
collected for all the instances of every object type provided by the library.
When this flag is cleared, none of the counters supported by the current library
are collected for any instance of any object type provided by the library:
.. code-block:: console
# DPDK file config/common_linuxapp, config/common_bsdapp, etc.
CONFIG_RTE_<LIBRARY_NAME>_STATS_COLLECT=y/n
The default value for this DPDK configuration file variable (either "yes" or
"no") is decided by each library.
Prevention of ABI changes due to library statistics support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The layout of data structures and prototype of functions that are part of the
library API should not be affected by whether the collection of statistics
counters is turned on or off for the current library. In practical terms, this
means that space should always be allocated in the API data structures for
statistics counters and the statistics related API functions are always built
into the code, regardless of whether the statistics counter collection is turned
on or off for the current library.
When the collection of statistics counters for the current library is turned
off, the counters retrieved through the statistics related API functions should
have a default value of zero.
Motivation to allow the application to turn library statistics on and off
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is highly recommended that each library provides statistics counters to allow
an application to monitor the library-level run-time events. Typical counters
are: number of packets received/dropped/transmitted, number of buffers
allocated/freed, number of occurrences for specific events, etc.
However, the resources consumed for library-level statistics counter collection
have to be spent out of the application budget and the counters collected by
some libraries might not be relevant to the current application. In order to
avoid any unwanted waste of resources and/or performance impacts, the
application should decide at build time whether the collection of library-level
statistics counters should be turned on or off for each library individually.
Library-level statistics counters can be relevant or not for specific
applications:
* For Application A, counters maintained by Library X are always relevant and
the application needs to use them to implement certain features, such as traffic
accounting, logging, application-level statistics, etc. In this case,
the application requires that collection of statistics counters for Library X is
always turned on.
* For Application B, counters maintained by Library X are only useful during the
application debug stage and are not relevant once debug phase is over. In this
case, the application may decide to turn on the collection of Library X
statistics counters during the debug phase and at a later stage turn them off.
* For Application C, counters maintained by Library X are not relevant at all.
It might be that the application maintains its own set of statistics counters
that monitor a different set of run-time events (e.g. number of connection
requests, number of active users, etc). It might also be that the application
uses multiple libraries (Library X, Library Y, etc) and it is interested in the
statistics counters of Library Y, but not in those of Library X. In this case,
the application may decide to turn the collection of statistics counters off for
Library X and on for Library Y.
The statistics collection consumes a certain amount of CPU resources (cycles,
cache bandwidth, memory bandwidth, etc) that depends on:
* Number of libraries used by the current application that have statistics
counters collection turned on.
* Number of statistics counters maintained by each library per object type
instance (e.g. per port, table, pipeline, thread, etc).
* Number of instances created for each object type supported by each library.
* Complexity of the statistics logic collection for each counter: when only
some occurrences of a specific event are valid, additional logic is typically
needed to decide whether the current occurrence of the event should be counted
or not. For example, in the event of packet reception, when only TCP packets
with destination port within a certain range should be recorded, conditional
branches are usually required. When processing a burst of packets that have been
validated for header integrity, counting the number of bits set in a bitmask
might be needed.