Skip to content

Commit

Permalink
feat: use BaggageContext to get and propagate context (#31)
Browse files Browse the repository at this point in the history
* feat: use BaggageContext to get and propagate context

Closes #23
Affects #19

* docs: update documentation
  • Loading branch information
pokryfka committed Jul 25, 2020
1 parent 2d8e57f commit e8ebae9
Show file tree
Hide file tree
Showing 22 changed files with 235 additions and 240 deletions.
3 changes: 2 additions & 1 deletion Documentation/Reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@

## Extensions

- [BaggageContext](extensions/BaggageContext.md)
- [XRayRecorder](extensions/XRayRecorder.md)
- [XRayRecorder.Segment](extensions/XRayRecorder.Segment.md)
- [XRayRecorder.Segment.Cause](extensions/XRayRecorder.Segment.Cause.md)
Expand All @@ -42,4 +43,4 @@
- [Encoder.OutboundOut](typealiases/Encoder.OutboundOut.md)
- [Segment.Metadata](typealiases/Segment.Metadata.md)

This file was generated by [SourceDocs](https://github.com/eneko/SourceDocs) on 2020-07-24 15:43:16 +0000
This file was generated by [SourceDocs](https://github.com/eneko/SourceDocs) on 2020-07-25 06:07:01 +0000
12 changes: 2 additions & 10 deletions Documentation/Reference/classes/XRayRecorder.Segment.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,12 @@ At a minimum, a segment records the name, ID, start time, trace ID, and end time
- [AWS X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html)

## Properties
### `context`
### `baggage`

```swift
public var context: TraceContext
public var baggage: BaggageContext
```

### `id`

```swift
public var id: ID
```

A 64-bit identifier for the segment, unique among segments in the same trace, in **16 hexadecimal digits**.

### `name`

```swift
Expand Down
45 changes: 34 additions & 11 deletions Documentation/Reference/classes/XRayRecorder.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,27 +17,50 @@ public class XRayRecorder
public init(emitter: XRayEmitter, config: Config = Config())
```

### `beginSegment(name:parentId:aws:metadata:)`
### `beginSegment(name:context:metadata:)`

```swift
public func beginSegment(name: String, parentId: Segment.ID? = nil,
aws: Segment.AWS? = nil, metadata: Segment.Metadata? = nil) -> Segment
public func beginSegment(name: String, context: TraceContext, metadata: Segment.Metadata? = nil) -> Segment
```

### `beginSubsegment(name:parentId:aws:metadata:)`
Creates new segment.
- Parameters:
- name: segment name
- context: the trace context
- metadata: segment metadata
- Returns: new segment

```swift
public func beginSubsegment(name: String, parentId: Segment.ID,
aws: Segment.AWS? = nil, metadata: Segment.Metadata? = nil) -> Segment
```
#### Parameters

| Name | Description |
| ---- | ----------- |
| name | segment name |
| context | the trace context |
| metadata | segment metadata |

### `beginSegment(name:context:aws:metadata:)`
### `beginSegment(name:baggage:metadata:)`

```swift
public func beginSegment(name: String, context: TraceContext,
aws: Segment.AWS? = nil, metadata: Segment.Metadata? = nil) -> Segment
public func beginSegment(name: String, baggage: BaggageContext, metadata: Segment.Metadata? = nil) -> XRayRecorder.Segment
```

Creates new segment.
Extracts the thre context from the baggage.
Creates new if the baggage does not contain a valid XRay Trace Context.
- Parameters:
- name: segment name
- baggage: baggage with the trace context
- metadata: segment metadata
- Returns: new segment

#### Parameters

| Name | Description |
| ---- | ----------- |
| name | segment name |
| baggage | baggage with the trace context |
| metadata | segment metadata |

### `wait(_:)`

```swift
Expand Down
15 changes: 15 additions & 0 deletions Documentation/Reference/extensions/BaggageContext.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
**EXTENSION**

# `BaggageContext`
```swift
public extension BaggageContext
```

## Properties
### `xRayContext`

```swift
var xRayContext: XRayRecorder.TraceContext?
```

XRay Trace Context..
19 changes: 6 additions & 13 deletions Documentation/Reference/extensions/XRayRecorder.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,18 @@ extension XRayRecorder
```

## Methods
### `segment(name:parentId:metadata:body:)`
### `segment(name:context:metadata:body:)`

```swift
public func segment<T>(name: String, parentId: Segment.ID? = nil, metadata: XRayRecorder.Segment.Metadata? = nil,
public func segment<T>(name: String, context: TraceContext, metadata: XRayRecorder.Segment.Metadata? = nil,
body: (Segment) throws -> T)
rethrows -> T
```

### `segment(name:traceHeader:metadata:body:)`
### `segment(name:baggage:metadata:body:)`

```swift
public func segment<T>(name: String, traceHeader: TraceContext, metadata: XRayRecorder.Segment.Metadata? = nil,
public func segment<T>(name: String, baggage: BaggageContext, metadata: XRayRecorder.Segment.Metadata? = nil,
body: (Segment) throws -> T)
rethrows -> T
```
Expand All @@ -34,16 +34,9 @@ public convenience init(config: Config = Config(), eventLoopGroup: EventLoopGrou
public func flush(on eventLoop: EventLoop) -> EventLoopFuture<Void>
```

### `segment(name:parentId:metadata:body:)`
### `segment(name:context:metadata:body:)`

```swift
public func segment<T>(name: String, parentId: Segment.ID? = nil, metadata: Segment.Metadata? = nil,
public func segment<T>(name: String, context: TraceContext, metadata: Segment.Metadata? = nil,
body: () -> EventLoopFuture<T>) -> EventLoopFuture<T>
```

### `beginSegment(name:parentId:metadata:body:)`

```swift
public func beginSegment<T>(name: String, parentId: Segment.ID? = nil, metadata: Segment.Metadata? = nil,
body: (Segment) -> EventLoopFuture<T>) -> EventLoopFuture<(Segment, T)>
```
9 changes: 6 additions & 3 deletions Documentation/Reference/structs/XRayRecorder.TraceContext.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@
public struct TraceContext
```

XRay Trace Context propagated in a tracing header.

# Tracing header
All requests are traced, up to a configurable minimum.
After reaching that minimum, a percentage of requests are traced to avoid unnecessary cost.
The sampling decision and trace ID are added to HTTP requests in **tracing headers** named `X-Amzn-Trace-Id`.
Expand Down Expand Up @@ -46,15 +49,15 @@ root trace ID
### `parentId`

```swift
public let parentId: Segment.ID?
public var parentId: Segment.ID?
```

parent segment ID

### `sampled`

```swift
public let sampled: XRayRecorder.SampleDecision
public var sampled: XRayRecorder.SampleDecision
```

sampling decision
Expand All @@ -63,7 +66,7 @@ sampling decision
### `init(traceId:parentId:sampled:)`

```swift
public init(traceId: XRayRecorder.TraceID = .init(), parentId: XRayRecorder.Segment.ID? = nil, sampled: XRayRecorder.SampleDecision)
public init(traceId: XRayRecorder.TraceID = .init(), parentId: XRayRecorder.Segment.ID? = nil, sampled: XRayRecorder.SampleDecision = .sampled)
```

Creates new Trace Context.
Expand Down
1 change: 0 additions & 1 deletion Examples/Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@ let package = Package(
name: "AWSXRayRecorderExampleSDK",
dependencies: [
.product(name: "AWSXRayRecorder", package: "aws-xray-sdk-swift"),
.product(name: "AWSXRayRecorderSDK", package: "aws-xray-sdk-swift"),
.product(name: "AsyncHTTPClient", package: "async-http-client"),
.product(name: "AWSS3", package: "aws-sdk-swift"),
]
Expand Down
6 changes: 4 additions & 2 deletions Examples/Sources/AWSXRayRecorderExample/main.swift
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,10 @@ enum ExampleError: Error {

let recorder = XRayRecorder()

let context = XRayRecorder.TraceContext()

// begin and end (sub)segments explicitly
let segment = recorder.beginSegment(name: "Segment 1")
let segment = recorder.beginSegment(name: "Segment 1", context: context)
segment.setAnnotation(98101, forKey: "zip_code")
segment.setMetadata(["debug": ["test": "Metadata string"]])
_ = segment.beginSubsegment(name: "Subsegment 1.1 in progress")
Expand All @@ -40,7 +42,7 @@ usleep(100_000)
subsegment.end()

// use closures for convenience
recorder.segment(name: "Segment 2") { segment in
recorder.segment(name: "Segment 2", context: context) { segment in
try? segment.subsegment(name: "Subsegment 2.1") { segment in
_ = segment.subsegment(name: "Subsegment 2.1.1 with Result") { _ -> String in
usleep(100_000)
Expand Down
5 changes: 2 additions & 3 deletions Examples/Sources/AWSXRayRecorderExampleSDK/main.swift
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@
import AsyncHTTPClient
import AWSS3
import AWSXRayRecorder
import AWSXRayRecorderSDK
import NIO

func env(_ name: String) -> String? {
Expand Down Expand Up @@ -46,10 +45,10 @@ let recorder = XRayRecorder(
eventLoopGroup: group
)

// TODO: WIP
// TODO: WIP https://github.com/pokryfka/aws-xray-sdk-swift/issues/19

let awsClient = AWSClient(
middlewares: [XRayMiddleware(recorder: recorder, name: "S3")],
// middlewares: [XRayMiddleware(recorder: recorder, name: "S3")],
httpClientProvider: .shared(httpClient)
)
let s3 = S3(client: awsClient)
Expand Down
11 changes: 2 additions & 9 deletions Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,12 @@ let package = Package(
products: [
.library(name: "AWSXRayRecorder", targets: ["AWSXRayRecorder"]),
.library(name: "AWSXRayRecorderLambda", targets: ["AWSXRayRecorderLambda"]),
.library(name: "AWSXRayRecorderSDK", targets: ["AWSXRayRecorderSDK"]),
],
dependencies: [
.package(url: "https://github.com/apple/swift-nio.git", .upToNextMajor(from: "2.17.0")),
.package(url: "https://github.com/apple/swift-log.git", .upToNextMajor(from: "1.0.0")),
.package(url: "https://github.com/Flight-School/AnyCodable.git", .upToNextMajor(from: "0.3.0")),
.package(url: "https://github.com/swift-aws/aws-sdk-swift-core.git", .upToNextMinor(from: "5.0.0-alpha.5")),
.package(name: "swift-baggage-context", url: "https://github.com/slashmo/gsoc-swift-baggage-context.git", .upToNextMinor(from: "0.1.0")),
.package(url: "https://github.com/swift-server/swift-aws-lambda-runtime.git", .upToNextMajor(from: "0.2.0")),
],
targets: [
Expand All @@ -26,6 +25,7 @@ let package = Package(
.product(name: "NIO", package: "swift-nio"),
.product(name: "Logging", package: "swift-log"),
.product(name: "AnyCodable", package: "AnyCodable"),
.product(name: "Baggage", package: "swift-baggage-context"),
]
),
.target(
Expand All @@ -35,13 +35,6 @@ let package = Package(
.product(name: "AWSLambdaRuntime", package: "swift-aws-lambda-runtime"),
]
),
.target(
name: "AWSXRayRecorderSDK",
dependencies: [
.byName(name: "AWSXRayRecorder"),
.product(name: "AWSSDKSwiftCore", package: "aws-sdk-swift-core"),
]
),
.testTarget(
name: "AWSXRayRecorderTests",
dependencies: ["AWSXRayRecorder"]
Expand Down
41 changes: 41 additions & 0 deletions Sources/AWSXRayRecorder/Baggage.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the aws-xray-sdk-swift open source project
//
// Copyright (c) 2020 pokryfka and the aws-xray-sdk-swift project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//

import Baggage

private enum XRayContextKey: BaggageContextKey {
typealias Value = XRayRecorder.TraceContext
var name: String { "XRayTraceContext" }
}

public extension BaggageContext {
/// XRay Trace Context..
var xRayContext: XRayRecorder.TraceContext? {
get {
self[XRayContextKey.self]
}
set {
self[XRayContextKey.self] = newValue
}
}
}

internal extension BaggageContext {
func withParent(_ parentId: XRayRecorder.Segment.ID) throws -> BaggageContext {
guard var context = xRayContext else { throw XRayRecorder.TraceError.missingContext }
context.parentId = parentId
var updated = self
updated.xRayContext = context
return updated
}
}
10 changes: 6 additions & 4 deletions Sources/AWSXRayRecorder/Recorder+Helpers.swift
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,16 @@
//
//===----------------------------------------------------------------------===//

import Baggage

extension XRayRecorder {
@inlinable
@discardableResult
public func segment<T>(name: String, parentId: Segment.ID? = nil, metadata: XRayRecorder.Segment.Metadata? = nil,
public func segment<T>(name: String, context: TraceContext, metadata: XRayRecorder.Segment.Metadata? = nil,
body: (Segment) throws -> T)
rethrows -> T
{
let segment = beginSegment(name: name, parentId: parentId, metadata: metadata)
let segment = beginSegment(name: name, context: context, metadata: metadata)
defer {
segment.end()
}
Expand All @@ -32,11 +34,11 @@ extension XRayRecorder {

@inlinable
@discardableResult
public func segment<T>(name: String, traceHeader: TraceContext, metadata: XRayRecorder.Segment.Metadata? = nil,
public func segment<T>(name: String, baggage: BaggageContext, metadata: XRayRecorder.Segment.Metadata? = nil,
body: (Segment) throws -> T)
rethrows -> T
{
let segment = beginSegment(name: name, context: traceHeader, metadata: metadata)
let segment = beginSegment(name: name, baggage: baggage, metadata: metadata)
defer {
segment.end()
}
Expand Down
Loading

0 comments on commit e8ebae9

Please sign in to comment.