Skip to content

Startup telemetry: a Clock, the boot's stages as spans, an always-sampled start; Kotlin API 2.3 - #72

Merged
rocketraman merged 4 commits into
masterfrom
rg/boot-clock
Nov 17, 2026
Merged

rocketraman merged 4 commits into
masterfrom
rg/boot-clock

Conversation

@rocketraman

@rocketraman rocketraman commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

ServiceStartTracing dated the start's root span with Instant.now(), while the SDK took the time of every other span from its own clock. So neither could be fixed in a test, and nothing made sure they agreed.

Changes

  • OpenTelemetryService(config, customizers, clock) takes a kotlin.time.Clock, which becomes the SDK's clock for its tracer and meter providers.
    • With Clock.System, the default, the SDK keeps its own clock, which measures durations with System.nanoTime.
    • Any other clock supplies both the time and the durations.
  • ServiceStartTracing(openTelemetry, clock) sets the root span's start to clock.now() less the time since the startup mark. The startup mark is monotonic, so the root span's duration is unaffected by changes to the wall clock.
  • Kodein and Metro use a Clock binding if there is one, and otherwise Clock.System. This follows the existing pattern for StartOrder:
    • Kodein: openTelemetryModule and serviceStartTracingModule use instanceOrNull<Clock>().
    • Metro: the binding functions take the clock as an optional parameter.

Kotlin API 2.3

kotlin.time.Clock has been stable only since Kotlin 2.3, so a Clock parameter would make callers compiling against API 2.1 opt in to ExperimentalTime.
Bootable now compiles for API 2.3, supporting the last two Kotlin versions (2.3 and 2.4), so the clock is an ordinary default parameter. The Metro flavors and examples already required 2.3, and no longer raise it themselves, and boot no longer opts in to ExperimentalTime.

Not a required ClockModule

There is no required ClockModule binding. A missing Clock falls back to Clock.System, as StartOrder does, so existing wiring keeps working. To use another clock, an app binds one: bindInstance<Clock> { … } with Kodein, or @Provides fun clock(): Clock with Metro.

Startup stages and sampling

  • aroundAppStart(serviceContext, timeline, start) now gets a StartupTimeline instead of the bare startup mark: the mark, plus the stages since, each ending where the next begins.
    • boot adds initialize JVM classes for logging and configuration: setting up logging, then the bootable lambda, which includes the config, the DI graph and the constructors.
      On a cold JVM this stage is mostly class loading and initialization: on the vanilla server-ktor-db example, about 1,900 classes while Log4j starts and about 3,100 in the bootable lambda (Hoplite with kotlin-reflect, Typesafe Config, the OpenTelemetry SDK, Flyway, Exposed). A JVM AOT cache cut it from about 490 ms to about 160 ms.
      It was two stages, set up logging and build application, but most of the first was class loading the app would do without logging too.
    • Bootable adds plan start and initialize.
    • A Bootable run without boot has only the last two.
  • ServiceStartTracing records each stage as a child span of start application. The spans are created after the fact, with the times the timeline marked, since the SDK doesn't exist yet during the early stages.
  • OpenTelemetryService's sampler always samples a root span that carries the ALWAYS_SAMPLE attribute (bootable.sample.always). It checks for the attribute, not the span name.
    • ServiceStartTracing sets the attribute on start application.
    • withRootSpan(name, sample = Sample.Always) sets it too, for other traces that are too rare or valuable to lose, such as a nightly job's.
    • The spans under such a root are sampled with it, through the parent-based default sampler.
    • Before this, a sampleRatio below 1 dropped the start's trace as often as any other trace.
  • New tests check the stage spans' timing against a fixed clock, and check that with sampleRatio = 0.0 the start's trace and a Sample.Always trace are recorded while ordinary ones aren't.

Verification

  • ./gradlew build passes.
  • New tests use a clock fixed at 2030-01-01, constructed directly and through both Kodein and Metro wiring. Each checks that a service span starts exactly at the fixed time and that the root span starts a little over a second before it.
  • The tests sample every trace, because the test config's sampleRatio = 0.5 would otherwise drop half of them.
  • The telemetry tests passed on three consecutive reruns.

@rocketraman rocketraman changed the title telemetry: time the SDK and the start's root span with a Clock telemetry: time the SDK and the start's root span with a Clock; Kotlin API 2.3 Nov 17, 2026
@claude

claude Bot commented Nov 17, 2026

Copy link
Copy Markdown

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

@rocketraman rocketraman changed the title telemetry: time the SDK and the start's root span with a Clock; Kotlin API 2.3 Startup telemetry: a Clock, the boot's stages as spans, an always-sampled start; Kotlin API 2.3 Nov 17, 2026
Bootable supports the last two Kotlin versions, 2.3 and 2.4, so it
compiles for API 2.3 rather than 2.1. 2.3 is also what Metro needs,
so the Metro flavors and examples no longer raise it themselves, and
where kotlin.time.Clock is stable, so boot no longer opts in to
ExperimentalTime.
ServiceStartTracing dated the start's root span with Instant.now(),
while the SDK took the time of every other span from its own clock, so
neither could be fixed in a test, nor be sure to agree.

- OpenTelemetryService takes a kotlin.time.Clock, Clock.System by
  default, which becomes the SDK's clock for its tracer and meter
  providers. With Clock.System, the SDK keeps its own, which measures
  durations with System.nanoTime.
- ServiceStartTracing takes the same Clock, and dates the root span
  at its time less the time since the startup mark.
- Kodein and Metro pass a Clock binding if there is one, or else
  Clock.System, as Bootable does for StartOrder.
aroundAppStart got only the startup mark, so a controller couldn't
tell where the time before the first service went. It now gets a
StartupTimeline: the mark, and the stages since, each ending where
the next begins. boot adds "initialize JVM classes for logging and
configuration" (setting up logging, then the bootable lambda), and
Bootable adds "plan start" and "initialize".

The first stage is named for what dominates it on a cold JVM:
loading and initializing the classes of the logging, config,
telemetry and database libraries, which a JVM AOT cache cuts
sharply. Setting up logging isn't a stage of its own, since most of
its time is class loading the application would do without logging
too.

ServiceStartTracing records each stage as a span under the start's
root span, at the times the timeline marked, since the SDK doesn't
exist yet when the early stages run.
With a sampleRatio below 1, the start's trace was dropped as often as
any other, though it happens once per process and is the trace of a
slow or failed start.

- OpenTelemetryService's sampler always samples a root span marked
  with ALWAYS_SAMPLE, bootable.sample.always, and leaves every other
  span to the sampler it wraps.
- ServiceStartTracing marks the start's root span with it.
- withRootSpan(name, sample = Sample.Always) marks its root span with
  it too: for a trace too rare or valuable to lose, such as a nightly
  job's.
@rocketraman
rocketraman merged commit c36e9ec into master Nov 17, 2026
2 checks passed
@rocketraman
rocketraman deleted the rg/boot-clock branch November 17, 2026 23:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant