From mboxrd@z Thu Jan 1 00:00:00 1970 From: Cristian Dumitrescu Subject: =?utf-8?q?=5BPATCH=5D_doc=3A_guidelines_for_library_st?= =?utf-8?q?atistics?= Date: Mon, 8 Jun 2015 15:50:24 +0100 Message-ID: <1433775024-29866-1-git-send-email-cristian.dumitrescu@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable To: dev@dpdk.org Return-path: Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by dpdk.org (Postfix) with ESMTP id 4C8ACFFA for ; Mon, 8 Jun 2015 16:50:29 +0200 (CEST) List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Signed-off-by: Cristian Dumitrescu --- doc/guides/guidelines/index.rst | 1 + doc/guides/guidelines/statistics.rst | 42 ++++++++++++++++++++++++++++++= ++++++ 2 files changed, 43 insertions(+) create mode 100644 doc/guides/guidelines/statistics.rst diff --git a/doc/guides/guidelines/index.rst b/doc/guides/guidelines/inde= x.rst index b2b0a92..c01f958 --- a/doc/guides/guidelines/index.rst +++ b/doc/guides/guidelines/index.rst @@ -6,3 +6,4 @@ Guidelines :numbered: =20 coding_style + statistics diff --git a/doc/guides/guidelines/statistics.rst b/doc/guides/guidelines= /statistics.rst new file mode 100644 index 0000000..32c6020 --- /dev/null +++ b/doc/guides/guidelines/statistics.rst @@ -0,0 +1,42 @@ +Library Statistics +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Description +----------- + +This document describes the guidelines for DPDK library-level statistics= counter support. This includes guidelines for turning library statistics= on and off, requirements for preventing ABI changes when library statist= ics are turned on and off, etc. + +Motivation to allow the application to turn library statistics on and of= f +------------------------------------------------------------------------= - + +It is highly recommended that each library provides statistics counters = to allow the application to monitor the library-level run-time events. Ty= pical counters are: number of packets received/dropped/transmitted, numbe= r of buffers allocated/freed, number of occurrences for specific events, = etc. + +Since the resources consumed for library-level statistics counter collec= tion have to be spent out of the application budget and the counters coll= ected by some libraries might not be relevant for the current application= , in order to avoid any unwanted waste of resources and/or performance fo= r the application, the application is to decide at build time whether the= collection of library-level statistics counters should be turned on or o= ff for each library individually. + +Library-level statistics counters can be relevant or not for specific ap= plications: +* For application A, counters maintained by library X are always relevan= t and the application needs to use them to implement certain features, 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 du= ring the application debug stage and not relevant once debug phase is ove= r. In this case, the application may decide to turn on the collection of = library X statistics counters during the debug phase and later on turn th= em off; +* For application C, counters maintained by library X are not relevant a= t all. It might me that the application maintains its own set of statisti= cs counters that monitor a different set of run-time events than library = X (e.g. number of connection requests, number of active users, etc). It m= ight also be that application uses multiple libraries (library X, library= Y, etc) and it is interested in the statistics counters of library Y, bu= t 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 l= ibrary Y. + +The statistics collection consumes a certain amount of CPU resources (cy= cles, cache bandwidth, memory bandwidth, etc) that depends on: +* Number of libraries used by the current application that have statisti= cs counters collection turned on; +* Number of statistics counters maintained by each library per object ty= pe instance (e.g. per port, table, pipeline, thread, etc); +* Number of instances created for each object type supported by each lib= rary; +* Complexity of the statistics logic collection for each counter: when o= nly some occurrences of a specific event are valid, several conditional b= ranches might involved in the decision of whether the current occurrence = of the event should be counted or not (e.g. on the event of packet recept= ion, only TCP packets with destination port within a certain range should= be recorded), etc. + +Mechanism to allow the application to turn library statistics on and off +------------------------------------------------------------------------ + +Each library that provides statistics counters should provide a single b= uild time flag that decides whether the statistics counter collection is = enabled or not for this library. This flag should be exposed as a variabl= e within the DPDK configuration file. When this flag is set, all the coun= ters supported by current library are collected; when this flag is cleare= d, none of the counters supported by the current library are collected: + + #DPDK file =E2=80=9C./config/common_linuxapp=E2=80=9D, =E2=80=9C./confi= g/common_bsdapp=E2=80=9D, etc + CONFIG_RTE_LIBRTE__COLLECT_STATS=3Dy/n + +The default value for this DPDK configuration file variable (either =E2=80= =9Cyes=E2=80=9D or =E2=80=9Cno=E2=80=9D) is left at the decision of each = library. + +Prevention of ABI changes due to library statistics support +----------------------------------------------------------- + +The layout of data structures and prototype of functions that are part o= f the library API should not be affected by whether the collection of sta= tistics counters is turned on or off for the current library. In practica= l terms, this means that space is always allocated in the API data struct= ures 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 tu= rned off, the counters retrieved through the statistics related API funct= ions should have the default value of zero. --=20 1.8.5.3