From mboxrd@z Thu Jan 1 00:00:00 1970 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) Received: from orsmga001.jf.intel.com ([10.7.209.18]) by orsmga102.jf.intel.com with ESMTP; 08 Jun 2015 07:50:28 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.13,574,1427785200"; d="scan'208";a="707302929" Received: from irvmail001.ir.intel.com ([163.33.26.43]) by orsmga001.jf.intel.com with ESMTP; 08 Jun 2015 07:50:28 -0700 Received: from sivswdev01.ir.intel.com (sivswdev01.ir.intel.com [10.237.217.45]) by irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id t58EoQTn028345; Mon, 8 Jun 2015 15:50:26 +0100 Received: from sivswdev01.ir.intel.com (localhost [127.0.0.1]) by sivswdev01.ir.intel.com with ESMTP id t58EoQK8029903; Mon, 8 Jun 2015 15:50:26 +0100 Received: (from cfdumitr@localhost) by sivswdev01.ir.intel.com with id t58EoQWc029899; Mon, 8 Jun 2015 15:50:26 +0100 From: Cristian Dumitrescu To: dev@dpdk.org Date: Mon, 8 Jun 2015 15:50:24 +0100 Message-Id: <1433775024-29866-1-git-send-email-cristian.dumitrescu@intel.com> X-Mailer: git-send-email 1.7.4.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] =?utf-8?q?=5BPATCH=5D_doc=3A_guidelines_for_library_st?= =?utf-8?q?atistics?= X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 08 Jun 2015 14:50:30 -0000 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/index.rst index b2b0a92..c01f958 --- a/doc/guides/guidelines/index.rst +++ b/doc/guides/guidelines/index.rst @@ -6,3 +6,4 @@ Guidelines :numbered: 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 +================== + +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 statistics are turned on and off, etc. + +Motivation to allow the application to turn library statistics on and off +------------------------------------------------------------------------- + +It is highly recommended that each library provides statistics counters to allow the 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. + +Since 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 for the current application, in order to avoid any unwanted waste of resources and/or performance for the application, the application is to 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, 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 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 later on turn them off; +* For application C, counters maintained by library X are not relevant at all. It might me that the application maintains its own set of statistics 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 might also be that 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, several conditional branches 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 reception, 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 build time flag that decides whether the statistics counter collection is enabled or not for this library. 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; when this flag is cleared, none of the counters supported by the current library are collected: + + #DPDK file “./config/common_linuxapp”, “./config/common_bsdapp”, etc + CONFIG_RTE_LIBRTE__COLLECT_STATS=y/n + +The default value for this DPDK configuration file variable (either “yes” or “no”) 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 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 is always 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 the default value of zero. -- 1.8.5.3