apple/swift-distributed-tracing-baggage

Minimal type-safe context propagation container

Swift Service Context

ServiceContext is a minimal (zero-dependency) context propagation container, intended to "carry" items for purposes of cross-cutting tools to be built on top of it.

It is modeled after the concepts explained in W3C Baggage and the in the spirit of Tracing Plane 's "Baggage Context" type, although by itself it does not define a specific serialization format.

See https://github.com/apple/swift-distributed-tracing for actual instrument types and implementations which can be used to deploy various cross-cutting instruments all reusing the same baggage type. More information can be found in the SSWG meeting notes.

Overview

ServiceContext serves as currency type for carrying around additional contextual information between Swift tasks and functions.

One generally starts from a "top level" (empty) or the "current" (ServiceContext.current) context and then adds values to it.

The context is a value type and is propagated using task-local values so it can be safely used from concurrent contexts like this:

var context = ServiceContext.topLevel
context[FirstTestKey.self] = 42

func exampleFunction() async -> Int {
    guard let context = ServiceContext.current {
        return 0
    }
    guard let value = context[FirstTestKey.self] {
        return 0
    }
    print("test = \(value)") // test = 42
    return value
}

let c = ServiceContext.withValue(context) {
    await exampleFunction()
}
assert(c == 42)

ServiceContext is a fundamental building block for how distributed tracing propagages trace identifiers.

Dependency

In order to depend on this library you can use the Swift Package Manager, and add the following dependency to your Package.swift:

dependencies: [
  .package(
    url: "https://github.com/apple/swift-service-context.git",
    from: "1.0.0"
  )
]

and depend on the module in your target:

targets: [
    .target(
        name: "MyAwesomeApp",
        dependencies: [
            .product(
              name: "ServiceContextModule",
              package: "swift-service-context"
            ),
        ]
    ),
    // ...
]

Contributing

Please make sure to run the ./scripts/soundness.sh script when contributing, it checks formatting and similar things.

You can ensure it always runs and passes before you push by installing a pre-push hook with git:

echo './scripts/soundness.sh' > .git/hooks/pre-push
chmod +x .git/hooks/pre-push

swift-distributed-tracing-baggage's Issues

Remove LoggingContext and BaggageCore

In the future, Logging should be handled elsewhere.

Remove BaggageCore

The reason for splitting up Baggage into two repositories, Baggage and BaggageCore was to have one "pure" library without the Logging dependency which others could depend on. Because the Logging dependency will be dropped from this repo, we can also get rid of baggage-core altogether and instead put its source files into this repo.

Merge Final API proposal after reviews conclude

Need to bring in slashmo/gsoc-swift-baggage-context#34 from the repo over here and ensure all types are proper.

Update README according to Final API

`Baggage.$current.withValue` vs `Baggage.withValue` and actors

If I call either Baggage.$current.withValue or Baggage.withValue from an actor where the closure accesses the same actor I get different results. The first compiles fine and the second errors with the following

non-sendable type '() async throws -> ()' exiting actor-isolated context in call to non-isolated static method 'withValue(_:operation:)' cannot cross actor boundary

Baggage namespace has conflict with `CoreBaggage.Baggage`

This package produces a library called Baggage.

The library Baggage uses @_exported import CoreBaggage.
CoreBaggage has a struct Baggage.

For this reason it is not possible to use the Baggage namespace. The compiler will always detect Baggage as the struct form CoreBaggage.

Failing code:

import Baggage

extension Lambda.Context: Baggage.LoggingContext {}

Produces the compile error: 'LoggingContext' is not a member of struct 'CoreBaggage.Baggage'.

requiring Sendable from Baggage is source breaking

This commit required that types confirming to BaggageKey are now Sendable on Swift 5.5+.

That change obviously makes sense but unfortunately, it's source breaking...

That's fine by SemVer (because this package is version 0.x) but probably still an issue.

Compilation fails on Swift 5.5 [known issue until Xcode ships with macOS 12 SDK]

Environment:

swift --version
swift-driver version: 1.26.9 Apple Swift version 5.5 (swiftlang-1300.0.31.1 clang-1300.0.29.1)
Target: x86_64-apple-macosx11.0

Steps:

swift build

Result:

/xxx/swift-distributed-tracing-baggage/Sources/InstrumentationBaggage/Baggage.swift:232:5: error: unknown attribute 'TaskLocal'
    @TaskLocal public static var current: Baggage?
    ^
[2/2] Compiling InstrumentationBaggage BaggageKey.swift

Expected result:

Additional steps/requirements like extra compilation flags described in README.md and, if possible, included in the manifest file Package.swift.

Consider renaming module/repo to something that doesn't mention distributed tracing/instrumentation

The Baggage type is useful more widely than just (distributed) tracing & instrumentation. We should seriously consider renaming repo & module. Systems like swift-llbuild2 currently use a (very bad) definition of Context because you need to be able to pass data "through" the llbuild2 build engine itself (as you, the user construct the build graph as well as execute the individual build steps).

Access control per baggage item key

This mirrors the slashmo/gsoc-swift-baggage-context#35 ticket

--

Additional capability similar to privacy in os_log to be added to baggage keys.

A key has to define if it wants to be included in forEach and if it wants to be logged.

[...] mark a key as containing sensitive information . for example, you may have a key that carries sensitive user information and that you never want the collectors to log

via @tomerd