TCP Expert Insights

Coming Soon — V2.00: MCP integration is coming as part of Kubeshark V2.00. Read the announcement.

Kubeshark’s TCP Expert Insights give you Wireshark Expert Information for every TCP connection in your cluster — retransmissions, RTT jitter, window saturation, connection lifecycle, and goodput — all queryable by AI through MCP.

What You Can Diagnose

Network Problems

“Show me all TCP connections with retransmission rates above 5%”

“Which connections have the highest RTT jitter?”

“Find connections where rtt_max is more than 10x rtt_min — those have bufferbloat.”

Application Bottlenecks

“Find connections with zero window events — which receivers are overwhelmed?”

“Which connections have small receive windows? They may need TCP tuning.”

“Compare goodput vs total bytes for database connections — how much bandwidth is wasted on retransmissions?”

Connection Failures

“Show me connections that were reset (RST) — what’s getting forcefully terminated?”

“Find connections with incomplete handshakes — are there connectivity issues?”

Performance Analysis

“Show me connections with high initial_rtt — which network paths are slow?”

“Show TCP connections sorted by goodput — which are transferring the most useful data?”

“Find connections with high window_full_events — are we hitting buffer limits?”

How to Use

Prerequisites

Enable Dissection

POST /mcp/dissection/enable

Or ask your AI assistant: “Enable dissection and show me TCP connection health.”

Query TCP Metrics

TCP flow entries are available through the list_api_calls endpoint using the KFL filter tcp_flow:

GET /mcp/calls?kfl=tcp_flow&format=raw&limit=10

Each result represents a TCP connection with full health metrics attached in the tcp_metrics object.

Diagnostic Decision Trees

“The service is slow”

Query tcp_flow entries for the service
|
+-- initial_rtt_us > 10ms?
|   YES -> Network latency problem
|       +-- Same for all source pods? -> Destination node or path issue
|       +-- Only some sources? -> Source node or routing issue
|
+-- initial_rtt_us < 1ms but rtt_avg_us >> initial_rtt_us?
|   YES -> Bufferbloat or congestion
|       +-- High jitter_us? -> Variable queuing, check for burst traffic
|       +-- Consistently high avg? -> Sustained congestion on the path
|
+-- retransmission_rate > 5%?
|   YES -> Packet loss problem
|       +-- fast_retransmissions ~ retransmissions? -> Lossy but recovering
|       +-- fast_retransmissions << retransmissions? -> Timeout-based, severe
|
+-- zero_window_events > 0?
|   YES -> Receiver application is too slow
|       +-- Check receiver pod CPU/memory
|       +-- Application isn't reading from socket fast enough
|
+-- All metrics look normal?
    Problem is at L7 (application logic, database queries, etc.)
    Use L7 API calls to investigate

“Connections are failing”

Query tcp_flow entries for the service
|
+-- connection_completeness = 33 (SYN + RST)?
|   Connection refused -- no listener on port, or firewall blocking
|
+-- connection_completeness = 1 (SYN only)?
|   No response -- destination unreachable, network partition
|
+-- connection_completeness = 3 (SYN + SYN-ACK)?
|   Client didn't complete handshake -- client-side issue or crash
|
+-- rst_count > 0 with connection_completeness including DATA?
|   Connection reset after data transfer -- app-level rejection
|       +-- Check application logs
|       +-- May be load balancer timeout or idle connection kill
|
+-- fin_count = 1 (not 2)?
    Half-close -- one side closed but other didn't acknowledge
    Possible app crash during graceful shutdown

Metrics Reference

Every TCP connection carries a tcp_metrics object with 24 fields organized into six categories. Each metric maps directly to a Wireshark TCP Analysis feature.

Retransmission Metrics — “Are packets getting lost?”

Interpreting Retransmission Rate

Window Metrics — “Is the receiver keeping up?”

What Window Problems Tell You

• High zero_window_events: The receiver application is too slow. This is an application-level problem, not a network problem. Common cause: overloaded database, slow consumer, insufficient memory.
• High window_full_events with low zero_window_events: The receiver’s buffer is simply too small for the link’s bandwidth-delay product. May need TCP tuning.
• Low window_scale: The connection can’t use large windows. On high-bandwidth or high-latency paths, this caps throughput.

Sequence Analysis — “Are packets arriving in order?”

What Sequence Anomalies Tell You

• High out_of_order: Packets taking different network paths. Check for ECMP routing doing per-packet (instead of per-flow) load balancing, or asymmetric paths.
• High dup_acks: The receiver is seeing gaps. If fast_retransmissions is also high, the connection is recovering. If not, data may be permanently lost.
• High missing_segments: Packet loss on the wire. Correlate with retransmissions — if retransmissions are also high, TCP is recovering. If not, the capture missed the retransmissions.

Connection State — “How did the connection live and die?”

Connection Completeness Bitmask

This field uses the exact same bitmask as Wireshark:

Common Completeness Values

Latency Metrics — “How fast is the network?”

All times in microseconds (us).

Interpreting Latency

Real Example from a Live Cluster

{
  "rtt_min_us": 28,
  "rtt_max_us": 42028,
  "rtt_avg_us": 8753,
  "rtt_samples": 100,
  "jitter_us": 15707,
  "connection_completeness": 8,
  "avg_receive_window": 2776,
  "goodput_bytes": 1072387
}

Reading this: Best-case RTT is 28us (same-node, very fast), but average is 8.7ms — 300x worse — with 15.7ms jitter. connection_completeness: 8 means only DATA was observed (capture started mid-stream, handshake was missed). The small avg_receive_window (2776 bytes) suggests the receiver’s buffer is constraining throughput. This pattern points to application-side backpressure combined with variable queuing delays.

Throughput — “How efficient is the connection?”

Calculating Retransmission Overhead

Compare goodput_bytes with the flow’s local_bytes:

overhead = 1 - (goodput_bytes / local_bytes)

If goodput is 90% of total bytes, you’re losing 10% of bandwidth to retransmissions.

What’s Next

• L4 Tools — Lightweight flow visibility without dissection
• L7 Tools — Application-layer API transaction analysis
• Delayed Dissection — Analyze snapshots with L7 dissection
• Wireshark TCP Analysis Reference — The upstream documentation these metrics are based on