Documentation/networking/snmp_counter.rst

   1 ===========
   2 SNMP counter
   3 ===========
   4
   5 This document explains the meaning of SNMP counters.
   6
   7 General IPv4 counters
   8 ====================
   9 All layer 4 packets and ICMP packets will change these counters, but
  10 these counters won't be changed by layer 2 packets (such as STP) or
  11 ARP packets.
  12
  13 * IpInReceives
  14 Defined in `RFC1213 ipInReceives`_
  15
  16 .. _RFC1213 ipInReceives: https://tools.ietf.org/html/rfc1213#page-26
  17
  18 The number of packets received by the IP layer. It gets increasing at the
  19 beginning of ip_rcv function, always be updated together with
  20 IpExtInOctets. It indicates the number of aggregated segments after
  21 GRO/LRO.
  22
  23 * IpInDelivers
  24 Defined in `RFC1213 ipInDelivers`_
  25
  26 .. _RFC1213 ipInDelivers: https://tools.ietf.org/html/rfc1213#page-28
  27
  28 The number of packets delivers to the upper layer protocols. E.g. TCP, UDP,
  29 ICMP and so on. If no one listens on a raw socket, only kernel
  30 supported protocols will be delivered, if someone listens on the raw
  31 socket, all valid IP packets will be delivered.
  32
  33 * IpOutRequests
  34 Defined in `RFC1213 ipOutRequests`_
  35
  36 .. _RFC1213 ipOutRequests: https://tools.ietf.org/html/rfc1213#page-28
  37
  38 The number of packets sent via IP layer, for both single cast and
  39 multicast packets, and would always be updated together with
  40 IpExtOutOctets.
  41
  42 * IpExtInOctets and IpExtOutOctets
  43 They are linux kernel extensions, no RFC definitions. Please note,
  44 RFC1213 indeed defines ifInOctets  and ifOutOctets, but they
  45 are different things. The ifInOctets and ifOutOctets include the MAC
  46 layer header size but IpExtInOctets and IpExtOutOctets don't, they
  47 only include the IP layer header and the IP layer data.
  48
  49 * IpExtInNoECTPkts, IpExtInECT1Pkts, IpExtInECT0Pkts, IpExtInCEPkts
  50 They indicate the number of four kinds of ECN IP packets, please refer
  51 `Explicit Congestion Notification`_ for more details.
  52
  53 .. _Explicit Congestion Notification: https://tools.ietf.org/html/rfc3168#page-6
  54
  55 These 4 counters calculate how many packets received per ECN
  56 status. They count the real frame number regardless the LRO/GRO. So
  57 for the same packet, you might find that IpInReceives count 1, but
  58 IpExtInNoECTPkts counts 2 or more.
  59
  60 ICMP counters
  61 ============
  62 * IcmpInMsgs and IcmpOutMsgs
  63 Defined by `RFC1213 icmpInMsgs`_ and `RFC1213 icmpOutMsgs`_
  64
  65 .. _RFC1213 icmpInMsgs: https://tools.ietf.org/html/rfc1213#page-41
  66 .. _RFC1213 icmpOutMsgs: https://tools.ietf.org/html/rfc1213#page-43
  67
  68 As mentioned in the RFC1213, these two counters include errors, they
  69 would be increased even if the ICMP packet has an invalid type. The
  70 ICMP output path will check the header of a raw socket, so the
  71 IcmpOutMsgs would still be updated if the IP header is constructed by
  72 a userspace program.
  73
  74 * ICMP named types
  75 | These counters include most of common ICMP types, they are:
  76 | IcmpInDestUnreachs: `RFC1213 icmpInDestUnreachs`_
  77 | IcmpInTimeExcds: `RFC1213 icmpInTimeExcds`_
  78 | IcmpInParmProbs: `RFC1213 icmpInParmProbs`_
  79 | IcmpInSrcQuenchs: `RFC1213 icmpInSrcQuenchs`_
  80 | IcmpInRedirects: `RFC1213 icmpInRedirects`_
  81 | IcmpInEchos: `RFC1213 icmpInEchos`_
  82 | IcmpInEchoReps: `RFC1213 icmpInEchoReps`_
  83 | IcmpInTimestamps: `RFC1213 icmpInTimestamps`_
  84 | IcmpInTimestampReps: `RFC1213 icmpInTimestampReps`_
  85 | IcmpInAddrMasks: `RFC1213 icmpInAddrMasks`_
  86 | IcmpInAddrMaskReps: `RFC1213 icmpInAddrMaskReps`_
  87 | IcmpOutDestUnreachs: `RFC1213 icmpOutDestUnreachs`_
  88 | IcmpOutTimeExcds: `RFC1213 icmpOutTimeExcds`_
  89 | IcmpOutParmProbs: `RFC1213 icmpOutParmProbs`_
  90 | IcmpOutSrcQuenchs: `RFC1213 icmpOutSrcQuenchs`_
  91 | IcmpOutRedirects: `RFC1213 icmpOutRedirects`_
  92 | IcmpOutEchos: `RFC1213 icmpOutEchos`_
  93 | IcmpOutEchoReps: `RFC1213 icmpOutEchoReps`_
  94 | IcmpOutTimestamps: `RFC1213 icmpOutTimestamps`_
  95 | IcmpOutTimestampReps: `RFC1213 icmpOutTimestampReps`_
  96 | IcmpOutAddrMasks: `RFC1213 icmpOutAddrMasks`_
  97 | IcmpOutAddrMaskReps: `RFC1213 icmpOutAddrMaskReps`_
  98
  99 .. _RFC1213 icmpInDestUnreachs: https://tools.ietf.org/html/rfc1213#page-41
 100 .. _RFC1213 icmpInTimeExcds: https://tools.ietf.org/html/rfc1213#page-41
 101 .. _RFC1213 icmpInParmProbs: https://tools.ietf.org/html/rfc1213#page-42
 102 .. _RFC1213 icmpInSrcQuenchs: https://tools.ietf.org/html/rfc1213#page-42
 103 .. _RFC1213 icmpInRedirects: https://tools.ietf.org/html/rfc1213#page-42
 104 .. _RFC1213 icmpInEchos: https://tools.ietf.org/html/rfc1213#page-42
 105 .. _RFC1213 icmpInEchoReps: https://tools.ietf.org/html/rfc1213#page-42
 106 .. _RFC1213 icmpInTimestamps: https://tools.ietf.org/html/rfc1213#page-42
 107 .. _RFC1213 icmpInTimestampReps: https://tools.ietf.org/html/rfc1213#page-43
 108 .. _RFC1213 icmpInAddrMasks: https://tools.ietf.org/html/rfc1213#page-43
 109 .. _RFC1213 icmpInAddrMaskReps: https://tools.ietf.org/html/rfc1213#page-43
 110
 111 .. _RFC1213 icmpOutDestUnreachs: https://tools.ietf.org/html/rfc1213#page-44
 112 .. _RFC1213 icmpOutTimeExcds: https://tools.ietf.org/html/rfc1213#page-44
 113 .. _RFC1213 icmpOutParmProbs: https://tools.ietf.org/html/rfc1213#page-44
 114 .. _RFC1213 icmpOutSrcQuenchs: https://tools.ietf.org/html/rfc1213#page-44
 115 .. _RFC1213 icmpOutRedirects: https://tools.ietf.org/html/rfc1213#page-44
 116 .. _RFC1213 icmpOutEchos: https://tools.ietf.org/html/rfc1213#page-45
 117 .. _RFC1213 icmpOutEchoReps: https://tools.ietf.org/html/rfc1213#page-45
 118 .. _RFC1213 icmpOutTimestamps: https://tools.ietf.org/html/rfc1213#page-45
 119 .. _RFC1213 icmpOutTimestampReps: https://tools.ietf.org/html/rfc1213#page-45
 120 .. _RFC1213 icmpOutAddrMasks: https://tools.ietf.org/html/rfc1213#page-45
 121 .. _RFC1213 icmpOutAddrMaskReps: https://tools.ietf.org/html/rfc1213#page-46
 122
 123 Every ICMP type has two counters: 'In' and 'Out'. E.g., for the ICMP
 124 Echo packet, they are IcmpInEchos and IcmpOutEchos. Their meanings are
 125 straightforward. The 'In' counter means kernel receives such a packet
 126 and the 'Out' counter means kernel sends such a packet.
 127
 128 * ICMP numeric types
 129 They are IcmpMsgInType[N] and IcmpMsgOutType[N], the [N] indicates the
 130 ICMP type number. These counters track all kinds of ICMP packets. The
 131 ICMP type number definition could be found in the `ICMP parameters`_
 132 document.
 133
 134 .. _ICMP parameters: https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml
 135
 136 For example, if the Linux kernel sends an ICMP Echo packet, the
 137 IcmpMsgOutType8 would increase 1. And if kernel gets an ICMP Echo Reply
 138 packet, IcmpMsgInType0 would increase 1.
 139
 140 * IcmpInCsumErrors
 141 This counter indicates the checksum of the ICMP packet is
 142 wrong. Kernel verifies the checksum after updating the IcmpInMsgs and
 143 before updating IcmpMsgInType[N]. If a packet has bad checksum, the
 144 IcmpInMsgs would be updated but none of IcmpMsgInType[N] would be updated.
 145
 146 * IcmpInErrors and IcmpOutErrors
 147 Defined by `RFC1213 icmpInErrors`_ and `RFC1213 icmpOutErrors`_
 148
 149 .. _RFC1213 icmpInErrors: https://tools.ietf.org/html/rfc1213#page-41
 150 .. _RFC1213 icmpOutErrors: https://tools.ietf.org/html/rfc1213#page-43
 151
 152 When an error occurs in the ICMP packet handler path, these two
 153 counters would be updated. The receiving packet path use IcmpInErrors
 154 and the sending packet path use IcmpOutErrors. When IcmpInCsumErrors
 155 is increased, IcmpInErrors would always be increased too.
 156
 157 relationship of the ICMP counters
 158 -------------------------------
 159 The sum of IcmpMsgOutType[N] is always equal to IcmpOutMsgs, as they
 160 are updated at the same time. The sum of IcmpMsgInType[N] plus
 161 IcmpInErrors should be equal or larger than IcmpInMsgs. When kernel
 162 receives an ICMP packet, kernel follows below logic:
 163
 164 1. increase IcmpInMsgs
 165 2. if has any error, update IcmpInErrors and finish the process
 166 3. update IcmpMsgOutType[N]
 167 4. handle the packet depending on the type, if has any error, update
 168    IcmpInErrors and finish the process
 169
 170 So if all errors occur in step (2), IcmpInMsgs should be equal to the
 171 sum of IcmpMsgOutType[N] plus IcmpInErrors. If all errors occur in
 172 step (4), IcmpInMsgs should be equal to the sum of
 173 IcmpMsgOutType[N]. If the errors occur in both step (2) and step (4),
 174 IcmpInMsgs should be less than the sum of IcmpMsgOutType[N] plus
 175 IcmpInErrors.
 176
 177 examples
 178 =======
 179
 180 ping test
 181 --------
 182 Run the ping command against the public dns server 8.8.8.8::
 183
 184   nstatuser@nstat-a:~$ ping 8.8.8.8 -c 1
 185   PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
 186   64 bytes from 8.8.8.8: icmp_seq=1 ttl=119 time=17.8 ms
 187
 188   --- 8.8.8.8 ping statistics ---
 189   1 packets transmitted, 1 received, 0% packet loss, time 0ms
 190   rtt min/avg/max/mdev = 17.875/17.875/17.875/0.000 ms
 191
 192 The nstayt result::
 193
 194   nstatuser@nstat-a:~$ nstat
 195   #kernel
 196   IpInReceives                    1                  0.0
 197   IpInDelivers                    1                  0.0
 198   IpOutRequests                   1                  0.0
 199   IcmpInMsgs                      1                  0.0
 200   IcmpInEchoReps                  1                  0.0
 201   IcmpOutMsgs                     1                  0.0
 202   IcmpOutEchos                    1                  0.0
 203   IcmpMsgInType0                  1                  0.0
 204   IcmpMsgOutType8                 1                  0.0
 205   IpExtInOctets                   84                 0.0
 206   IpExtOutOctets                  84                 0.0
 207   IpExtInNoECTPkts                1                  0.0
 208
 209 The Linux server sent an ICMP Echo packet, so IpOutRequests,
 210 IcmpOutMsgs, IcmpOutEchos and IcmpMsgOutType8 were increased 1. The
 211 server got ICMP Echo Reply from 8.8.8.8, so IpInReceives, IcmpInMsgs,
 212 IcmpInEchoReps and IcmpMsgInType0 were increased 1. The ICMP Echo Reply
 213 was passed to the ICMP layer via IP layer, so IpInDelivers was
 214 increased 1. The default ping data size is 48, so an ICMP Echo packet
 215 and its corresponding Echo Reply packet are constructed by:
 216
 217 * 14 bytes MAC header
 218 * 20 bytes IP header
 219 * 16 bytes ICMP header
 220 * 48 bytes data (default value of the ping command)
 221
 222 So the IpExtInOctets and IpExtOutOctets are 20+16+48=84.