prometheus / prometheus/node_exporter
Incorrect help text for sockstat metrics
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 13.8k
- Forks
- 2.7k
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 8
Description
I've removed the usual bug report boilerplate because it doesn't seem necessary in this case. I hope that's OK.
Here is the current output of the sockstat metrics:
# HELP node_sockstat_FRAG_inuse Number of FRAG sockets in state inuse.
# TYPE node_sockstat_FRAG_inuse gauge
node_sockstat_FRAG_inuse 0
# HELP node_sockstat_FRAG_memory Number of FRAG sockets in state memory.
# TYPE node_sockstat_FRAG_memory gauge
node_sockstat_FRAG_memory 0
# HELP node_sockstat_RAW_inuse Number of RAW sockets in state inuse.
# TYPE node_sockstat_RAW_inuse gauge
node_sockstat_RAW_inuse 0
# HELP node_sockstat_TCP_alloc Number of TCP sockets in state alloc.
# TYPE node_sockstat_TCP_alloc gauge
node_sockstat_TCP_alloc 17
# HELP node_sockstat_TCP_inuse Number of TCP sockets in state inuse.
# TYPE node_sockstat_TCP_inuse gauge
node_sockstat_TCP_inuse 4
# HELP node_sockstat_TCP_mem Number of TCP sockets in state mem.
# TYPE node_sockstat_TCP_mem gauge
node_sockstat_TCP_mem 1
# HELP node_sockstat_TCP_mem_bytes Number of TCP sockets in state mem_bytes.
# TYPE node_sockstat_TCP_mem_bytes gauge
node_sockstat_TCP_mem_bytes 4096
# HELP node_sockstat_TCP_orphan Number of TCP sockets in state orphan.
# TYPE node_sockstat_TCP_orphan gauge
node_sockstat_TCP_orphan 0
# HELP node_sockstat_TCP_tw Number of TCP sockets in state tw.
# TYPE node_sockstat_TCP_tw gauge
node_sockstat_TCP_tw 4
Note that several are of the form: Number of TCP sockets in state <xxx>, including mem, which is neither a socket state nor a number of sockets, and mem_bytes which is definitely neither of those.
This is really unhelpful ('# UNHELPFUL) in understanding what these metrics actually are.
Now, from digging around, it seems that the output of sockstat isn't documented at all. Instead, people have to resort to reading the kernel source, which is a pretty sorry state to be in. But, we do have some clues:
- https://serverfault.com/questions/628635/what-is-the-unit-of-mem-and-memory-in-proc-net-sockstat
- https://www.unix.com/302388593-post4.html
mem values for TCP and UDP are in kernel pages, while the memory value in FRAG is in bytes
the mem parameters for TCP and UDP is the number of kernel pages allocated. However, the memory parameter of FRAG seems to be the memory allocated bytes for fragmentation re-assembly
Now, I don't know what fragmentation re-assembly means, and I don't even know what the FRAG part of the output means. But we can at least label the units correctly!
# HELP node_sockstat_FRAG_memory Number of allocated bytes for <whatever this is>
# HELP node_sockstat_TCP_mem Number of kernel pages allocated
Similarly, state tw is very unhelpful. Please consider labelling with the more useful state TIME_WAIT. In fact, all the states could use some translation to make it more user friendly.
Sorry this if this is a bit of an unsatisfying issue. I wish I had the answers to help write better messages, but at the moment I'm trying to figure out what this all means!
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the current sockstat metric output and the Linux /proc/net/sockstat documentation or kernel source referenced in the issue. Determine the meanings and units of the fields, including FRAG, mem, mem_bytes, and abbreviated TCP states. Done means the exported help text and state labels accurately describe the metrics and their units.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, linux
- Domain
- observability-sre, operating-systems
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100