From 01313611f40e4f62780480966e916f9721bdd1d1 Mon Sep 17 00:00:00 2001 From: Konrad `ktoso` Malawski Date: Thu, 15 Oct 2020 11:07:04 +0900 Subject: [PATCH 1/4] review feedback, accept Int64 in attributes --- Sources/Tracing/Span.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/Tracing/Span.swift b/Sources/Tracing/Span.swift index 78400a5b..621d0291 100644 --- a/Sources/Tracing/Span.swift +++ b/Sources/Tracing/Span.swift @@ -162,7 +162,7 @@ extension SpanAttributeNamespace { /// The value of an attribute used to describe a `Span` or `SpanEvent`. public enum SpanAttribute: Equatable { case string(String) - case int(Int) + case int(Int64) case double(Double) case bool(Bool) From 80802783a6a63abf1669d8495a789fbd8b7982d7 Mon Sep 17 00:00:00 2001 From: Konrad `ktoso` Malawski Date: Mon, 19 Oct 2020 11:51:45 +0900 Subject: [PATCH 2/4] more docs on span end() --- Sources/Tracing/Span.swift | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/Sources/Tracing/Span.swift b/Sources/Tracing/Span.swift index 48b2f77f..171f3959 100644 --- a/Sources/Tracing/Span.swift +++ b/Sources/Tracing/Span.swift @@ -48,13 +48,35 @@ public protocol Span: AnyObject { /// End this `Span` at the given timestamp. /// - /// Ending a `Span` MUST be idempotent. + /// ### Rules about ending Spans + /// A Span must be ended only ONCE. Ending a span multiple times or never at all is considered a programming error. + /// + /// A tracer implementation MAY decide to crash the application if e.g. running in debug mode and noticing such misuse. + /// + /// Implementations SHOULD prevent double-emitting by marking a span as ended internally, however it still is a + /// programming mistake to rely on this behavior. + /// /// - Parameter timestamp: The `Timestamp` at which the span ended. + /// + /// - SeeAlso: `Span.end()` which automatically uses the "current" time as timestamp. func end(at timestamp: Timestamp) } extension Span { /// End this `Span` at the current timestamp. + /// + /// ### Rules about ending Spans + /// A Span must be ended only ONCE. Ending a span multiple times or never at all is considered a programming error. + /// + /// A tracer implementation MAY decide to crash the application if e.g. running in debug mode and noticing such misuse. + /// + /// Implementations SHOULD prevent double-emitting by marking a span as ended internally, however it still is a + /// programming mistake to rely on this behavior. + /// + /// - Parameter timestamp: The `Timestamp` at which the span ended. + /// + /// - SeeAlso: `Span.end(at:)` which allows passing in a specific timestamp, e.g. if the operation was ended and recorded somewhere and we need to post-factum record it. + /// Generally though prefer using the `end()` version of this API in user code and structure your system such that it can be called in the right place and time. public func end() { self.end(at: .now()) } From db9f43c77e6d50d43244844c959a5123f20ba6ba Mon Sep 17 00:00:00 2001 From: Konrad `ktoso` Malawski Date: Tue, 20 Oct 2020 10:14:07 +0900 Subject: [PATCH 3/4] Update Sources/Tracing/Span.swift Co-authored-by: Yim Lee --- Sources/Tracing/Span.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/Tracing/Span.swift b/Sources/Tracing/Span.swift index 171f3959..9d4a950d 100644 --- a/Sources/Tracing/Span.swift +++ b/Sources/Tracing/Span.swift @@ -66,7 +66,7 @@ extension Span { /// End this `Span` at the current timestamp. /// /// ### Rules about ending Spans - /// A Span must be ended only ONCE. Ending a span multiple times or never at all is considered a programming error. + /// A Span must be ended only ONCE. Ending a Span multiple times or never at all is considered a programming error. /// /// A tracer implementation MAY decide to crash the application if e.g. running in debug mode and noticing such misuse. /// From 9b33f746f485f5c2dd81e172920ef829021a3aae Mon Sep 17 00:00:00 2001 From: Konrad `ktoso` Malawski Date: Tue, 20 Oct 2020 10:14:14 +0900 Subject: [PATCH 4/4] Update Sources/Tracing/Span.swift Co-authored-by: Yim Lee --- Sources/Tracing/Span.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/Tracing/Span.swift b/Sources/Tracing/Span.swift index 9d4a950d..b6e17848 100644 --- a/Sources/Tracing/Span.swift +++ b/Sources/Tracing/Span.swift @@ -49,7 +49,7 @@ public protocol Span: AnyObject { /// End this `Span` at the given timestamp. /// /// ### Rules about ending Spans - /// A Span must be ended only ONCE. Ending a span multiple times or never at all is considered a programming error. + /// A Span must be ended only ONCE. Ending a Span multiple times or never at all is considered a programming error. /// /// A tracer implementation MAY decide to crash the application if e.g. running in debug mode and noticing such misuse. ///