confluent_kafka/common/metrics/time_unit.rs
1// Copyright 2025 Confluent Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15/// A subset of `java.util.concurrent.TimeUnit` used by the metrics rate stats.
16///
17/// A JDK type, so Kafka's audience rules do not apply: it is public because
18/// the public `MetricConfig::set_time_window`, `Rate` and `Meter` take it.
19///
20/// Only the variants the metrics framework needs are modelled; the conversion
21/// factors used by the rate stats are exactly Java's `TimeUnit` semantics.
22#[derive(Clone, Copy, Debug, PartialEq, Eq)]
23#[non_exhaustive]
24// translates the JDK's java.util.concurrent.TimeUnit, outside Kafka's audience rules; the public MetricConfig::set_time_window, Rate and Meter take it
25#[doc(alias = "rust-only")]
26pub enum TimeUnit {
27 /// Nanoseconds.
28 Nanoseconds,
29 /// Microseconds.
30 Microseconds,
31 /// Milliseconds.
32 Milliseconds,
33 /// Seconds.
34 Seconds,
35 /// Minutes.
36 Minutes,
37 /// Hours.
38 Hours,
39 /// Days.
40 Days,
41}
42
43impl TimeUnit {
44 /// Returns the `name()` of the unit, matching Java's enum constant name.
45 pub fn name(&self) -> &'static str {
46 match self {
47 TimeUnit::Nanoseconds => "NANOSECONDS",
48 TimeUnit::Microseconds => "MICROSECONDS",
49 TimeUnit::Milliseconds => "MILLISECONDS",
50 TimeUnit::Seconds => "SECONDS",
51 TimeUnit::Minutes => "MINUTES",
52 TimeUnit::Hours => "HOURS",
53 TimeUnit::Days => "DAYS",
54 }
55 }
56
57 /// Converts a duration expressed in this unit to milliseconds, as
58 /// `TimeUnit.MILLISECONDS.convert(window, unit)` does: a finer unit
59 /// truncates, a coarser one saturates at `i64::MAX` / `i64::MIN`.
60 ///
61 /// # Arguments
62 ///
63 /// - `window` - the duration, in this unit
64 ///
65 /// # Returns
66 ///
67 /// The duration in milliseconds.
68 pub fn to_millis(self, window: i64) -> i64 {
69 match self {
70 TimeUnit::Nanoseconds => window / 1_000_000,
71 TimeUnit::Microseconds => window / 1_000,
72 TimeUnit::Milliseconds => window,
73 TimeUnit::Seconds => window.saturating_mul(1_000),
74 TimeUnit::Minutes => window.saturating_mul(60 * 1_000),
75 TimeUnit::Hours => window.saturating_mul(60 * 60 * 1_000),
76 TimeUnit::Days => window.saturating_mul(24 * 60 * 60 * 1_000),
77 }
78 }
79}