tapset::snmp(3stap)

1TAPSET::SNMP(3stap)                                        TAPSET::SNMP(3stap)
2
3
4

NAME

6       tapset::snmp  -  Systemtap  simple  network  management  protocol probe
7       points.
8
9
10

DESCRIPTION

12       This family of probe points enhances the Linux system's  implementation
13       of  the  Simple Network Management Protocol (SNMP) by allowing the user
14       to collect per-socket statistics. SNMP data is collected in  the  Linux
15       kernel  by  counting various events occurring in the networking subsys‐
16       tem. Linux provides one counter for each type of event, thus  providing
17       a system-wide collection of network statistics. These statistics can be
18       viewed with the command: netstat -s.
19
20       The probe points defined in the SNMP group of tapsets  allow  users  to
21       aberrate  each  SNMP  counter into groups of counters. For example, the
22       user may count SNMP events for a single network socket or for  a  group
23       of sockets.
24
25       Severals  SNMP tapsets have been created. Each tapset represents a sin‐
26       gle layer of the network stack and defines a group of  counters  called
27       management  information  blocks or MIBs. Currently tapsets are provided
28       that support MIBS for IP, TCP layers and the enhanced  linux  MIB.  See
29       the  file  /usr/include/linux/snmp.h  for  a  list of MIBS supported by
30       linux.
31
32

PROBE HANDLERS, COUNTERS AND CALLBACKS

34       Each probe represents a single SNMP statistic. The probe's  handler  is
35       called  each time the system performs an operation that would alter the
36       associated statistic. Each probe also defines an indexed set  of  coun‐
37       ters used to record probe hits. The probe handler calls a user supplied
38       callback functions to determine which  counter  to  alter.  The  user's
39       callback  should  return  a  key  value  that will be used to index the
40       counter. For example a callback could return a unique  value  for  each
41       socket.  This  would  results in a separate counter being used for each
42       socket.
43
44       Each tapset is now described. Examples of probe names and counter names
45       are  given.  See  the   tapset  itself for a complete list of supported
46       probes. Users of the tapset must provide a callback  function  matching
47       the name and prototype as shown.
48
49
50       IP MIB Tapset:
51
52       Example probe name: ipmib.InReceives
53
54       Example counter name: InReceives
55
56       Callback prototype:
57
58       ipmib_filter_key:long (skb:long, op:long, SourceIsLocal:long)
59
60       This  user  supplied function should compute and return a value used to
61       index the statistical counter. The skb  is  a  pointer  to  the  struct
62       sk_buff being processed at the time. The local ip-address and port num‐
63       ber will be located in either the source or destination fields  of  the
64       network  packet.  SourceIsLocal will be true if the local address is in
65       the source field. The probe handler will add the value  of  op  to  the
66       counter. To skip counting the event return a value of zero.
67
68
69       TCP MIB tapset:
70
71       Example probe name: tcpmib.InSegs
72
73       Example counter name: InSegs
74
75       Callback prototype:
76
77       tcpmib_filter_key:long (sk:long, op:long)
78
79       This  user  supplied function should compute and return a value used to
80       index the statistical counter. The sk is a pointer to the  struct  sock
81       being processed at the time. The probe handler will add the value of op
82       to the counter. To skip counting the event return a value of zero.
83
84
85       LINUX MIB tapset:
86
87       linuxmib.stp
88
89       Example probe name: linuxmib.DelayedACKs
90
91       Example counter name: DelayedACKs
92
93       Callback prototype:
94
95       linuxmib_filter_key:long (sk:long, op:long)
96
97       This user supplied function should compute and return a value  used  to
98       index  the  statistical counter. The sk is a pointer to the struct sock
99       being processed at the time. The probe handler will add the value of op
100       to the counter. To skip counting the event return a value of zero.
101
102

EXAMPLE

104       This  example  script  counts the number of TCP retransmits and records
105       them per-remote address. It displays the counts when terminated.
106
107              /* Enable the statistic we want to record. */
108              probe tcpmib.RetransSegs {}
109
110              /*
111               * Find the remote address and return
112               * it as an index to the counter array.
113               */
114              function tcpmib_filter_key: long ( sk:long, op:long ){
115                   if ( !sk ) return 0;
116                   raddr = sk_get_daddr(sk);
117                   return raddr
118              }
119
120              /* Print the results. */
121              probe end {
122                   foreach (addr in  RetransSegs )
123                        printf ("%s  %d ",ip_ntop(htonl(addr)), lport)
124              }
125
126

FILES

128       /usr/share/doc/systemtap*/examples/tcpipstat.stp
129
130

NAME

DESCRIPTION

PROBE HANDLERS, COUNTERS AND CALLBACKS

EXAMPLE

FILES

SEE ALSO