Skip to content

Commit 8b2be68

Browse files
ktosoktoso
committed
add documentation
1 parent f2e4d32 commit 8b2be68

File tree

3 files changed

+189
-10
lines changed

3 files changed

+189
-10
lines changed

‎Sources/Tracing/TracerProtocol+Legacy.swift

+128-10
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,7 @@ import Dispatch
2020
public protocol LegacyTracerProtocol: InstrumentProtocol {
2121
/// Start a new span returning an existential ``Span`` reference.
2222
///
23-
/// This API will be deprecated as soon as Swift 5.9 is released, and the Swift 5.7 requiring `TracerProtocol`
24-
/// is recommended instead.
23+
/// - Warning: This method will be deprecated in favor of `TracerProtocol/withSpan` as soon as this project is able to require Swift 5.7.
2524
///
2625
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
2726
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
@@ -75,8 +74,7 @@ extension LegacyTracerProtocol {
7574

7675
/// Start a new span returning an existential ``Span`` reference.
7776
///
78-
/// This API will be deprecated as soon as Swift 5.9 is released, and the Swift 5.7 requiring `TracerProtocol`
79-
/// is recommended instead.
77+
/// - Warning: This method will be deprecated in favor of `TracerProtocol/withSpan` as soon as this project is able to require Swift 5.7.
8078
///
8179
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
8280
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
@@ -122,6 +120,34 @@ extension LegacyTracerProtocol {
122120
)
123121
}
124122

123+
/// Start a new span returning an existential ``Span`` reference.
124+
///
125+
/// - Warning: This method will be deprecated in favor of `TracerProtocol/withSpan` as soon as this project is able to require Swift 5.7.
126+
///
127+
///
128+
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
129+
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
130+
/// to pick up the task-local baggage is prevented. This can be useful when we know that
131+
/// we're about to start a top-level span, or if a span should be started from a different,
132+
/// stored away previously,
133+
///
134+
/// - Note: Legacy API, prefer using ``startSpan(_:baggage:ofKind:at:
135+
///
136+
/// - Note: Prefer ``withSpan(_:baggage:ofKind:at:function:file:line:operation:)`` to start
137+
/// a span as it automatically takes care of ending the span, and recording errors when thrown.
138+
/// Use `startSpan` iff you need to pass the span manually to a different
139+
/// location in your source code to end it.
140+
///
141+
/// - Warning: You must `end()` the span when it the measured operation has completed explicitly,
142+
/// otherwise the span object will potentially never be released nor reported.
143+
///
144+
/// - Parameters:
145+
/// - operationName: The name of the operation being traced. This may be a handler function, database call, ...
146+
/// - baggage: The `Baggage` providing information on where to start the new ``Span``.
147+
/// - kind: The ``SpanKind`` of the new ``Span``.
148+
/// - function: The function name in which the span was started
149+
/// - fileID: The `fileID` where the span was started.
150+
/// - line: The file line where the span was started.
125151
public func startAnySpan(
126152
_ operationName: String,
127153
baggage: @autoclosure () -> Baggage = .current ?? .topLevel,
@@ -143,6 +169,29 @@ extension LegacyTracerProtocol {
143169

144170
// ==== withAnySpan + sync ------------------------------------------------
145171

172+
/// Start a new ``Span`` and automatically end when the `operation` completes,
173+
/// including recording the `error` in case the operation throws.
174+
///
175+
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
176+
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
177+
/// to pick up the task-local baggage is prevented. This can be useful when we know that
178+
/// we're about to start a top-level span, or if a span should be started from a different,
179+
/// stored away previously,
180+
///
181+
/// - Warning: You MUST NOT ``Span/end()`` the span explicitly, because at the end of the `withSpan`
182+
/// operation closure returning the span will be closed automatically.
183+
///
184+
/// - Parameters:
185+
/// - operationName: The name of the operation being traced. This may be a handler function, database call, ...
186+
/// - baggage: The `Baggage` providing information on where to start the new ``Span``.
187+
/// - kind: The ``SpanKind`` of the new ``Span``.
188+
/// - clock: The clock to use as time source for the start time of the ``Span``
189+
/// - function: The function name in which the span was started
190+
/// - fileID: The `fileID` where the span was started.
191+
/// - line: The file line where the span was started.
192+
/// - operation: The operation that this span should be measuring
193+
/// - Returns: the value returned by `operation`
194+
/// - Throws: the error the `operation` has thrown (if any)
146195
public func withAnySpan<T, Clock: TracerClock>(
147196
_ operationName: String,
148197
clock: Clock,
@@ -173,6 +222,30 @@ extension LegacyTracerProtocol {
173222
}
174223
}
175224

225+
/// Start a new ``Span`` and automatically end when the `operation` completes,
226+
/// including recording the `error` in case the operation throws.
227+
///
228+
/// - Warning: This method will be deprecated in favor of `TracerProtocol/withSpan` as soon as this project is able to require Swift 5.7.
229+
///
230+
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
231+
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
232+
/// to pick up the task-local baggage is prevented. This can be useful when we know that
233+
/// we're about to start a top-level span, or if a span should be started from a different,
234+
/// stored away previously,
235+
///
236+
/// - Warning: You MUST NOT ``Span/end()`` the span explicitly, because at the end of the `withSpan`
237+
/// operation closure returning the span will be closed automatically.
238+
///
239+
/// - Parameters:
240+
/// - operationName: The name of the operation being traced. This may be a handler function, database call, ...
241+
/// - baggage: The `Baggage` providing information on where to start the new ``Span``.
242+
/// - kind: The ``SpanKind`` of the new ``Span``.
243+
/// - function: The function name in which the span was started
244+
/// - fileID: The `fileID` where the span was started.
245+
/// - line: The file line where the span was started.
246+
/// - operation: The operation that this span should be measuring
247+
/// - Returns: the value returned by `operation`
248+
/// - Throws: the error the `operation` has thrown (if any)
176249
public func withAnySpan<T>(
177250
_ operationName: String,
178251
baggage: @autoclosure () -> Baggage = .current ?? .topLevel,
@@ -196,6 +269,30 @@ extension LegacyTracerProtocol {
196269

197270
// ==== withAnySpan async -------------------------------------------------
198271

272+
/// Start a new ``Span`` and automatically end when the `operation` completes,
273+
/// including recording the `error` in case the operation throws.
274+
///
275+
/// - Warning: This method will be deprecated in favor of `TracerProtocol/withSpan` as soon as this project is able to require Swift 5.7.
276+
///
277+
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
278+
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
279+
/// to pick up the task-local baggage is prevented. This can be useful when we know that
280+
/// we're about to start a top-level span, or if a span should be started from a different,
281+
/// stored away previously,
282+
///
283+
/// - Warning: You MUST NOT ``Span/end()`` the span explicitly, because at the end of the `withSpan`
284+
/// operation closure returning the span will be closed automatically.
285+
///
286+
/// - Parameters:
287+
/// - operationName: The name of the operation being traced. This may be a handler function, database call, ...
288+
/// - baggage: The `Baggage` providing information on where to start the new ``Span``.
289+
/// - kind: The ``SpanKind`` of the new ``Span``.
290+
/// - function: The function name in which the span was started
291+
/// - fileID: The `fileID` where the span was started.
292+
/// - line: The file line where the span was started.
293+
/// - operation: The operation that this span should be measuring
294+
/// - Returns: the value returned by `operation`
295+
/// - Throws: the error the `operation` has thrown (if any)
199296
public func withAnySpan<T, Clock: TracerClock>(
200297
_ operationName: String,
201298
clock: Clock,
@@ -226,6 +323,30 @@ extension LegacyTracerProtocol {
226323
}
227324
}
228325

326+
/// Start a new ``Span`` and automatically end when the `operation` completes,
327+
/// including recording the `error` in case the operation throws.
328+
///
329+
/// - Warning: This method will be deprecated in favor of `TracerProtocol/withSpan` as soon as this project is able to require Swift 5.7.
330+
///
331+
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
332+
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
333+
/// to pick up the task-local baggage is prevented. This can be useful when we know that
334+
/// we're about to start a top-level span, or if a span should be started from a different,
335+
/// stored away previously,
336+
///
337+
/// - Warning: You MUST NOT ``Span/end()`` the span explicitly, because at the end of the `withSpan`
338+
/// operation closure returning the span will be closed automatically.
339+
///
340+
/// - Parameters:
341+
/// - operationName: The name of the operation being traced. This may be a handler function, database call, ...
342+
/// - baggage: The `Baggage` providing information on where to start the new ``Span``.
343+
/// - kind: The ``SpanKind`` of the new ``Span``.
344+
/// - function: The function name in which the span was started
345+
/// - fileID: The `fileID` where the span was started.
346+
/// - line: The file line where the span was started.
347+
/// - operation: The operation that this span should be measuring
348+
/// - Returns: the value returned by `operation`
349+
/// - Throws: the error the `operation` has thrown (if any)
229350
public func withAnySpan<T>(
230351
_ operationName: String,
231352
baggage: @autoclosure () -> Baggage = .current ?? .topLevel,
@@ -262,8 +383,7 @@ extension LegacyTracerProtocol {
262383
extension TracerProtocol {
263384
/// Start a new span returning an existential ``Span`` reference.
264385
///
265-
/// This API will be deprecated as soon as Swift 5.9 is released, and the Swift 5.7 requiring `TracerProtocol`
266-
/// is recommended instead.
386+
/// - Warning: This method will be deprecated in favor of `TracerProtocol/withSpan` as soon as this project is able to require Swift 5.7.
267387
///
268388
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
269389
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
@@ -312,8 +432,7 @@ extension TracerProtocol {
312432
/// Start a new ``Span`` and automatically end when the `operation` completes,
313433
/// including recording the `error` in case the operation throws.
314434
///
315-
/// This API will be deprecated as soon as Swift 5.9 is released, and the Swift 5.7 requiring `TracerProtocol`
316-
/// is recommended instead.
435+
/// - Warning: This method will be deprecated in favor of `TracerProtocol/withSpan` as soon as this project is able to require Swift 5.7.
317436
///
318437
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
319438
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
@@ -368,8 +487,7 @@ extension TracerProtocol {
368487
/// Start a new ``Span`` and automatically end when the `operation` completes,
369488
/// including recording the `error` in case the operation throws.
370489
///
371-
/// This API will be deprecated as soon as Swift 5.9 is released, and the Swift 5.7 requiring `TracerProtocol`
372-
/// is recommended instead.
490+
/// - Warning: This method will be deprecated in favor of `TracerProtocol/withSpan` as soon as this project is able to require Swift 5.7.
373491
///
374492
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
375493
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting

‎Sources/Tracing/TracerProtocol.swift

+46
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,29 @@ extension TracerProtocol {
167167
}
168168
}
169169

170+
/// Start a new ``Span`` and automatically end when the `operation` completes,
171+
/// including recording the `error` in case the operation throws.
172+
///
173+
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
174+
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
175+
/// to pick up the task-local baggage is prevented. This can be useful when we know that
176+
/// we're about to start a top-level span, or if a span should be started from a different,
177+
/// stored away previously,
178+
///
179+
/// - Warning: You MUST NOT ``Span/end()`` the span explicitly, because at the end of the `withSpan`
180+
/// operation closure returning the span will be closed automatically.
181+
///
182+
/// - Parameters:
183+
/// - operationName: The name of the operation being traced. This may be a handler function, database call, ...
184+
/// - baggage: The `Baggage` providing information on where to start the new ``Span``.
185+
/// - kind: The ``SpanKind`` of the new ``Span``.
186+
/// - clock: The clock to use as time source for the start time of the ``Span``
187+
/// - function: The function name in which the span was started
188+
/// - fileID: The `fileID` where the span was started.
189+
/// - line: The file line where the span was started.
190+
/// - operation: The operation that this span should be measuring
191+
/// - Returns: the value returned by `operation`
192+
/// - Throws: the error the `operation` has thrown (if any)
170193
public func withSpan<T>(
171194
_ operationName: String,
172195
baggage: @autoclosure () -> Baggage = .current ?? .topLevel,
@@ -248,6 +271,29 @@ extension TracerProtocol {
248271
}
249272
}
250273

274+
/// Start a new ``Span`` and automatically end when the `operation` completes,
275+
/// including recording the `error` in case the operation throws.
276+
///
277+
/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
278+
/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
279+
/// to pick up the task-local baggage is prevented. This can be useful when we know that
280+
/// we're about to start a top-level span, or if a span should be started from a different,
281+
/// stored away previously,
282+
///
283+
/// - Warning: You MUST NOT ``Span/end()`` the span explicitly, because at the end of the `withSpan`
284+
/// operation closure returning the span will be closed automatically.
285+
///
286+
/// - Parameters:
287+
/// - operationName: The name of the operation being traced. This may be a handler function, database call, ...
288+
/// - baggage: The `Baggage` providing information on where to start the new ``Span``.
289+
/// - kind: The ``SpanKind`` of the new ``Span``.
290+
/// - clock: The clock to use as time source for the start time of the ``Span``
291+
/// - function: The function name in which the span was started
292+
/// - fileID: The `fileID` where the span was started.
293+
/// - line: The file line where the span was started.
294+
/// - operation: The operation that this span should be measuring
295+
/// - Returns: the value returned by `operation`
296+
/// - Throws: the error the `operation` has thrown (if any)
251297
public func withSpan<T>(
252298
_ operationName: String,
253299
baggage: @autoclosure () -> Baggage = .current ?? .topLevel,

‎Tests/TracingTests/TracerTests.swift

+15
Original file line numberDiff line numberDiff line change
@@ -351,6 +351,21 @@ final class TracerTests: XCTestCase {
351351
#endif
352352
}
353353

354+
func testWithSpanSignatures() {
355+
let tracer = TestTracer()
356+
let clock = DefaultTracerClock()
357+
358+
#if swift(>=5.7.0)
359+
tracer.withSpan("") { _ in }
360+
tracer.withSpan("", clock: clock) { _ in }
361+
tracer.withSpan("", baggage: .topLevel) { _ in }
362+
#endif
363+
364+
tracer.withAnySpan("") { _ in }
365+
tracer.withAnySpan("", clock: clock) { _ in }
366+
tracer.withAnySpan("", baggage: .topLevel) { _ in }
367+
}
368+
354369
#if swift(>=5.7.0)
355370
// @available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
356371
/// Helper method to execute async operations until we can use async tests (currently incompatible with the generated LinuxMain file).

0 commit comments

Comments
 (0)