From patchwork Tue Jun 16 13:15:44 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Cristian Dumitrescu X-Patchwork-Id: 5451 Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [IPv6:::1]) by dpdk.org (Postfix) with ESMTP id 32787C322; Tue, 16 Jun 2015 15:17:02 +0200 (CEST) Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id C5221C320 for ; Tue, 16 Jun 2015 15:16:59 +0200 (CEST) Received: from orsmga002.jf.intel.com ([10.7.209.21]) by orsmga103.jf.intel.com with ESMTP; 16 Jun 2015 06:15:47 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.13,626,1427785200"; d="scan'208";a="747637146" Received: from irvmail001.ir.intel.com ([163.33.26.43]) by orsmga002.jf.intel.com with ESMTP; 16 Jun 2015 06:15:47 -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 t5GDFjK6010730; Tue, 16 Jun 2015 14:15:46 +0100 Received: from sivswdev01.ir.intel.com (localhost [127.0.0.1]) by sivswdev01.ir.intel.com with ESMTP id t5GDFjRL015294; Tue, 16 Jun 2015 14:15:45 +0100 Received: (from cfdumitr@localhost) by sivswdev01.ir.intel.com with id t5GDFjk8015290; Tue, 16 Jun 2015 14:15:45 +0100 From: Cristian Dumitrescu To: dev@dpdk.org Date: Tue, 16 Jun 2015 14:15:44 +0100 Message-Id: <1434460544-15256-1-git-send-email-cristian.dumitrescu@intel.com> X-Mailer: git-send-email 1.7.4.1 Subject: [dpdk-dev] [PATCH v3] doc: guidelines for library statistics 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: , Errors-To: dev-bounces@dpdk.org Sender: "dev" v3 changes -fixed bullets for correct doc generation v2 changes -small text changes -reordered sections to have guidelines at the top and motivation at the end -broke lines at 80 characters Signed-off-by: Cristian Dumitrescu --- doc/guides/guidelines/index.rst | 1 + doc/guides/guidelines/statistics.rst | 104 ++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 0 deletions(-) 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 100644 --- 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..bc91723 --- /dev/null +++ b/doc/guides/guidelines/statistics.rst @@ -0,0 +1,104 @@ +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__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.