io-metrics 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50d4b28faec3b5ae9389c3437d1e5687c1e54229d0abfd79305699e3f43e798b
-  data.tar.gz: 33db46c67476acedd0ee7695d437679ffe8e3602f60de2d15363e9b59423aab6
+  metadata.gz: ef189b6c38ef215409837bfe6d596116856ee48177fe67c63f6926f32e58e611
+  data.tar.gz: a62a323790464b1ef965cfbf1ff1aba63e329e025f0f3b0b93696a809aa7095a
 SHA512:
-  metadata.gz: 4131cbf7a3d8d15256972f057c24608ac1f9a72e958a6361ef24e36ceb97f669767e80dfc309d9c39df6d8aa530d10f82d93d9e53a61f7e6d2b1a47e16568434
-  data.tar.gz: b3c5ae946df3a0f7d1fe59d787f91aa0faf95c2f8b8353a2b132576325f033c3e7819613923b5ba79fe87e153424591fa66f3f1cfbc6030592bfa2d44e39619d
+  metadata.gz: b763b526aa7e8e82428206ba4b0a7d652fa3dd89ba4f3d8a0db7677af8c4e19171d459d6fd750f0b2f43aa3ac99461821c6f6fae61f1ac9c5024a569bb4af6ec
+  data.tar.gz: 79e05df4f9d528c29cc1030c59623efeb6b3147f029e6361133e1a5e0660fc9a46a78d8ff7baa5026bc2db892a8ac29bbfe99b6a310314bfaa96a84fd144e02b

data/lib/io/metrics/listener/darwin.rb

@@ -33,12 +33,14 @@ class IO
 					return Addrinfo.tcp(ip, port)
 				end
 				
-				# Handle IPv6 or other formats: best-effort via Addrinfo.parse
-				begin
-					Addrinfo.parse(address)
-				rescue ArgumentError, SocketError
-					nil
+				# Handle IPv6: [::1].8080, [fe80::1%lo0].8080, [::].8080
+				if address =~ /\A\[([^\]]+)\]\.(\d+)\z/
+					ip = $1.sub(/%.*\z/, "")  # strip zone ID (e.g. %lo0)
+					port = $2.to_i
+					return Addrinfo.tcp(ip, port)
 				end
+				
+				nil
 			end
 			
 			# Build a stable string key for TCP listener filter matching (same style as Linux / user filters).
@@ -83,10 +85,12 @@ class IO
 							# Apply filter if specified
 							next if address_filter && !address_filter.include?(key.downcase)
 							
-							listeners[key] ||= Listener.new(addrinfo, 0, 0)
-							listeners[key].queue_size = queue_length
-							# active_connections set to 0 (can't reliably count per listener)
-							listeners[key].active_connections = 0
+							listeners[key] ||= Listener.new(addrinfo, 0, 0, 0, 0, 0)
+							listeners[key].queued_count = queue_length
+							
+							# active_count and close_wait_count set to 0 (netstat -L doesn't expose connection states)
+							listeners[key].active_count = 0
+							listeners[key].close_wait_count = 0
 						end
 					end
 				end

data/lib/io/metrics/listener/linux.rb

@@ -161,8 +161,11 @@ class IO
 				listeners = {}
 				address_filter = addresses ? addresses.map{|address| address.downcase}.to_set : nil
 				connections = []
+				close_wait_connections = []
+				fin_wait_connections = []
+				time_wait_connections = []
 				
-				# Single pass: collect LISTEN sockets and ESTABLISHED connections
+				# Single pass: collect LISTEN sockets and tracked connection states.
 				File.foreach(file) do |line|
 					next if line.start_with?("sl")
 					
@@ -192,13 +195,16 @@ class IO
 							# Apply filter if specified
 							next if address_filter && !address_filter.include?(local_address.downcase)
 							
-							listeners[local_address] ||= Listener.new(Addrinfo.tcp(local_ip, local_port), 0, 0)
-						# rx_queue shows number of connections waiting to be accepted.
-						# Accumulate across SO_REUSEPORT sockets sharing the same address.
-						listeners[local_address].queue_size += rx_queue_hex.to_i(16)
-							listeners[local_address].active_connections = 0
-						# Collect ESTABLISHED connections to count later
-						elsif state == :established
+							listeners[local_address] ||= Listener.new(Addrinfo.tcp(local_ip, local_port), 0, 0, 0, 0, 0)
+							# rx_queue shows number of connections waiting to be accepted.
+							# Accumulate across SO_REUSEPORT sockets sharing the same address.
+							listeners[local_address].queued_count += rx_queue_hex.to_i(16)
+							listeners[local_address].active_count = 0
+							listeners[local_address].close_wait_count = 0
+							listeners[local_address].fin_wait_count = 0
+							listeners[local_address].time_wait_count = 0
+						elsif state == :established || state == :close_wait ||
+								state == :fin_wait1 || state == :fin_wait2 || state == :time_wait
 							if ipv6
 								local_ip = parse_ipv6(local_ip_hex)
 								local_address = "[#{local_ip}]:#{parse_port(local_port_hex)}"
@@ -207,24 +213,58 @@ class IO
 								local_port = parse_port(local_port_hex)
 								local_address = "#{local_ip}:#{local_port}"
 							end
-							connections << local_address
+							case state
+							when :established            then connections << local_address
+							when :close_wait             then close_wait_connections << local_address
+							when :fin_wait1, :fin_wait2  then fin_wait_connections << local_address
+							when :time_wait              then time_wait_connections << local_address
+							end
 						end
 					end
 				end
 				
-				# Count ESTABLISHED connections for each listener
+				# Count ESTABLISHED connections for each listener.
 				connections.each do |local_address|
 					if listener_address = find_matching_listener(local_address, listeners)
-						listeners[listener_address].active_connections += 1
+						listeners[listener_address].active_count += 1
+					end
+				end
+				
+				# Count CLOSE_WAIT connections for each listener.
+				# Peer has closed its end; application still holds the socket
+				# (e.g. running rack.response_finished callbacks).
+				close_wait_connections.each do |local_address|
+					if listener_address = find_matching_listener(local_address, listeners)
+						listeners[listener_address].close_wait_count += 1
+					end
+				end
+				
+				# Count FIN_WAIT1 + FIN_WAIT2 connections for each listener.
+				# Server has sent FIN (initiated close), waiting for peer to finish closing.
+				# FIN_WAIT1 is extremely brief (ACK in transit); FIN_WAIT2 persists until
+				# the peer sends its FIN — both represent the same "server-initiated close" phase.
+				fin_wait_connections.each do |local_address|
+					if listener_address = find_matching_listener(local_address, listeners)
+						listeners[listener_address].fin_wait_count += 1
+					end
+				end
+				
+				# Count TIME_WAIT connections for each listener.
+				# Both sides have closed; the kernel holds the socket for ~60s (2×MSL) to
+				# absorb delayed packets. These consume file descriptors but represent no
+				# active work. High counts indicate fast connection churn.
+				time_wait_connections.each do |local_address|
+					if listener_address = find_matching_listener(local_address, listeners)
+						listeners[listener_address].time_wait_count += 1
 					end
 				end
 				
 				# /proc lists every ESTABLISHED child with the listener's local address, including
-				# sockets still in the accept queue. Those are already counted in queue_size on the
+				# sockets still in the accept queue. Those are already counted in queued_count on the
 				# LISTEN row (same meaning as Raindrops inet_diag queued vs inode != 0 for active).
 				listeners.each_value do |listener|
-					backlog = listener.queue_size
-					listener.active_connections = [listener.active_connections - backlog, 0].max
+					backlog = listener.queued_count
+					listener.active_count = [listener.active_count - backlog, 0].max
 				end
 				
 				return listeners
@@ -263,13 +303,13 @@ class IO
 					
 					state = state_hex.to_i(16)
 					
-					listeners[path] ||= Listener.new(Addrinfo.unix(path), 0, 0)
+					listeners[path] ||= Listener.new(Addrinfo.unix(path), 0, 0, 0, 0, 0)
 					
 					case state
 					when SS_CONNECTING # Queued connections
-						listeners[path].queue_size += 1
+						listeners[path].queued_count += 1
 					when SS_CONNECTED # Active connections
-						listeners[path].active_connections += 1
+						listeners[path].active_count += 1
 					end
 				end
 				

data/lib/io/metrics/listener.rb

@@ -7,17 +7,24 @@ require "json"
 
 class IO
 	module Metrics
+		# Represents a network listener socket with its queue statistics.
 		# Represents a network listener socket with its queue statistics.
 		# @attribute address [Addrinfo | Nil] Listening endpoint from capture; nil only for {Listener.zero} placeholders.
-		# @attribute queue_size [Integer] Number of connections waiting to be accepted (queued).
-		# @attribute active_connections [Integer] Number of active connections (already accepted).
-		class Listener < Struct.new(:address, :queue_size, :active_connections)
+		# @attribute queued_count [Integer] Number of connections waiting to be accepted (currently in the accept queue).
+		# @attribute active_count [Integer] Number of accepted connections in ESTABLISHED state.
+		# @attribute close_wait_count [Integer] Number of connections in CLOSE_WAIT state (peer has closed; application still holds the socket).
+		# @attribute fin_wait_count [Integer] Number of connections in FIN_WAIT1 or FIN_WAIT2 state (server has initiated close; peer has not yet completed close).
+		# @attribute time_wait_count [Integer] Number of connections in TIME_WAIT state (both sides closed; waiting ~60s for delayed packets before releasing the port/fd).
+		class Listener < Struct.new(:address, :queued_count, :active_count, :close_wait_count, :fin_wait_count, :time_wait_count)
 			# Serialize for JSON; address uses Addrinfo#inspect_sockaddr.
 			def as_json(*)
 				{
 					address: address&.inspect_sockaddr,
-					queue_size: queue_size,
-					active_connections: active_connections,
+					queued_count: queued_count,
+					active_count: active_count,
+					close_wait_count: close_wait_count,
+					fin_wait_count: fin_wait_count,
+					time_wait_count: time_wait_count,
 				}
 			end
 			
@@ -29,7 +36,7 @@ class IO
 			# Create a zero-initialized Listener instance (no endpoint; for tests or templates).
 			# @returns [Listener] Counters zero; {#address} is nil.
 			def self.zero
-				new(nil, 0, 0)
+				new(nil, 0, 0, 0, 0, 0)
 			end
 			
 			# Whether listener stats can be captured on this system.

data/lib/io/metrics/version.rb

@@ -7,6 +7,6 @@
 class IO
 	# @namespace
 	module Metrics
-		VERSION = "0.2.1"
+		VERSION = "0.4.0"
 	end
 end

data/readme.md

@@ -14,6 +14,17 @@ Please see the [project documentation](https://socketry.github.io/io-metrics/) f
 
 Please see the [project releases](https://socketry.github.io/io-metrics/releases/index) for all releases.
 
+### v0.4.0
+
+  - Introduce `Listener#fin_wait_count`: connections in `FIN_WAIT1` or `FIN_WAIT2` state — server has sent FIN (initiated close) and is waiting for the peer to finish closing. Symmetric counterpart to `close_wait_count`.
+  - Introduce `Listener#time_wait_count`: connections in `TIME_WAIT` state — both sides have closed; the kernel holds the socket for \~60s (2×MSL) to absorb delayed packets. High counts indicate fast connection churn.
+  - Fix `parse_address` for IPv6 listeners: replace non-existent `Addrinfo.parse` with an explicit `[ipv6addr].port` pattern match.
+
+### v0.3.0
+
+  - **Breaking** Rename `Listener` fields: `queue_size` → `queued_count`, `active_connections` → `active_count`.
+  - Introduce `Listener#close_wait_count`: number of accepted connections in `CLOSE_WAIT` state (peer has closed; application still processing).
+
 ### v0.2.1
 
   - Fixed `queue_size` under-reporting when multiple `SO_REUSEPORT` sockets share the same address — queue depths are now accumulated across all sockets rather than overwritten by the last one.

data/releases.md

@@ -1,5 +1,16 @@
 # Releases
 
+## v0.4.0
+
+  - Introduce `Listener#fin_wait_count`: connections in `FIN_WAIT1` or `FIN_WAIT2` state — server has sent FIN (initiated close) and is waiting for the peer to finish closing. Symmetric counterpart to `close_wait_count`.
+  - Introduce `Listener#time_wait_count`: connections in `TIME_WAIT` state — both sides have closed; the kernel holds the socket for \~60s (2×MSL) to absorb delayed packets. High counts indicate fast connection churn.
+  - Fix `parse_address` for IPv6 listeners: replace non-existent `Addrinfo.parse` with an explicit `[ipv6addr].port` pattern match.
+
+## v0.3.0
+
+  - **Breaking** Rename `Listener` fields: `queue_size` → `queued_count`, `active_connections` → `active_count`.
+  - Introduce `Listener#close_wait_count`: number of accepted connections in `CLOSE_WAIT` state (peer has closed; application still processing).
+
 ## v0.2.1
 
   - Fixed `queue_size` under-reporting when multiple `SO_REUSEPORT` sockets share the same address — queue depths are now accumulated across all sockets rather than overwritten by the last one.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-metrics
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Samuel Williams