TAPSET::SNMP(3stap)                                                                                          TAPSET::SNMP(3stap)



NAME
       tapset::snmp - Systemtap simple network management protocol probe points.



DESCRIPTION
       This  family  of probe points enhances the Linux system's implementation of the Simple Network Management Protocol (SNMP)
       by allowing the user to collect per-socket statistics. SNMP data is collected in the Linux  kernel  by  counting  various
       events occurring in the networking subsystem. Linux provides one counter for each type of event, thus providing a system-
       wide collection of network statistics. These statistics can be viewed with the command: netstat -s.

       The probe points defined in the SNMP group of tapsets allow users to aberrate each SNMP counter into groups of  counters.
       For example, the user may count SNMP events for a single network socket or for a group of sockets.

       Severals  SNMP  tapsets have been created. Each tapset represents a single layer of the network stack and defines a group
       of counters called management information blocks or MIBs. Currently tapsets are provided that support MIBS  for  IP,  TCP
       layers and the enhanced linux MIB. See the file /usr/include/linux/snmp.h for a list of MIBS supported by linux.


PROBE HANDLERS, COUNTERS AND CALLBACKS
       Each  probe  represents a single SNMP statistic. The probe's handler is called each time the system performs an operation
       that would alter the associated statistic. Each probe also defines an indexed set of counters used to record probe  hits.
       The  probe  handler  calls  a  user  supplied callback functions to determine which counter to alter. The user's callback
       should return a key value that will be used to index the counter. For example a callback could return a unique value  for
       each socket. This would results in a separate counter being used for each socket.

       Each  tapset is now described. Examples of probe names and counter names are given. See the  tapset itself for a complete
       list of supported probes. Users of the tapset must provide a callback function matching the name and prototype as shown.


       IP MIB Tapset:

       Example probe name: ipmib.InReceives

       Example counter name: InReceives

       Callback prototype:

       ipmib_filter_key:long (skb:long, op:long, SourceIsLocal:long)

       This user supplied function should compute and return a value used to index the statistical counter. The skb is a pointer
       to  the  struct  sk_buff  being processed at the time. The local ip-address and port number will be located in either the
       source or destination fields of the network packet.  SourceIsLocal will be true if the local address  is  in  the  source
       field. The probe handler will add the value of op to the counter. To skip counting the event return a value of zero.


       TCP MIB tapset:

       Example probe name: tcpmib.InSegs

       Example counter name: InSegs

       Callback prototype:

       tcpmib_filter_key:long (sk:long, op:long)

       This  user supplied function should compute and return a value used to index the statistical counter. The sk is a pointer
       to the struct sock being processed at the time. The probe handler will add the value of op to the counter. To skip count-
       ing the event return a value of zero.


       LINUX MIB tapset:

       linuxmib.stp

       Example probe name: linuxmib.DelayedACKs

       Example counter name: DelayedACKs

       Callback prototype:

       linuxmib_filter_key:long (sk:long, op:long)

       This  user supplied function should compute and return a value used to index the statistical counter. The sk is a pointer
       to the struct sock being processed at the time. The probe handler will add the value of op to the counter. To skip count-
       ing the event return a value of zero.


EXAMPLE
       This example script counts the number of TCP retransmits and records them per-remote address. It displays the counts when
       terminated.

              /* Enable the statistic we want to record. */
              probe tcpmib.RetransSegs {}

              /*
               * Find the remote address and return
               * it as an index to the counter array.
               */
              function tcpmib_filter_key: long ( sk:long, op:long ){
                   if ( !sk ) return 0;
                   raddr = sk_get_daddr(sk);
                   return raddr
              }

              /* Print the results. */
              probe end {
                   foreach (addr in  RetransSegs )
                        printf ("%s  %d ",ip_ntop(htonl(addr)), lport)
              }


FILES
       /usr/share/doc/systemtap*/examples/tcpipstat.stp


SEE ALSO
       stap(1), stapprobes(3stap), stapfuncs(3stap)



IBM                                                                                                          TAPSET::SNMP(3stap)