Repository navigation
Startup telemetry: a Clock, the boot's stages as spans, an always-sampled start; Kotlin API 2.3 - #72
Merged
Merged
Conversation
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. |
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.
rocketraman
force-pushed
the
rg/boot-clock
branch
from
November 17, 2026 21:17
0f09139 to
a90c16e
Compare
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
force-pushed
the
rg/boot-clock
branch
from
November 17, 2026 21:38
a90c16e to
8cbbc1c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ServiceStartTracingdated the start's root span withInstant.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 akotlin.time.Clock, which becomes the SDK's clock for its tracer and meter providers.Clock.System, the default, the SDK keeps its own clock, which measures durations withSystem.nanoTime.ServiceStartTracing(openTelemetry, clock)sets the root span's start toclock.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.Clockbinding if there is one, and otherwiseClock.System. This follows the existing pattern forStartOrder:openTelemetryModuleandserviceStartTracingModuleuseinstanceOrNull<Clock>().Kotlin API 2.3
kotlin.time.Clockhas been stable only since Kotlin 2.3, so aClockparameter would make callers compiling against API 2.1 opt in toExperimentalTime.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
bootno longer opts in toExperimentalTime.Not a required
ClockModuleThere is no required
ClockModulebinding. A missingClockfalls back toClock.System, asStartOrderdoes, so existing wiring keeps working. To use another clock, an app binds one:bindInstance<Clock> { … }with Kodein, or@Provides fun clock(): Clockwith Metro.Startup stages and sampling
aroundAppStart(serviceContext, timeline, start)now gets aStartupTimelineinstead of the bare startup mark: the mark, plus the stages since, each ending where the next begins.bootaddsinitialize JVM classes for logging and configuration: setting up logging, then thebootablelambda, 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-dbexample, about 1,900 classes while Log4j starts and about 3,100 in thebootablelambda (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 loggingandbuild application, but most of the first was class loading the app would do without logging too.Bootableaddsplan startandinitialize.Bootablerun withoutboothas only the last two.ServiceStartTracingrecords each stage as a child span ofstart 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 theALWAYS_SAMPLEattribute (bootable.sample.always). It checks for the attribute, not the span name.ServiceStartTracingsets the attribute onstart 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.sampleRatiobelow 1 dropped the start's trace as often as any other trace.sampleRatio = 0.0the start's trace and aSample.Alwaystrace are recorded while ordinary ones aren't.Verification
./gradlew buildpasses.sampleRatio = 0.5would otherwise drop half of them.