Skip to main content

krabka_client_admin/
telemetry.rs

1//! Client metrics push (KIP-714) of the admin client: Kafka's
2//! `enable.metrics.push` on `KafkaAdminClient`.
3//!
4//! The reporter of `krabka-client-core` sends on the admin client's current
5//! bootstrap or controller connection, and every connection of the client
6//! counts in the `admin-client-metrics` network metrics.
7
8use std::sync::Arc;
9
10use krabka_client_core::{Connection, telemetry::TelemetryConnections};
11use krabka_units::Time;
12
13use crate::{AdminClient, AdminError, RecoveringConnection};
14
15/// The connection that the admin client's reporter sends on. It has no
16/// broker id in the metadata, so the reporter sees it as `-1`, as a
17/// bootstrap connection.
18pub(crate) struct AdminTelemetryConnection(pub(crate) Arc<RecoveringConnection>);
19
20impl TelemetryConnections for AdminTelemetryConnection {
21    fn open_connection(&self, _preferred: Option<i32>) -> Option<(i32, Arc<Connection>)> {
22        // A connection that is being replaced is skipped; the reporter tries
23        // again after the reconnect backoff.
24        let connection = self.0.inner.try_read().ok()?;
25        (!connection.is_closed()).then(|| (-1, Arc::clone(&connection)))
26    }
27}
28
29impl AdminClient {
30    /// The client instance id that the broker assigned for metrics push
31    /// (KIP-714), as Kafka's `KafkaAdminClient.clientInstanceId` returns it.
32    ///
33    /// The call waits up to `timeout` for the first
34    /// `GetTelemetrySubscriptions` response. It returns `Ok(None)` when none
35    /// has come by then, as Kafka returns `null`. A zero `timeout` does not
36    /// wait.
37    ///
38    /// # Errors
39    /// Returns [`AdminError::Transport`] with
40    /// [`ClientError::InvalidArgument`] for a negative `timeout`, and with
41    /// [`ClientError::TelemetryDisabled`] when
42    /// [`AdminClientConfig::enable_metrics_push`] is `false`, as Kafka throws
43    /// an `IllegalArgumentException` and an `IllegalStateException`.
44    ///
45    /// [`ClientError::InvalidArgument`]: ClientError::InvalidArgument
46    /// [`ClientError::TelemetryDisabled`]: ClientError::TelemetryDisabled
47    /// [`AdminClientConfig::enable_metrics_push`]: crate::AdminClientConfig::enable_metrics_push
48    pub async fn client_instance_id(
49        &self,
50        timeout: Time,
51    ) -> Result<Option<uuid::Uuid>, AdminError> {
52        Ok(
53            krabka_client_core::telemetry::client_instance_id(self.telemetry.as_ref(), timeout)
54                .await?,
55        )
56    }
57
58    /// Close the client: send the terminating telemetry push (KIP-714), if
59    /// the client pushes metrics and has a subscription, and wait for it, as
60    /// Kafka's `KafkaAdminClient.close` does. The wait is at most about two
61    /// request timeouts. Dropping the client sends the push in the
62    /// background instead.
63    pub async fn close(self) {
64        if let Some(telemetry) = &self.telemetry {
65            telemetry.close().await;
66        }
67    }
68}
69
70#[cfg(test)]
71mod tests {
72    use std::time::Duration;
73
74    use assert2::assert;
75    use bytes::BytesMut;
76    use krabka_client_core::{
77        MockBroker,
78        telemetry::otlp::{MetricData, MetricsData, NumberValue},
79    };
80    use krabka_protocol::{
81        Decode, Encode,
82        owned::{
83            api_versions_request,
84            api_versions_response::{ApiVersion, ApiVersionsResponse},
85            get_telemetry_subscriptions_request::{self, GetTelemetrySubscriptionsRequest},
86            get_telemetry_subscriptions_response::GetTelemetrySubscriptionsResponse,
87            push_telemetry_request::{self, PushTelemetryRequest},
88            push_telemetry_response::PushTelemetryResponse,
89        },
90        primitives::uuid::Uuid as WireUuid,
91    };
92    use tokio::sync::mpsc;
93
94    use crate::AdminClientConfig;
95
96    const INSTANCE: WireUuid = WireUuid([7; 16]);
97    const CONNECTION_COUNT: &str = "org.apache.kafka.admin.client.connection.count";
98
99    /// A telemetry request that the broker received. A push holds each
100    /// metric's name and value.
101    #[derive(Clone, Debug, PartialEq)]
102    enum Seen {
103        Subscriptions(WireUuid),
104        Push {
105            client_instance_id: WireUuid,
106            terminating: bool,
107            metrics: Vec<(String, Option<NumberValue>)>,
108        },
109    }
110
111    /// The body of a flexible request after the request header v2.
112    fn request_body(frame: &[u8]) -> &[u8] {
113        let client_id_len = usize::try_from(i16::from_be_bytes([frame[0], frame[1]])).unwrap_or(0);
114        &frame[2 + client_id_len + 1..]
115    }
116
117    fn flexible_response(response: &impl Encode) -> Vec<u8> {
118        let mut body = BytesMut::from(&[0u8][..]);
119        response.encode(&mut body, 0).unwrap();
120        body.to_vec()
121    }
122
123    fn seen_push(request: &PushTelemetryRequest) -> Seen {
124        let data = MetricsData::decode(&request.metrics).unwrap();
125        let metrics = data
126            .resource_metrics
127            .into_iter()
128            .flat_map(|resource| resource.scope_metrics)
129            .flat_map(|scope| scope.metrics)
130            .map(|metric| {
131                let value = match metric.data {
132                    Some(
133                        MetricData::Gauge { data_points } | MetricData::Sum { data_points, .. },
134                    ) => data_points.first().and_then(|point| point.value),
135                    None => None,
136                };
137                (metric.name, value)
138            })
139            .collect();
140        Seen::Push {
141            client_instance_id: request.client_instance_id,
142            terminating: request.terminating,
143            metrics,
144        }
145    }
146
147    /// A broker that assigns [`INSTANCE`] and subscribes the admin client's
148    /// connection count, pushed every 200 ms. With `advertise_telemetry`
149    /// false it does not list the KIP-714 APIs.
150    async fn start_broker(
151        advertise_telemetry: bool,
152    ) -> (MockBroker, mpsc::UnboundedReceiver<Seen>) {
153        let (seen_tx, seen_rx) = mpsc::unbounded_channel();
154        let broker = MockBroker::start(move |api_key, version, _corr, frame| match api_key {
155            api_versions_request::API_KEY => {
156                let mut keys = vec![(api_versions_request::API_KEY, 3)];
157                if advertise_telemetry {
158                    keys.push((get_telemetry_subscriptions_request::API_KEY, 0));
159                    keys.push((push_telemetry_request::API_KEY, 0));
160                }
161                let response = ApiVersionsResponse {
162                    api_keys: keys
163                        .into_iter()
164                        .map(|(api_key, max_version)| ApiVersion {
165                            api_key,
166                            min_version: 0,
167                            max_version,
168                            ..Default::default()
169                        })
170                        .collect(),
171                    ..Default::default()
172                };
173                let mut body = BytesMut::new();
174                response.encode(&mut body, version).unwrap();
175                Some(body.to_vec())
176            }
177            get_telemetry_subscriptions_request::API_KEY => {
178                let mut body = request_body(frame);
179                let request = GetTelemetrySubscriptionsRequest::decode(&mut body, version).unwrap();
180                seen_tx
181                    .send(Seen::Subscriptions(request.client_instance_id))
182                    .ok();
183                Some(flexible_response(&GetTelemetrySubscriptionsResponse {
184                    client_instance_id: INSTANCE,
185                    subscription_id: 5,
186                    push_interval_ms: 200,
187                    telemetry_max_bytes: 1 << 20,
188                    requested_metrics: vec![CONNECTION_COUNT.to_owned()],
189                    ..Default::default()
190                }))
191            }
192            push_telemetry_request::API_KEY => {
193                let mut body = request_body(frame);
194                let request = PushTelemetryRequest::decode(&mut body, version).unwrap();
195                seen_tx.send(seen_push(&request)).ok();
196                Some(flexible_response(&PushTelemetryResponse::default()))
197            }
198            _ => None,
199        })
200        .await;
201        (broker, seen_rx)
202    }
203
204    async fn next(seen: &mut mpsc::UnboundedReceiver<Seen>) -> Seen {
205        tokio::time::timeout(Duration::from_secs(10), seen.recv())
206            .await
207            .expect("a telemetry request within 10 s")
208            .expect("the broker is running")
209    }
210
211    /// Kafka's admin client with `enable.metrics.push`: it asks for the
212    /// subscription, pushes the subscribed metrics (its one open
213    /// connection), returns the assigned id from `clientInstanceId`, and
214    /// sends a terminating push on close. With the setting off, or with a
215    /// broker without KIP-714, it sends no telemetry request.
216    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
217    async fn admin_client_pushes_metrics_and_reports_its_instance_id() {
218        let disabled =
219            "client-core: Telemetry is not enabled. Set config `enable.metrics.push` to \
220                        `true`."
221                .to_owned();
222        let push = |terminating| Seen::Push {
223            client_instance_id: INSTANCE,
224            terminating,
225            metrics: vec![(CONNECTION_COUNT.to_owned(), Some(NumberValue::Double(1.0)))],
226        };
227        let cases = [
228            (
229                "enable.metrics.push=true",
230                true,
231                true,
232                2,
233                Ok(Some(uuid::Uuid::from_bytes(INSTANCE.0))),
234                vec![Seen::Subscriptions(WireUuid::ZERO), push(false), push(true)],
235            ),
236            (
237                "enable.metrics.push=false",
238                false,
239                true,
240                0,
241                Err(disabled),
242                vec![],
243            ),
244            ("broker without KIP-714", true, false, 0, Ok(None), vec![]),
245        ];
246        for (name, enable_metrics_push, advertise_telemetry, count, expected_id, expected) in cases
247        {
248            let (broker, mut seen) = start_broker(advertise_telemetry).await;
249            let admin = crate::AdminClient::connect_with_config(
250                &[broker.addr.to_string()],
251                AdminClientConfig {
252                    enable_metrics_push,
253                    ..AdminClientConfig::default()
254                },
255            )
256            .await
257            .expect("admin connects");
258            let timeout = if count == 0 {
259                krabka_units::millis(300)
260            } else {
261                krabka_units::secs(10)
262            };
263            let id = admin
264                .client_instance_id(timeout)
265                .await
266                .map_err(|error| error.to_string());
267            let mut requests = Vec::new();
268            for _ in 0..count {
269                requests.push(next(&mut seen).await);
270            }
271            tokio::time::timeout(Duration::from_secs(20), admin.close())
272                .await
273                .expect("the close ends");
274            broker.stop();
275            while let Ok(request) = seen.try_recv() {
276                requests.push(request);
277            }
278            assert!((id, requests) == (expected_id, expected), "{name}");
279        }
280    }
281}