feat(kotlin): trace sandbox pool warmup with OpenTelemetry - #1524
Merged
Pangjiping merged 3 commits intoAug 17, 2026
Merged
Conversation
Add opt-in OpenTelemetry tracing (ConnectionConfig.enableTracing, default off) for the pool warmup path. Each warmup task emits one trace rooted at a pool.warmup span with per-phase child spans (create / prepare / renew / commit); the root span is backdated to task submission so queue-wait time is visible. trace_id/span_id are published to the SLF4J MDC while a warmup is in progress so logs can be correlated back to traces by sandbox_id. The SDK depends only on opentelemetry-api (no-op by default); users bring their own OpenTelemetry SDK + exporter and configure the global instance. When enabled, the active trace context is propagated to lifecycle requests via the W3C traceparent header for server-side correlation. Adds PoolTracer + WarmupTrace, TraceContextInterceptor in HttpClientProvider, ConnectionConfig.enableTracing (builder + copyWithoutConnectionPool), and tests covering span tree/attributes/MDC, failure traces, disabled no-op behavior, and traceparent injection. Documents setup and trace querying in docs/guides/sdk-tracing.md.
github-actions
Bot
added
documentation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6fb65398b6
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…ommits - The warmup root span start timestamp now uses epoch wall-clock (System.currentTimeMillis-based) captured at submission instead of the monotonic System.nanoTime, so the root span is comparable with child spans' timestamps. - Commits that drop the warmed sandbox (stale run, primary lock lost, or putIdle failure) now end the warmup trace as failure with a drop.reason attribute instead of marking result=success. - Tests: assert root start is epoch wall-clock near test start; new case covering a warmup dropped with warmup-lock-lost.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0f02b464cc
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
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
2 participants
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.
Summary
Add opt-in OpenTelemetry tracing to the Kotlin SDK's client-side sandbox pool warmup path, so warmup bottlenecks can be analyzed per phase and correlated to application logs by
sandbox_id.Behavior
ConnectionConfig.enableTracing(true)(defaultfalse, no env var) turns tracing on.pool.warmuproot span (backdated to task submission so queue-wait time is visible) with sequential sibling phase spans:pool.warmup.create— create API + readiness waitpool.warmup.prepare— userwarmupSandboxPreparerpool.warmup.renew— TTL renewalpool.warmup.commit— primary-lock renew +putIdle(scheduler thread)pool.name,pool.owner,pool.run.generation,sandbox.id,sandbox.image,result; failures recorded viarecordException.trace_id/span_idare published to the SLF4J MDC while a warmup is in progress → search logs bysandbox_id, open the trace in your backend.traceparent(server-side correlation, ready for server tracing support).Design notes
io.opentelemetry:opentelemetry-api(implementation, no-op without an OTel SDK on the classpath); users bring their own SDK + exporter and setGlobalOpenTelemetry. BOM constraint added.docs/guides/sdk-tracing.md(setup, span structure, MDC correlation, querying/drill-down), linked from the Kotlin SDK page and Client Pool guide; sidebar entry added.Tests
PoolWarmupTracingTest(4 cases): full span tree + attributes + MDC correlation, failure trace (exception event, no commit span), disabled → zero spans, traceparent injection on/off. Full suite::sandbox:test322 tests, 0 failures;:code-interpreter:testgreen; spotless clean;pnpm docs:buildzero errors.Notes
1.0.19as the min SDK version for this feature; currentgradle.propertiesis1.0.18— bump at release time.