hi Siddhartha
I might be misunderstanding the approach of this PR. The
@SuppressWarnings("deprecation") annotation is just a temporary workaround for
now, right? We will eventually face the same issue in version 5.0: how to
create a Metrics instance with a specific Time object from another package.
Best,
Chia-Ping
On 2026/07/20 21:34:15 Siddhartha Devineni wrote:
> Hi Chia-Ping and Sean,
>
> To clarify the earlier discussion, after further investigation, "Metrics"
> doesn't call any "Time" methods directly, rather it just stores and passes
> it to internal components (this.time = time on line 174).
>
> This means no officially public Javadoc class actually needs to call any
> "Time" methods.
>
> So, we could simply:
> 1. Deprecate Time-accepting constructors in "Metrics" and "KafkaStreams"
> 2. Keep "Time" as internal API
> 3. No new public interface needed
>
> I have already created a PR implementing this approach after
> withdrawing the KIP
>
> https://github.com/apache/kafka/pull/22689
>
> WDYT?
>
> Thanks and Best regards,
> Siddhartha
>
> On Mon, Jul 20, 2026 at 8:02 PM Chia-Ping Tsai <[email protected]> wrote:
>
> > hi Alieh
> >
> > We could keep discussing on this mail thread.
> >
> > The solution provided by Sean is pretty good. Except for KafkaStreams, the
> > others only use the `milliseconds` so we could have a new simple interface
> > Time, which could be located at org.apache.kafka.common, to replace origin
> > Time-accepting constructor
> >
> > Best,
> > Chia-Ping
> >
> > On 2026/07/20 14:27:00 Alieh Saeedi via dev wrote:
> > > Hi
> > >
> > > Why is the KIP marked as withdrawn if the discussion is still ongoing in
> > > the same thread?
> > >
> > > -Alieh
> > >
> > > On Mon, Jul 20, 2026 at 3:31 PM Sean Quah via dev <[email protected]>
> > > wrote:
> > >
> > > > Hi,
> > > >
> > > > I was hoping we could avoid making Time public. Failing that, is it
> > > > possible to reduce the public API surface further? I looked at Metrics
> > > > before and it only wanted the wall clock (milliseconds()). Perhaps
> > > > the other constructors are the same?
> > > > We could perhaps have a very simple public Time interface only exposing
> > > > milliseconds (effectively a wall clock interface) and an internal Time
> > > > interface which extends it with other methods.
> > > >
> > > > Thanks,
> > > > Sean
> > > >
> > > > On Mon, Jul 20, 2026 at 8:51 AM Chia-Ping Tsai <[email protected]>
> > > > wrote:
> > > >
> > > > > hi all,
> > > > >
> > > > > I re-read the constructors, and I think deprecating the
> > time-accepting
> > > > > constructors will introduce huge changes to the codebase.
> > > > >
> > > > > Maybe we could just make Time public with a few methods, such as
> > > > > milliseconds, nanoseconds, and sleep. Since Timer is not public, we
> > could
> > > > > add a helper method to Timer, like Timer.create(Time, ...), to
> > replace
> > > > > Time#timer().
> > > > >
> > > > > WDYT?
> > > > >
> > > > > On 2026/04/23 20:57:19 Siddhartha Devineni wrote:
> > > > > > Hi Chia-Ping, Kirk and Matthias,
> > > > > >
> > > > > > @Chia-Ping: You were right - after investigating, Time doesn't
> > need to
> > > > be
> > > > > > public.
> > > > > >
> > > > > > @Kirk: You are right - the OAuth examples are instantiated via
> > > > > reflection,
> > > > > > not direct user code.
> > > > > >
> > > > > > @Matthias: Good points. I investigated whether Metrics can be
> > changed
> > > > to
> > > > > > not expose Time.
> > > > > >
> > > > > > Findings:
> > > > > >
> > > > > > - new Metrics() - users call this (internally uses Time.SYSTEM)
> > > > > > - new Metrics(Time time) and other variants - only called by
> > internal
> > > > > Kafka
> > > > > > code (KafkaProducer, KafkaAdminClient, etc) and tests
> > > > > >
> > > > > > Proposed approach:
> > > > > >
> > > > > > - Withdraw KIP-1311 (Make Time public)
> > > > > > - Create JIRA: "Deprecate Time-accepting constructors"
> > > > > > - Deprecate Time constructors in both KafkaStreams and Metrics:
> > > > > > - KafkaStreams(Topology, Properties, Time)
> > > > > > - KafkaStreams(Topology, StreamsConfig, Time)
> > > > > > - KafkaStreams(Topology, Properties, KafkaClientSupplier,
> > Time)
> > > > > > - Metrics(Time)
> > > > > > - Metrics(MetricConfig, Time)
> > > > > > - Metrics(MetricConfig, List<MetricsReporter>, Time)
> > > > > > - (and other Metrics variants accepting Time)
> > > > > > - In version 5.0, make these constructors package-private
> > > > > > - Internal Kafka code continues using them
> > > > > >
> > > > > > Result: Time remains internal.
> > > > > >
> > > > > > Does this approach work? If so, I'll withdraw KIP-1311 and create
> > the
> > > > > JIRA.
> > > > > >
> > > > > > Thank you,
> > > > > > Siddhartha
> > > > > >
> > > > > > On Tue, Apr 21, 2026 at 5:22 AM Matthias J. Sax <[email protected]>
> > > > > wrote:
> > > > > >
> > > > > > > Thanks for the KIP. I am not sure if I understand why
> > > > > `KafkaStreamsMock`
> > > > > > > would be anything public?
> > > > > > >
> > > > > > > Also, why would we put it into some new `...test...` package? If
> > we
> > > > > > > change the package, we need to have `protected` access, which is
> > > > > already
> > > > > > > "semi-public"...
> > > > > > >
> > > > > > > If we want to keep `Time` internal, we would eventually make the
> > > > > > > constructors that are marked deprecated, package-private, what
> > allows
> > > > > us
> > > > > > > to add `org.apache.kafka.streams.KafkaStreamsMock` (same package
> > > > name,
> > > > > > > but int `test/` module) to still use these constructors, and the
> > > > > > > corresponding unit test would use the new mock-factory instead of
> > > > > > > calling `new`?
> > > > > > >
> > > > > > > For this case, the KIP does not need to mention anything about
> > > > > > > `KafkaStreamsMock` as it's an helper in our `test/` module only,
> > but
> > > > > not
> > > > > > > public API. -- If we want, we can still mention this plan on the
> > KIP,
> > > > > > > but atm the KIP is written in a way as if `KafkaStreamsMock`
> > would
> > > > > > > become public API, but to my understanding it should be an
> > > > impl/testing
> > > > > > > details only?
> > > > > > >
> > > > > > > Or did I misunderstand something?
> > > > > > >
> > > > > > >
> > > > > > > Also wondering, if we could also change `Metrics` in a way, that
> > we
> > > > > > > would not need to make `Time` public to begin with?
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > -Matthias
> > > > > > >
> > > > > > > On 4/20/26 4:53 PM, Kirk True wrote:
> > > > > > > > Hi Siddhartha,
> > > > > > > >
> > > > > > > > The OAuth examples use Time in their constructors for unit
> > tests.
> > > > > > > They're not intended to be instantiated by any user code since
> > > > they're
> > > > > in
> > > > > > > an internals package.
> > > > > > > >
> > > > > > > > Thanks,
> > > > > > > > Kirk
> > > > > > > >
> > > > > > > > On Wed, Apr 15, 2026, at 8:52 AM, Siddhartha Devineni wrote:
> > > > > > > >> Hi Chia-Ping,
> > > > > > > >>
> > > > > > > >> Sorry that i didn't mention the following examples in the KIP
> > > > > earlier.
> > > > > > > >> Now, I have updated the KIP with the following public packages
> > > > > examples,
> > > > > > > >> where "Time" is exposed in the public constructors:
> > > > > > > >>
> > > > > > > >> // couple of examples from multiple
> > > > > > > >> "org.apache.kafka.common.metrics.Metrics.java" constructors
> > > > > > > >> public Metrics(Time time) {}
> > > > > > > >> public Metrics(MetricConfig defaultConfig, Time time) {}
> > > > > > > >>
> > > > > > > >> // in the public package
> > > > > "org.apache.kafka.common.security.oauthbearer"
> > > > > > > >> public JwtBearerJwtRetriever(Time time) {}
> > > > > > > >> public ClientCredentialsJwtRetriever(Time time) {}
> > > > > > > >>
> > > > > > > >> Now, it should be clear.
> > > > > > > >> Thanks for your time.
> > > > > > > >>
> > > > > > > >> Best regards,
> > > > > > > >> Siddhartha
> > > > > > > >>
> > > > > > > >> On Tue, Apr 14, 2026 at 11:14 AM Chia-Ping Tsai <
> > > > [email protected]
> > > > > >
> > > > > > > wrote:
> > > > > > > >>
> > > > > > > >>> hi Siddhartha
> > > > > > > >>>
> > > > > > > >>> Thanks for this KIP.
> > > > > > > >>>
> > > > > > > >>> What is the exact benefit of exposing Time as a public API?
> > Since
> > > > > this
> > > > > > > KIP
> > > > > > > >>> proposes deprecating KafkaStreams(Topology, Properties,
> > Time), it
> > > > > seems
> > > > > > > >>> there are no public interfaces relying on it anymore.
> > > > > > > >>>
> > > > > > > >>> Thus, it should be fine to just keep Time as an internal API,
> > > > > right?
> > > > > > > >>>
> > > > > > > >>> Best,
> > > > > > > >>> Chia-Ping
> > > > > > > >>>
> > > > > > > >>>
> > > > > > > >>> Siddhartha Devineni <[email protected]> 於
> > > > 2026年4月7日週二
> > > > > > > >>> 下午2:19寫道：
> > > > > > > >>>
> > > > > > > >>>> Apologies, as I forgot to add the link to the KIP:
> > > > > > > >>>>
> > > > > > > >>>>
> > > > > > > >>>
> > > > > > >
> > > > >
> > > >
> > https://urldefense.com/v3/__https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=406623925__;!!Ayb5sqE7!o-ar2zzpALvIzp5wF7s2E77bUw9C8CxXLU1JxqxsiiliVfUFzl_M8gIOcFoy3T1nFx5L78W0vA8d7XV_enMH$
> > > > > > > >>>>
> > > > > > > >>>>
> > > > > > > >>>> On Tue, Apr 7, 2026 at 9:13 AM Siddhartha Devineni <
> > > > > > > >>>> [email protected]> wrote:
> > > > > > > >>>>
> > > > > > > >>>>> Hello everyone,
> > > > > > > >>>>>
> > > > > > > >>>>> I would like to start a discussion on [DISCUSS] KIP-1311:
> > Make
> > > > > > > >>> Time/Timer
> > > > > > > >>>>> public API.
> > > > > > > >>>>>
> > > > > > > >>>>> Following KIP-1247 (Make Bytes part of public API), the
> > Time
> > > > > > > interface
> > > > > > > >>>> and
> > > > > > > >>>>> Timer class are the next candidates from
> > > > > > > >>> "org.apache.kafka.common.utils"
> > > > > > > >>>> to
> > > > > > > >>>>> be made officially public. Time is currently exposed
> > through
> > > > > public
> > > > > > > >>> APIs
> > > > > > > >>>>> (e.g., in clients, KafkaStreams constructors, etc) but not
> > > > > officially
> > > > > > > >>>>> designated as a public API.
> > > > > > > >>>>>
> > > > > > > >>>>> An earlier version of this KIP explored splitting Time into
> > > > > focused
> > > > > > > >>>>> interfaces (Clock, MonotonicClock, etc.), but this would
> > > > require
> > > > > > > >>>> rewriting
> > > > > > > >>>>> thousands of method signatures across the Kafka codebase.
> > The
> > > > > simpler
> > > > > > > >>>>> approach of making Time public as-is seems more
> > appropriate to
> > > > > avoid
> > > > > > > >>>>> breaking changes.
> > > > > > > >>>>>
> > > > > > > >>>>> Looking forward to your feedback.
> > > > > > > >>>>>
> > > > > > > >>>>> Thank you,
> > > > > > > >>>>> Siddhartha
> > > > > > > >>>>>
> > > > > > > >>>>
> > > > > > > >>>
> > > > > > > >>
> > > > > > > >
> > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
