[mirror_ubuntu-bionic-kernel.git] / Documentation / networking / gen_stats.txt

Generic networking statistics for netlink users
======================================================================

Statistic counters are grouped into structs:

Struct               TLV type              Description
----------------------------------------------------------------------
gnet_stats_basic     TCA_STATS_BASIC       Basic statistics
gnet_stats_rate_est  TCA_STATS_RATE_EST    Rate estimator
gnet_stats_queue     TCA_STATS_QUEUE       Queue statistics
none                 TCA_STATS_APP         Application specific


Collecting:
-----------

Declare the statistic structs you need:
struct mystruct {
	struct gnet_stats_basic	bstats;
	struct gnet_stats_queue	qstats;
	...
};

Update statistics, in dequeue() methods only, (while owning qdisc->running)
mystruct->tstats.packet++;
mystruct->qstats.backlog += skb->pkt_len;


Export to userspace (Dump):
---------------------------

my_dumping_routine(struct sk_buff *skb, ...)
{
	struct gnet_dump dump;

	if (gnet_stats_start_copy(skb, TCA_STATS2, &mystruct->lock, &dump,
				  TCA_PAD) < 0)
		goto rtattr_failure;

	if (gnet_stats_copy_basic(&dump, &mystruct->bstats) < 0 ||
	    gnet_stats_copy_queue(&dump, &mystruct->qstats) < 0 ||
		gnet_stats_copy_app(&dump, &xstats, sizeof(xstats)) < 0)
		goto rtattr_failure;

	if (gnet_stats_finish_copy(&dump) < 0)
		goto rtattr_failure;
	...
}

TCA_STATS/TCA_XSTATS backward compatibility:
--------------------------------------------

Prior users of struct tc_stats and xstats can maintain backward
compatibility by calling the compat wrappers to keep providing the
existing TLV types.

my_dumping_routine(struct sk_buff *skb, ...)
{
    if (gnet_stats_start_copy_compat(skb, TCA_STATS2, TCA_STATS,
				     TCA_XSTATS, &mystruct->lock, &dump,
				     TCA_PAD) < 0)
		goto rtattr_failure;
	...
}

A struct tc_stats will be filled out during gnet_stats_copy_* calls
and appended to the skb. TCA_XSTATS is provided if gnet_stats_copy_app
was called.


Locking:
--------

Locks are taken before writing and released once all statistics have
been written. Locks are always released in case of an error. You
are responsible for making sure that the lock is initialized.


Rate Estimator:
--------------

0) Prepare an estimator attribute. Most likely this would be in user
   space. The value of this TLV should contain a tc_estimator structure.
   As usual, such a TLV needs to be 32 bit aligned and therefore the
   length needs to be appropriately set, etc. The estimator interval
   and ewma log need to be converted to the appropriate values.
   tc_estimator.c::tc_setup_estimator() is advisable to be used as the
   conversion routine. It does a few clever things. It takes a time
   interval in microsecs, a time constant also in microsecs and a struct
   tc_estimator to  be populated. The returned tc_estimator can be
   transported to the kernel.  Transfer such a structure in a TLV of type
   TCA_RATE to your code in the kernel.

In the kernel when setting up:
1) make sure you have basic stats and rate stats setup first.
2) make sure you have initialized stats lock that is used to setup such
   stats.
3) Now initialize a new estimator:

   int ret = gen_new_estimator(my_basicstats,my_rate_est_stats,
       mystats_lock, attr_with_tcestimator_struct);

   if ret == 0
       success
   else
       failed

From now on, every time you dump my_rate_est_stats it will contain
up-to-date info.

Once you are done, call gen_kill_estimator(my_basicstats,
my_rate_est_stats) Make sure that my_basicstats and my_rate_est_stats
are still valid (i.e still exist) at the time of making this call.


Authors:
--------
Thomas Graf <tgraf@suug.ch>
Jamal Hadi Salim <hadi@cyberus.ca>
Commit	Line	Data
1da177e4 LT	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
edb09eb1	24	Update statistics, in dequeue() methods only, (while owning qdisc->running)
1da177e4 LT	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
9854518e ND	36	if (gnet_stats_start_copy(skb, TCA_STATS2, &mystruct->lock, &dump,
9854518e ND	37	TCA_PAD) < 0)
1da177e4 LT	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,
9854518e ND	60	TCA_XSTATS, &mystruct->lock, &dump,
9854518e ND	61	TCA_PAD) < 0)
1da177e4 LT	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.
992caacf ML	84	As usual, such a TLV needs to be 32 bit aligned and therefore the
992caacf ML	85	length needs to be appropriately set, etc. The estimator interval
1da177e4 LT	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
fff9289b ML	108	From now on, every time you dump my_rate_est_stats it will contain
fff9289b ML	109	up-to-date info.
1da177e4 LT	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>