Skip to content

[SDT-0001]: task-local instrument implementation - #230

Draft
kukushechkin wants to merge 9 commits into
apple:mainfrom
kukushechkin:SDT-0001-task-local-instrument-implementation
Draft

[SDT-0001]: task-local instrument implementation#230
kukushechkin wants to merge 9 commits into
apple:mainfrom
kukushechkin:SDT-0001-task-local-instrument-implementation

Conversation

@kukushechkin

Copy link
Copy Markdown
Contributor

Add withInstrument(_:_:) for task-local instrument scoping.

Motivation:

InstrumentationSystem.bootstrap(_:) installs an instrument once per process, so every withSpan/startSpan and every read of InstrumentationSystem.instrument resolves through that single instrument. That fits one tracer for the whole application, but it leaves no way to bind a different instrument for a region of work — most acutely in tests, where a second bootstrap crashes and parallel tests cannot each install their own in-memory tracer.

Modifications:

  • Added withInstrument(_:_:) and an internal TaskLocalInstrument.
  • InstrumentationSystem installs the task-local instrument on first use, and tracer discovery and propagation resolve through it via an internal _InstrumentContainer walk shared with MultiplexInstrument.
  • Added tests covering scoping, replacement, MultiplexInstrument resolution, and the self-reference guard, and updated the TraceYourApplication and InstrumentYourLibrary guides.

Result:

swift-distributed-tracing provides opt-in withInstrument(_:_:) task-local instrument scoping.

@kukushechkin kukushechkin added the 🆕 semver/minor Adds new public API. label Jun 29, 2026
/// - Returns: The value returned by the closure.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
@inlinable
public func withInstrument<Result, Failure: Error>(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if it'd be nice to also have withTracer variants, as most people, when they use SDT, instantiate and talk about "tracers", not "instruments".

If I think to how I'd discover this with autocompletion, unless intimately familiar with SDT, I'd struggle to realize that withInstrument is what I should use when I'm looking for withTracer (after I've already adopted withLogger and withMetricsFactory.

@kukushechkin
kukushechkin force-pushed the SDT-0001-task-local-instrument-implementation branch 2 times, most recently from 7ef78c0 to 30e5587 Compare August 4, 2026 15:57
@kukushechkin
kukushechkin force-pushed the SDT-0001-task-local-instrument-implementation branch from 30e5587 to caadb06 Compare August 5, 2026 14:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🆕 semver/minor Adds new public API.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants