Skip to content

Commit ec52414

Browse files
kbatuigaskbatuigas
authored
[25.3] Add rpk cluster connections list examples (#1431)
1 parent 18f2340 commit ec52414

4 files changed

Lines changed: 94 additions & 168 deletions

File tree

‎modules/get-started/pages/release-notes/redpanda.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ This topic includes new content added in version {page-component-version}. For a
99
1010
== Connected client monitoring
1111

12-
You can view details about Kafka client connections using the Admin API ListKafkaConnections endpoint. This allows you to view detailed information about about active client connections on a cluster, and identify and troubleshoot problematic clients. For more information, see xref:manage:monitoring.adoc#identify-high-throughput-clients[Monitor Redpanda].
12+
You can view details about Kafka client connections using `rpk` or the Admin API ListKafkaConnections endpoint. This allows you to view detailed information about active client connections on a cluster, and identify and troubleshoot problematic clients. For more information, see xref:manage:monitoring.adoc#identify-high-throughput-clients[Monitor Redpanda].
1313

1414
== New Admin API endpoints
1515

‎modules/manage/pages/cluster-maintenance/configure-client-connections.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ ifndef::env-cloud[]
1515
====
1616
Before you configure connection limits or reconnection settings, start by gathering detailed data about your client connections.
1717

18-
* Internal metrics that follow the `vectorized_kafka_rpc_.*connect.*` naming pattern provide details on Kafka client connection activity. For example, xref:reference:internal-metrics-reference.adoc#vectorized_kafka_rpc_active_connections[`vectorized_kafka_rpc_active_connections`] reports the current number of active connections.
19-
* For Redpanda v25.3 and later, use the Admin API ListKafkaConnections endpoint to identify:
18+
* Internal metrics that follow the `vectorized_kafka_rpc_.\*connect.*` naming pattern provide details on Kafka client connection activity. For example, xref:reference:internal-metrics-reference.adoc#vectorized_kafka_rpc_active_connections[`vectorized_kafka_rpc_active_connections`] reports the current number of active connections.
19+
* For Redpanda v25.3 and later, use `rpk cluster connections list` or the Admin API ListKafkaConnections endpoint to identify:
2020
+
2121
--
2222
** Which clients and applications are connected

‎modules/manage/pages/cluster-maintenance/manage-throughput.adoc‎

Lines changed: 67 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,38 @@ endif::[]
2121

2222
You may find it helpful to check the xref:{monitor-doc}[current produce and consume throughput] of a client before you configure throughput quotas.
2323

24-
Use the Admin API link:/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections[ListKafkaConnections] endpoint to view detailed information about active Kafka client connections. For example, to view a cluster's connected clients in order of highest current produce throughput, you can use the following request:
24+
Use the `rpk cluster connections list` command or the link:/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections[ListKafkaConnections] Admin API endpoint to view detailed information about active Kafka client connections.
2525

26+
For example, to view a cluster's connected clients in order of highest current produce throughput, run:
27+
28+
[tabs]
29+
======
30+
rpk::
31+
+
32+
--
33+
[,bash]
34+
----
35+
rpk cluster connections list --order-by="recent_request_statistics.produce_bytes desc"
36+
----
37+
38+
[,bash,role="no-copy no-wrap"]
39+
----
40+
UID STATE USER CLIENT-ID IP:PORT NODE SHARD OPEN-TIME IDLE PROD-TPUT/SEC FETCH-TPUT/SEC REQS/MIN
41+
b20601a3-624c-4a8c-ab88-717643f01d56 OPEN UNAUTHENTICATED perf-producer-client 127.0.0.1:55012 0 0 9s 0s 78.9MB 0B 292
42+
36338ca5-86b7-4478-ad23-32d49cfaef61 OPEN UNAUTHENTICATED rpk 127.0.0.1:49722 0 0 13s 13.694243104s 0B 0B 1
43+
7e277ef6-0176-4007-b100-6581bfde570f OPEN UNAUTHENTICATED rpk 127.0.0.1:49736 0 0 13s 10.093957335s 0B 0B 2
44+
567d9918-d3dc-4c74-ab5d-85f70cd3ee35 OPEN UNAUTHENTICATED rpk 127.0.0.1:49748 0 0 13s 0.591413542s 0B 0B 5
45+
08616f21-08f9-46e7-8f06-964bd8240d9b OPEN UNAUTHENTICATED rpk 127.0.0.1:49764 0 0 13s 10.094602845s 0B 0B 2
46+
e4d5b57e-5c76-4975-ada8-17a88d68a62d OPEN UNAUTHENTICATED rpk 127.0.0.1:54992 0 0 10s 0.302090085s 0B 14.5MB 27
47+
b41584f3-2662-4185-a4b8-0d8510f5c780 OPEN UNAUTHENTICATED perf-producer-client 127.0.0.1:55002 0 0 8s 7.743592270s 0B 0B 1
48+
62fde947-411d-4ea8-9461-3becc2631b46 CLOSED UNAUTHENTICATED rpk 127.0.0.1:48578 0 0 26s 0.000737836s 0B 0B 1
49+
95387e2e-2ec4-4040-aa5e-4257a3efa1a2 CLOSED UNAUTHENTICATED rpk 127.0.0.1:48564 0 0 26s 0.208180826s 0B 0B 1
50+
----
51+
--
52+
53+
curl::
54+
+
55+
--
2656
[,bash]
2757
----
2858
curl -s -X POST \
@@ -34,10 +64,10 @@ curl -s -X POST \
3464
"localhost:9644/redpanda.core.admin.v2.ClusterService/ListKafkaConnections"
3565
----
3666
37-
The response lists each connection's details:
38-
39-
.Show sample response
40-
[,json,lines=54+103+153]
67+
.Show example API response
68+
[%collapsible]
69+
====
70+
[,json,role=no-copy,lines=54]
4171
----
4272
{
4373
"connections": [
@@ -98,113 +128,38 @@ The response lists each connection's details:
98128
"produceBatchCount": "4849"
99129
}
100130
},
101-
{
102-
"nodeId": 0,
103-
"shardId": 0,
104-
"uid": "36338ca5-86b7-4478-ad23-32d49cfaef61",
105-
"state": "KAFKA_CONNECTION_STATE_OPEN",
106-
"openTime": "2025-10-15T14:15:09.801571000Z",
107-
"closeTime": "1970-01-01T00:00:00.000000000Z",
108-
"authenticationInfo": {
109-
"state": "AUTHENTICATION_STATE_UNAUTHENTICATED",
110-
"mechanism": "AUTHENTICATION_MECHANISM_UNSPECIFIED",
111-
"userPrincipal": ""
112-
},
113-
"listenerName": "",
114-
"tlsInfo": {
115-
"enabled": false
116-
},
117-
"source": {
118-
"ipAddress": "127.0.0.1",
119-
"port": 49722
120-
},
121-
"clientId": "rpk",
122-
"clientSoftwareName": "kgo",
123-
"clientSoftwareVersion": "unknown",
124-
"transactionalId": "",
125-
"groupId": "",
126-
"groupInstanceId": "",
127-
"groupMemberId": "",
128-
"apiVersions": {
129-
"18": 4,
130-
"3": 12
131-
},
132-
"idleDuration": "13.694243104s",
133-
"inFlightRequests": {
134-
"sampledInFlightRequests": [],
135-
"hasMoreRequests": false
136-
},
137-
"totalRequestStatistics": {
138-
"produceBytes": "0",
139-
"fetchBytes": "0",
140-
"requestCount": "2",
141-
"produceBatchCount": "0"
142-
},
143-
"recentRequestStatistics": {
144-
"produceBytes": "0",
145-
"fetchBytes": "0",
146-
"requestCount": "2",
147-
"produceBatchCount": "0"
148-
}
149-
},
150-
{
151-
"nodeId": 0,
152-
"shardId": 0,
153-
"uid": "7e277ef6-0176-4007-b100-6581bfde570f",
154-
"state": "KAFKA_CONNECTION_STATE_OPEN",
155-
"openTime": "2025-10-15T14:15:09.804034000Z",
156-
"closeTime": "1970-01-01T00:00:00.000000000Z",
157-
"authenticationInfo": {
158-
"state": "AUTHENTICATION_STATE_UNAUTHENTICATED",
159-
"mechanism": "AUTHENTICATION_MECHANISM_UNSPECIFIED",
160-
"userPrincipal": ""
161-
},
162-
"listenerName": "",
163-
"tlsInfo": {
164-
"enabled": false
165-
},
166-
"source": {
167-
"ipAddress": "127.0.0.1",
168-
"port": 49736
169-
},
170-
"clientId": "rpk",
171-
"clientSoftwareName": "kgo",
172-
"clientSoftwareVersion": "unknown",
173-
"transactionalId": "",
174-
"groupId": "",
175-
"groupInstanceId": "",
176-
"groupMemberId": "",
177-
"apiVersions": {
178-
"18": 4,
179-
"3": 12,
180-
"10": 4
181-
},
182-
"idleDuration": "10.093957335s",
183-
"inFlightRequests": {
184-
"sampledInFlightRequests": [],
185-
"hasMoreRequests": false
186-
},
187-
"totalRequestStatistics": {
188-
"produceBytes": "0",
189-
"fetchBytes": "0",
190-
"requestCount": "4",
191-
"produceBatchCount": "0"
192-
},
193-
"recentRequestStatistics": {
194-
"produceBytes": "0",
195-
"fetchBytes": "0",
196-
"requestCount": "4",
197-
"produceBatchCount": "0"
198-
}
199-
},
200131
...
201132
]
202133
"totalSize": "9"
203134
}
204135
----
136+
====
137+
--
138+
======
205139

206140
To view connections for a specific client, you can use a filter expression:
207141

142+
[tabs]
143+
======
144+
rpk::
145+
+
146+
--
147+
[,bash]
148+
----
149+
rpk cluster connections list --client-id="perf-producer-client"
150+
----
151+
152+
[,bash,role="no-copy no-wrap"]
153+
----
154+
UID STATE USER CLIENT-ID IP:PORT NODE SHARD OPEN-TIME IDLE PROD-TPUT/SEC FETCH-TPUT/SEC REQS/MIN
155+
b41584f3-2662-4185-a4b8-0d8510f5c780 OPEN UNAUTHENTICATED perf-producer-client 127.0.0.1:55002 0 0 8s 7.743592270s 0B 0B 1
156+
b20601a3-624c-4a8c-ab88-717643f01d56 OPEN UNAUTHENTICATED perf-producer-client 127.0.0.1:55012 0 0 9s 0s 78.9MB 0B 292
157+
----
158+
--
159+
160+
curl::
161+
+
162+
--
208163
[,bash]
209164
----
210165
curl -s -X POST \
@@ -215,8 +170,10 @@ curl -s -X POST \
215170
"localhost:9644/redpanda.core.admin.v2.ClusterService/ListKafkaConnections"
216171
----
217172
218-
.Show sample response
219-
[,json,lines=23+73+123]
173+
.Show example API response
174+
[%collapsible]
175+
====
176+
[,json,lines=24]
220177
----
221178
{
222179
"connections": [
@@ -270,67 +227,14 @@ curl -s -X POST \
270227
"produceBatchCount": "0"
271228
}
272229
},
273-
{
274-
"nodeId": 0,
275-
"shardId": 0,
276-
"uid": "b20601a3-624c-4a8c-ab88-717643f01d56",
277-
"state": "KAFKA_CONNECTION_STATE_OPEN",
278-
"openTime": "2025-10-15T14:15:15.755065000Z",
279-
"closeTime": "1970-01-01T00:00:00.000000000Z",
280-
"authenticationInfo": {
281-
"state": "AUTHENTICATION_STATE_UNAUTHENTICATED",
282-
"mechanism": "AUTHENTICATION_MECHANISM_UNSPECIFIED",
283-
"userPrincipal": ""
284-
},
285-
"listenerName": "",
286-
"tlsInfo": {
287-
"enabled": false
288-
},
289-
"source": {
290-
"ipAddress": "127.0.0.1",
291-
"port": 55012
292-
},
293-
"clientId": "perf-producer-client",
294-
"clientSoftwareName": "apache-kafka-java",
295-
"clientSoftwareVersion": "3.9.0",
296-
"transactionalId": "my-tx-id",
297-
"groupId": "",
298-
"groupInstanceId": "",
299-
"groupMemberId": "",
300-
"apiVersions": {
301-
"18": 4,
302-
"22": 3,
303-
"3": 12,
304-
"24": 3,
305-
"0": 7
306-
},
307-
"idleDuration": "0s",
308-
"inFlightRequests": {
309-
"sampledInFlightRequests": [
310-
{
311-
"apiKey": 0,
312-
"inFlightDuration": "0.000406892s"
313-
}
314-
],
315-
"hasMoreRequests": false
316-
},
317-
"totalRequestStatistics": {
318-
"produceBytes": "78927173",
319-
"fetchBytes": "0",
320-
"requestCount": "4853",
321-
"produceBatchCount": "4849"
322-
},
323-
"recentRequestStatistics": {
324-
"produceBytes": "78927173",
325-
"fetchBytes": "0",
326-
"requestCount": "4853",
327-
"produceBatchCount": "4849"
328-
}
329-
}
230+
...
330231
],
331232
"totalSize": "2"
332233
}
333234
----
235+
====
236+
--
237+
======
334238

335239

336240
== Throughput throttling enforcement

‎modules/manage/partials/monitor-health.adoc‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -129,10 +129,30 @@ rate(redpanda_rpc_sent_bytes{redpanda_server="kafka"}[$__rate_interval])
129129
ifndef::env-cloud[]
130130
==== Identify high-throughput clients
131131

132-
Use the ListKafkaConnections service in Admin API to identify which client connections are driving the majority of, or the change in, the produce or consume throughput for a cluster.
132+
Use `rpk cluster connections list` or the ListKafkaConnections service in Admin API to identify which client connections are driving the majority of, or the change in, the produce or consume throughput for a cluster.
133133

134-
For example, to list connections with a current produce throughput greater than 1MB, use the following request:
134+
For example, to list connections with a current produce throughput greater than 1MB, run:
135135

136+
[tabs]
137+
======
138+
rpk::
139+
+
140+
--
141+
[,bash]
142+
----
143+
rpk cluster connections list --filter-raw="recent_request_statistics.produce_bytes > 1000000" --order-by="recent_request_statistics.produce_bytes desc"
144+
----
145+
146+
[,bash,role="no-copy no-wrap"]
147+
----
148+
UID STATE USER CLIENT-ID IP:PORT NODE SHARD OPEN-TIME IDLE PROD-TPUT/SEC FETCH-TPUT/SEC REQS/MIN
149+
b20601a3-624c-4a8c-ab88-717643f01d56 OPEN UNAUTHENTICATED perf-producer-client 127.0.0.1:55012 0 0 9s 0s 78.9MB 0B 292
150+
----
151+
--
152+
153+
curl::
154+
+
155+
--
136156
[,bash]
137157
----
138158
curl -s -X POST "localhost:9644/redpanda.core.admin.v2.ClusterService/ListKafkaConnections" --header "Content-Type: application/json" --data '{"filter":"recent_request_statistics.produce_bytes > 1000000", "order_by":"recent_request_statistics.produce_bytes desc"}' | jq
@@ -206,6 +226,8 @@ curl -s -X POST "localhost:9644/redpanda.core.admin.v2.ClusterService/ListKafkaC
206226
}
207227
----
208228
====
229+
--
230+
======
209231

210232
You can adjust the filter and sorting criteria as necessary. See the link:/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections[Admin API reference] for more details.
211233
endif::[]

0 commit comments

Comments
 (0)