io-metrics 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7f07281a060f8644b5f50c62d526bfca3ea15ecb8a63001192f617b0aa7690d
-  data.tar.gz: ae6e4568aeae519c4e69643cc60a9203e0549408db787148b035151462a12819
+  metadata.gz: ef189b6c38ef215409837bfe6d596116856ee48177fe67c63f6926f32e58e611
+  data.tar.gz: a62a323790464b1ef965cfbf1ff1aba63e329e025f0f3b0b93696a809aa7095a
 SHA512:
-  metadata.gz: 69bc0a438888c3f4a58790d53aa09919110e7c538c6cbdbf04165c2c6472043a47844b5b61a5d8db61df739289ea806c7f906422c734a0a3a0f3c727b7756624
-  data.tar.gz: a3a052adb78a2d63276282795ffc9c2d3d691f5afc7dbc2313a9fe528a1f4ee5d82157b050aef6514d52b6cf8025ff4c3344d59df41782653916bbc3491069c2
+  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,7 +85,7 @@ class IO
 							# Apply filter if specified
 							next if address_filter && !address_filter.include?(key.downcase)
 							
-							listeners[key] ||= Listener.new(addrinfo, 0, 0, 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)

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

@@ -162,8 +162,10 @@ class IO
 				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, ESTABLISHED, and CLOSE_WAIT connections
+				# Single pass: collect LISTEN sockets and tracked connection states.
 				File.foreach(file) do |line|
 					next if line.start_with?("sl")
 					
@@ -193,14 +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, 0)
+							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
-						# Collect ESTABLISHED and CLOSE_WAIT connections to count later
-						elsif state == :established || state == :close_wait
+							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)}"
@@ -209,16 +213,17 @@ class IO
 								local_port = parse_port(local_port_hex)
 								local_address = "#{local_ip}:#{local_port}"
 							end
-							if state == :established
-								connections << local_address
-							else
-								close_wait_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_count += 1
@@ -226,15 +231,34 @@ class IO
 				end
 				
 				# Count CLOSE_WAIT connections for each listener.
-				# These are accepted connections where the peer has closed its end but the
-				# application has not yet closed its side (e.g. still in rack.response_finished
-				# callbacks, or processing a request whose upstream already disconnected).
+				# 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 queued_count on the
 				# LISTEN row (same meaning as Raindrops inet_diag queued vs inode != 0 for active).
@@ -279,7 +303,7 @@ class IO
 					
 					state = state_hex.to_i(16)
 					
-					listeners[path] ||= Listener.new(Addrinfo.unix(path), 0, 0, 0)
+					listeners[path] ||= Listener.new(Addrinfo.unix(path), 0, 0, 0, 0, 0)
 					
 					case state
 					when SS_CONNECTING # Queued connections

data/lib/io/metrics/listener.rb

@@ -7,12 +7,15 @@ 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 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 accepted connections in CLOSE_WAIT state (peer has closed; application still processing).
-		class Listener < Struct.new(:address, :queued_count, :active_count, :close_wait_count)
+		# @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(*)
 				{
@@ -20,6 +23,8 @@ class IO
 					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
 			
@@ -31,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, 0)  # address, queued_count, active_count, close_wait_count
+				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.3.0"
+		VERSION = "0.4.0"
 	end
 end

data/readme.md

@@ -14,6 +14,12 @@ 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`.

data/releases.md

@@ -1,5 +1,11 @@
 # 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`.

metadata

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