Skip to content
This repository was archived by the owner on Jul 11, 2025. It is now read-only.

Commit 398fba1

Browse files
yim-leeyim-lee
authored
DocC setup (#19)
* DocC setup * Fix license header
1 parent 6a8b708 commit 398fba1

File tree

6 files changed

+180
-4
lines changed

6 files changed

+180
-4
lines changed

‎Package.swift‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// swift-tools-version:5.3
1+
// swift-tools-version:5.6
22
import PackageDescription
33

44
let package = Package(
@@ -19,6 +19,7 @@ let package = Package(
1919
],
2020
dependencies: [
2121
.package(url: "https://github.com/apple/swift-distributed-tracing.git", from: "0.3.0"),
22+
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
2223
],
2324
targets: [
2425
.target(

‎[email protected]‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// swift-tools-version:5.3
2+
import PackageDescription
3+
4+
let package = Package(
5+
name: "swift-distributed-tracing-extras",
6+
platforms: [
7+
.macOS(.v10_13),
8+
.iOS(.v14),
9+
.tvOS(.v14),
10+
.watchOS(.v7),
11+
],
12+
products: [
13+
.library(
14+
name: "TracingOpenTelemetrySemanticConventions",
15+
targets: [
16+
"TracingOpenTelemetrySemanticConventions",
17+
]
18+
),
19+
],
20+
dependencies: [
21+
.package(url: "https://github.com/apple/swift-distributed-tracing.git", from: "0.3.0"),
22+
],
23+
targets: [
24+
.target(
25+
name: "TracingOpenTelemetrySemanticConventions",
26+
dependencies: [
27+
.product(name: "Tracing", package: "swift-distributed-tracing"),
28+
]
29+
),
30+
.testTarget(
31+
name: "TracingOpenTelemetrySemanticConventionsTests",
32+
dependencies: [
33+
.target(name: "TracingOpenTelemetrySemanticConventions"),
34+
.product(name: "Tracing", package: "swift-distributed-tracing"),
35+
]
36+
),
37+
]
38+
)

‎[email protected]‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// swift-tools-version:5.3
2+
import PackageDescription
3+
4+
let package = Package(
5+
name: "swift-distributed-tracing-extras",
6+
platforms: [
7+
.macOS(.v10_13),
8+
.iOS(.v14),
9+
.tvOS(.v14),
10+
.watchOS(.v7),
11+
],
12+
products: [
13+
.library(
14+
name: "TracingOpenTelemetrySemanticConventions",
15+
targets: [
16+
"TracingOpenTelemetrySemanticConventions",
17+
]
18+
),
19+
],
20+
dependencies: [
21+
.package(url: "https://github.com/apple/swift-distributed-tracing.git", from: "0.3.0"),
22+
],
23+
targets: [
24+
.target(
25+
name: "TracingOpenTelemetrySemanticConventions",
26+
dependencies: [
27+
.product(name: "Tracing", package: "swift-distributed-tracing"),
28+
]
29+
),
30+
.testTarget(
31+
name: "TracingOpenTelemetrySemanticConventionsTests",
32+
dependencies: [
33+
.target(name: "TracingOpenTelemetrySemanticConventions"),
34+
.product(name: "Tracing", package: "swift-distributed-tracing"),
35+
]
36+
),
37+
]
38+
)

‎Sources/TracingOpenTelemetrySemanticConventions/Docs.docc/index.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# ``TracingOpenTelemetrySemanticConventions``
2+
3+
OpenTelemetry semantic conventions.
4+
5+
## Overview
6+
7+
Additional module complementary to [swift-distributed-tracing](https://github.com/apple/swift-distributed-tracing).
8+
9+
## Getting started
10+
11+
This module is complementary to [swift-distributed-tracing](https://github.com/apple/swift-distributed-tracing) so you will want to depend on it (the API package).
12+
13+
Then, you can depend on the extras package:
14+
15+
```swift
16+
.package(url: "https://github.com/apple/swift-distributed-tracing.git", from: "..."),
17+
.package(url: "https://github.com/apple/swift-distributed-tracing-extras.git", from: "..."),
18+
```
19+
20+
> 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](https://github.com/apple/swift-distributed-tracing).
21+
22+
## Usage
23+
24+
The OpenTelemetry Semantic Conventions package provides span attributes to work with [OpenTelemetry's
25+
semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/trace/semantic_conventions).
26+
27+
Semantic attributes enable users of [swift-distributed-tracing](https://github.com/apple/swift-distributed-tracing) to
28+
set attributes on spans using a type-safe pre-defined and well known attributes, like this:
29+
30+
```swift
31+
import Tracing
32+
import TracingOpenTelemetrySemanticConventions
33+
34+
// Example framework code, which handles an incoming request and starts a span for handling a request:
35+
func wrapHandleRequest(exampleRequest: ExampleHTTPRequest) async throws -> ExampleHTTPResponse {
36+
try await InstrumentationSystem.tracer.withSpan(named: "test") { span in
37+
38+
// Set semantic HTTP attributes before
39+
span.attributes.http.method = exampleRequest.method
40+
span.attributes.http.url = exampleRequest.url
41+
// ...
42+
43+
// Hand off to user code to handle the request;
44+
// The current span already has all important semantic attributes set.
45+
let response = try await actualHandleRequest(exampleRequest: exampleRequest)
46+
47+
// ... set any response attributes ...
48+
49+
return response
50+
}
51+
}
52+
```
53+
54+
You can also read attributes that are set on a span using the same property syntax:
55+
56+
```swift
57+
assert(span.attributes.http.method == "GET")
58+
// etc.
59+
```
60+
61+
Without the semantic attributes package, one would be able to set the attributes using a type-unsafe approach, like this:
62+
63+
```swift
64+
span.attributes["http.method"] = "\(exampleRequest.method)"
65+
span.attributes["http.url"] = "\(exampleRequest.url)"
66+
```
67+
68+
however this approach is error-prone as one can accidentally record not quite the right type of value,
69+
or accidentally use a wrong, unexpected, key that would then not be understood by Otel tracing backends.

‎scripts/preview_docc.sh‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
#!/bin/bash
2+
##===----------------------------------------------------------------------===##
3+
##
4+
## This source file is part of the Swift Distributed Tracing open source project
5+
##
6+
## Copyright (c) 2022 Apple Inc. and the Swift Distributed Tracing project
7+
## authors
8+
## Licensed under Apache License v2.0
9+
##
10+
## See LICENSE.txt for license information
11+
##
12+
## SPDX-License-Identifier: Apache-2.0
13+
##
14+
##===----------------------------------------------------------------------===##
15+
16+
##===----------------------------------------------------------------------===##
17+
##
18+
## This source file is part of the Swift Distributed Actors open source project
19+
##
20+
## Copyright (c) 2018-2019 Apple Inc. and the Swift Distributed Actors project authors
21+
## Licensed under Apache License v2.0
22+
##
23+
## See LICENSE.txt for license information
24+
## See CONTRIBUTORS.md for the list of Swift Distributed Actors project authors
25+
##
26+
## SPDX-License-Identifier: Apache-2.0
27+
##
28+
##===----------------------------------------------------------------------===##
29+
30+
swift package --disable-sandbox preview-documentation --target $1

‎scripts/validate_license_headers.sh‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
##
44
## This source file is part of the Swift Distributed Tracing open source project
55
##
6-
## Copyright (c) 2020-2021 Apple Inc. and the Swift Distributed Tracing project
6+
## Copyright (c) 2020-2022 Apple Inc. and the Swift Distributed Tracing project
77
## authors
88
## Licensed under Apache License v2.0
99
##
@@ -32,7 +32,7 @@ here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
3232

3333
function replace_acceptable_years() {
3434
# this needs to replace all acceptable forms with 'YEARS'
35-
sed -e 's/2020-2021/YEARS/' -e 's/2020/YEARS/' -e 's/2021/YEARS/' -e 's/2022/YEARS/'
35+
sed -e 's/202[01]-202[12]/YEARS/' -e 's/202[012]/YEARS/'
3636
}
3737

3838
printf "=> Checking license headers\n"
@@ -46,7 +46,7 @@ for language in swift-or-c bash dtrace; do
4646
matching_files=( -name '*' )
4747
case "$language" in
4848
swift-or-c)
49-
exceptions=( -name c_nio_http_parser.c -o -name c_nio_http_parser.h -o -name cpp_magic.h -o -name Package.swift -o -name CNIOSHA1.h -o -name c_nio_sha1.c -o -name ifaddrs-android.c -o -name ifaddrs-android.h)
49+
exceptions=( -name Package.swift -o -name 'Package@*.swift' )
5050
matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' )
5151
cat > "$tmp" <<"EOF"
5252
//===----------------------------------------------------------------------===//

0 commit comments

Comments
 (0)