https://github.com/apple/swift-service-context
Minimal type-safe context propagation container
https://github.com/apple/swift-service-context
async-context baggage baggage-context concurrency context-propagation distributed-systems sswg trace-context
Last synced: 5 months ago
JSON representation
Minimal type-safe context propagation container
- Host: GitHub
- URL: https://github.com/apple/swift-service-context
- Owner: apple
- License: apache-2.0
- Created: 2020-09-24T19:39:15.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-13T10:35:48.000Z (about 1 year ago)
- Last Synced: 2025-03-29T03:09:55.014Z (about 1 year ago)
- Topics: async-context, baggage, baggage-context, concurrency, context-propagation, distributed-systems, sswg, trace-context
- Language: Swift
- Homepage: https://github.com/apple/swift-distributed-tracing
- Size: 166 KB
- Stars: 84
- Watchers: 29
- Forks: 22
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Swift Service Context
[](https://swift.org/download/)
[](https://swift.org/download/)
[](https://swift.org/download/)
`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](https://w3c.github.io/baggage/) and
in the spirit of [Tracing Plane](https://cs.brown.edu/~jcmace/papers/mace18universal.pdf) '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](https://gist.github.com/ktoso/4d160232407e4d5835b5ba700c73de37#swift-baggage-context--distributed-tracing).
## 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:
```swift
var context = ServiceContext.topLevel
context[FirstTestKey.self] = 42
func exampleFunction() async -> Int {
guard let context = ServiceContext.current else {
return 0
}
guard let value = context[FirstTestKey.self] else {
return 0
}
print("test = \(value)") // test = 42
return value
}
let c = await ServiceContext.withValue(context) {
await exampleFunction()
}
assert(c == 42)
```
`ServiceContext` is a fundamental building block for how distributed tracing propagates 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`:
```swift
dependencies: [
.package(
url: "https://github.com/apple/swift-service-context.git",
from: "1.0.0"
)
]
```
and depend on the module in your target:
```swift
targets: [
.target(
name: "MyAwesomeApp",
dependencies: [
.product(
name: "ServiceContextModule",
package: "swift-service-context"
),
]
),
// ...
]
```