#
# Copyright (c) 2021 Red Hat.
#
# This program is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the
# Free Software Foundation; either version 2 of the License, or (at your
# option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
# for more details.
#
# Sockets PMDA help file
#
# lines beginning with a # are ignored
# lines beginning @ introduce a new entry of the form
#  @ metric_name oneline-text
#  help text goes
#  here over multiple lines
#  ...
#
# the metric_name is decoded against the default PMNS -- as a special case,
# a name of the form NNN.MM (for numeric NNN and MM) is interpreted as an
# instance domain identification, and the text describes the instance domain
#
# blank lines before the @ line are ignored
#
@ 154.0 network sockets

@ network.persocket.filter filter for sockets of interest
The string value of this metric is used to restrict the returned instance
domain of network sockets to only those sockets of interest. The default
filter is "state connected". This metric supports pmstore(1) to change the
filter. For further details on filter syntax, see the FILTER section of ss(1).

@ network.persocket.netid socket protocol identifier
Depending on PMDA configuration options, the socket netid may be one of tcp,
tcp6, udp, udp6, udplite, udplite6 or raw. See ss(8) for further details.

@ network.persocket.state socket state as a string, commonly UNCONN, ESTAB, TIME-WAIT
Possible socket states depend on the address family. Common states include:
UNCONN, ESTAB, SYN_SENT, SYN_RECV, FIN_WAIT1, FIN_WAIT2, TIME_WAIT,
CLOSE, CLOSE_WAIT, LAST_ACK, LISTEN and CLOSING

@ network.persocket.recvq length of the receive queue

@ network.persocket.sendq length of the send queue

@ network.persocket.src local (source) IP address (IPv4 or IPv6) and port

@ network.persocket.dst destination IP address (IPv4 or IPv6) and port

@ network.persocket.uid the user id the socket belongs to

@ network.persocket.inode the socket's inode number in VFS
The socket inode can be matched up with symlinks in /proc/<pid>/fd
for the process that created the socket.

@ network.persocket.sk uuid cookie of the socket

@ network.persocket.cgroup cgroup v2 pathname
Cgroup v2 pathname. This pathname is relative to the mount point
of the hierarchy (usually below /sys/fs/cgroup)

@ network.persocket.v6only boolean value set to one if the socket is IPv6, 0 otherwise

@ network.persocket.ts boolean value set to one if the timestamp option is set

@ network.persocket.sack boolean value set to one if the sack option is set

@ network.persocket.cubic boolean value set to one if cubic congestion control is enabled

@ network.persocket.ato ack timeout when using delayed ack mode
Ack timeout in milliseconds, used for delayed ack mode.

@ network.persocket.mss maximum segment size

@ network.persocket.pmtu path maximum transmission unit

@ network.persocket.rcvmss receive maximum transmission units

@ network.persocket.advmss advertised maximum segment size

@ network.persocket.cwnd congestion window size

@ network.persocket.ssthresh tcp congestion window slow start threshold

@ network.persocket.bytes_sent count of bytes sent using the socket

@ network.persocket.bytes_retrans count of bytes retransmitted using the socket

@ network.persocket.bytes_acked count of bytes acked using the socket

@ network.persocket.bytes_received count of bytes received using the socket

@ network.persocket.segs_out count of segments sent out using the socket

@ network.persocket.segs_in count of segments received using the socket

@ network.persocket.data_segs_out count of data segments sent out using the socket

@ network.persocket.data_segs_in count of data segments received using the socket

@ network.persocket.send egress bps

@ network.persocket.lastsnd how long time since the last packet sent in milliseconds

@ network.persocket.lastrcv how long time since the last packet received in milliseconds

@ network.persocket.lastack how long time since the last ack received in milliseconds

@ network.persocket.pacing_rate the current pacing rate of the socket
The rate at which the fair queuing queuing discipline will attempt to evenly send data
when not restricted by either the congestion window or the availability of application
data.

@ network.persocket.delivery_rate delivery bandwidth estimate excluding idle periods
The recent effective delivery bandwidth of the connection to the client. This gives
an estimate of current connection performance by excluding periods when the connection
was idle due to lack of application data to send.

@ network.persocket.delivered data segments and retransmits delivered to the receiver
Data segments delivered to the receiver including retransmits, as reported by
returning ACKs, used by ECN. Kernel: delivered in include/linux/tcp.h

@ network.persocket.app_limited TCP flows are limited with application-limiting

@ network.persocket.reord_seen received ACKs that were out of order
Received ACKs that were out of order. Estimates reordering on the
return path. Kernel: reord_seen

@ network.persocket.busy TCP connection is busy??

@ network.persocket.dsack_dups duplicate selective acknowledgements

@ network.persocket.rcv_rtt receive round trip time

@ network.persocket.rcv_space TCP internal auto tuning socket receive buffer size

@ network.persocket.rcv_ssthresh TCP congestion window slow start threshold
The slow start threshold (ssthresh) determines the (de)activation of
slow start. When a new connection is made, cwnd is initialized to one
TCP data or acknowledgment packet, and waits for an acknowledgement,
or ACK. Slow start also terminates when congestion is experienced.

@ network.persocket.minrtt minimum round trip time achieved in the socket

@ network.persocket.notsent unsent data bytes that are still buffered

@ network.persocket.timer.str the 'timer:' string, as reported by ss
Format is <timer_name>,<expire_time>,<retrans>. See also network.persocket.timer.name,
network.persocket.timer.expire_str and network.persocket.timer.retrans.

@ network.persocket.timer.name name of the socket timer.

on : means one of these timers: TCP retrans timer, TCP early retrans
timer and tail loss probe timer

keepalive: tcp keep alive timer

timewait: timewait stage timer

persist: zero window probe timer

unknown: none of the above timers

@ network.persocket.timer.expire_str how long until the timer will expire
Currently only exported as a string.

@ network.persocket.timer.retrans how many times the retransmission occured in timer

@ network.persocket.skmem.str socket memory details, as a string
The format is r<rmem_alloc>,rb<rcv_buf>,t<wmem_alloc>,tb<snd_buf>,
f<fwd_alloc>,w<wmem_queued>,o<opt_mem>, bl<back_log>,d<sock_drop>

For details, see also network.persocket.skmem.rmem_alloc, network.persocket.skmem.wmem_alloc,
network.persocket.skmem.rcv_buf, network.persocket.skmem.snd_buf, network.persocket.skmem.fwd_alloc,
network.persocket.skmem.wmem_queued, network.persocket.skmem.ropt_mem, network.persocket.skmem.back_log,
network.persocket.skmem.sock_drop.

@ network.persocket.skmem.rmem_alloc memory allocated for receiving packet

@ network.persocket.skmem.wmem_alloc memory used for sending packet (which has been sent
Memory used for sending packet (which has been sent to layer 3)

@ network.persocket.skmem.rcv_buf total memory that can be allocated to recv packets

@ network.persocket.skmem.snd_buf total memory that can be allocated to send packets

@ network.persocket.skmem.fwd_alloc cache memory allocated but not yet used for snd/rcv
The memory allocated by the socket as cache, but not used for receiving
or sending packet yet. If need memory to send/receive packet, the memory
in this cache will be used before allocate additional memory.

@ network.persocket.skmem.wmem_queued memory allocated for sending packet
The memory allocated for sending packet (which has not been sent to layer 3)

@ network.persocket.skmem.ropt_mem memory used for storing socket options
The memory used for storing socket option, e.g., the key for
TCP MD5 signature

@ network.persocket.skmem.back_log memory used for the sk backlog queue
The memory used for the sk backlog queue. On a process context, if the
process is receiving packet, and a new packet is received, it will be
put into the sk backlog queue, so it can be received by the process
immediately.

@ network.persocket.skmem.sock_drop dropped packets before demultiplexed into socket
The number of packets dropped before they are demultiplexed into the socket.

@ network.persocket.wscale.str send and rcv scale factor as a string
If the window scale option is used, this field shows the send scale
factor and receive scale factor as a string <snd_wscale>:<rcv_wscale>.

See also network.persocket.wscale.snd and network.persocket.wscale.rcv.

@ network.persocket.wscale.snd send scale factor when window scale is used

@ network.persocket.wscale.rcv receive scale factor when window scale is used

@ network.persocket.round_trip.str average round trip time and variance, as a string
String value of the average round trip time and the mean deviation of rtt,
both in milliseconds.

See also network.persocket.round_trip.rtt and network.persocket.round_trip.rttvar

@ network.persocket.round_trip.rtt average round trip time in milliseconds
See also network.persocket.round_trip.str and network.persocket.round_trip.rttvar

@ network.persocket.round_trip.rttvar round trip time mean deviation.
See also network.persocket.round_trip.str and network.persocket.round_trip.rtt.
