Swift Distributed Tracing Extras ships the following extra modules:
This module is complementary to swift-distributed-tracing so you will want to depend on it (the API package).
Then, you can depend on the extras package:
.package(url: "https://github.com/apple/swift-distributed-tracing.git", from: "..."),
.package(url: "https://github.com/apple/swift-distributed-tracing-extras.git", from: "..."),If you are writing an application, rather than a library, you'll also want to depend on a specific tracer implementation. For available implementations refer to the swift-distributed-tracing README.md.
The OpenTelemetry Semantic Conventions package provides span attributes to work with OpenTelemetry's semantic conventions.
Semantic attributes enable users of swift-distributed-tracing to set attributes on spans using a type-safe pre-defined and well known attributes, like this:
import Tracing
import TracingOpenTelemetrySemanticConventions
// Example framework code, which handles an incoming request and starts a span for handling a request:
func wrapHandleRequest(exampleRequest: ExampleHTTPRequest) async throws -> ExampleHTTPResponse {
try await InstrumentationSystem.tracer.withSpan(named: "test") { span in
// Set semantic HTTP attributes before
span.attributes.http.method = exampleRequest.method
span.attributes.http.url = exampleRequest.url
// ...
// Hand off to user code to handle the request;
// The current span already has all important semantic attributes set.
let response = try await actualHandleRequest(exampleRequest: exampleRequest)
// ... set any response attributes ...
return response
}
}You can also read attributes that are set on a span using the same property syntax:
assert(span.attributes.http.method == "GET")
// etc.Without the semantic attributes package, one would be able to set the attributes using a type-unsafe approach, like this:
span.attributes["http.method"] = "\(exampleRequest.method)"
span.attributes["http.url"] = "\(exampleRequest.url)"however this approach is error-prone as one can accidentally record not quite the right type of value, or accidentally use a wrong, unexpected, key that would then not be understood by Otel tracing backends.
This module supports: Swift 5.4+, on all platforms Swift is available.