About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / gen_stats.txt




Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:47 EST.

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:
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>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.