Documentation/networking/gen_stats.txt

   1 Generic networking statistics for netlink users
   2 ======================================================================
   3
   4 Statistic counters are grouped into structs:
   5
   6 Struct               TLV type              Description
   7 ----------------------------------------------------------------------
   8 gnet_stats_basic     TCA_STATS_BASIC       Basic statistics
   9 gnet_stats_rate_est  TCA_STATS_RATE_EST    Rate estimator
  10 gnet_stats_queue     TCA_STATS_QUEUE       Queue statistics
  11 none                 TCA_STATS_APP         Application specific
  12
  13
  14 Collecting:
  15 -----------
  16
  17 Declare the statistic structs you need:
  18 struct mystruct {
  19         struct gnet_stats_basic bstats;
  20         struct gnet_stats_queue qstats;
  21         ...
  22 };
  23
  24 Update statistics, in dequeue() methods only, (while owning qdisc->running)
  25 mystruct->tstats.packet++;
  26 mystruct->qstats.backlog += skb->pkt_len;
  27
  28
  29 Export to userspace (Dump):
  30 ---------------------------
  31
  32 my_dumping_routine(struct sk_buff *skb, ...)
  33 {
  34         struct gnet_dump dump;
  35
  36         if (gnet_stats_start_copy(skb, TCA_STATS2, &mystruct->lock, &dump,
  37                                   TCA_PAD) < 0)
  38                 goto rtattr_failure;
  39
  40         if (gnet_stats_copy_basic(&dump, &mystruct->bstats) < 0 ||
  41             gnet_stats_copy_queue(&dump, &mystruct->qstats) < 0 ||
  42                 gnet_stats_copy_app(&dump, &xstats, sizeof(xstats)) < 0)
  43                 goto rtattr_failure;
  44
  45         if (gnet_stats_finish_copy(&dump) < 0)
  46                 goto rtattr_failure;
  47         ...
  48 }
  49
  50 TCA_STATS/TCA_XSTATS backward compatibility:
  51 --------------------------------------------
  52
  53 Prior users of struct tc_stats and xstats can maintain backward
  54 compatibility by calling the compat wrappers to keep providing the
  55 existing TLV types.
  56
  57 my_dumping_routine(struct sk_buff *skb, ...)
  58 {
  59     if (gnet_stats_start_copy_compat(skb, TCA_STATS2, TCA_STATS,
  60                                      TCA_XSTATS, &mystruct->lock, &dump,
  61                                      TCA_PAD) < 0)
  62                 goto rtattr_failure;
  63         ...
  64 }
  65
  66 A struct tc_stats will be filled out during gnet_stats_copy_* calls
  67 and appended to the skb. TCA_XSTATS is provided if gnet_stats_copy_app
  68 was called.
  69
  70
  71 Locking:
  72 --------
  73
  74 Locks are taken before writing and released once all statistics have
  75 been written. Locks are always released in case of an error. You
  76 are responsible for making sure that the lock is initialized.
  77
  78
  79 Rate Estimator:
  80 --------------
  81
  82 0) Prepare an estimator attribute. Most likely this would be in user
  83    space. The value of this TLV should contain a tc_estimator structure.
  84    As usual, such a TLV needs to be 32 bit aligned and therefore the
  85    length needs to be appropriately set, etc. The estimator interval
  86    and ewma log need to be converted to the appropriate values.
  87    tc_estimator.c::tc_setup_estimator() is advisable to be used as the
  88    conversion routine. It does a few clever things. It takes a time
  89    interval in microsecs, a time constant also in microsecs and a struct
  90    tc_estimator to  be populated. The returned tc_estimator can be
  91    transported to the kernel.  Transfer such a structure in a TLV of type
  92    TCA_RATE to your code in the kernel.
  93
  94 In the kernel when setting up:
  95 1) make sure you have basic stats and rate stats setup first.
  96 2) make sure you have initialized stats lock that is used to setup such
  97    stats.
  98 3) Now initialize a new estimator:
  99
 100    int ret = gen_new_estimator(my_basicstats,my_rate_est_stats,
 101        mystats_lock, attr_with_tcestimator_struct);
 102
 103    if ret == 0
 104        success
 105    else
 106        failed
 107
 108 From now on, every time you dump my_rate_est_stats it will contain
 109 up-to-date info.
 110
 111 Once you are done, call gen_kill_estimator(my_basicstats,
 112 my_rate_est_stats) Make sure that my_basicstats and my_rate_est_stats
 113 are still valid (i.e still exist) at the time of making this call.
 114
 115
 116 Authors:
 117 --------
 118 Thomas Graf <tgraf@suug.ch>
 119 Jamal Hadi Salim <hadi@cyberus.ca>