[Docs] Combined initial documentation work

Docs/README.md

@@ -0,0 +1,3 @@
+# Documentation landing page
+
+This documentation target exists only to serve as a landing page for self-hosted documentation.

Docs/SwiftDistributedTracing/Docs.docc/index.md

@@ -0,0 +1,29 @@
+# ``SwiftDistributedTracing``
+
+A Distributed Tracing API for Swift.
+
+## Overview
+
+This is a collection of Swift libraries enabling the instrumentation of server side applications using tools such as tracers. Our goal is to provide a common foundation that allows to freely choose how to instrument systems with minimal changes to your actual code.
+
+While Swift Distributed Tracing allows building all kinds of _instruments_, which can co-exist in applications transparently, its primary use is instrumenting multi-threaded and distributed systems with Distributed Traces.
+
+### Quickstart Guides
+
+We provide a number of guides aimed at getting your started with tracing your systems and have prepared them from three "angles":
+
+1. **Application developers** who create server-side applications
+    * please refer to the <doc:TraceYourApplication> guide.
+2. **Library/Framework developers** who provide building blocks to create these applications
+    * please refer to the <doc:InstrumentYourLibrary> guide. 
+3. **Instrument developers** who provide tools to collect distributed metadata about your application
+    * please refer to the <doc:ImplementATracer> guide.
+
+
+## Topics
+
+### Guides
+
+- <doc:TraceYourApplication>
+- <doc:InstrumentYourLibrary>
+- <doc:ImplementATracer>

Docs/SwiftDistributedTracing/empty.swift

@@ -0,0 +1,19 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Distributed Tracing open source project
+//
+// Copyright (c) 2020-2021 Apple Inc. and the Swift Distributed Tracing project
+// authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! //
+// This module is left purposefully empty of any source files, as it serves
+// only as a "landing page" for the documentation. This is in-place until docc
+// gains the ability to support package-wide documentation.
+// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! //

Samples/Dinner/.gitignore

@@ -0,0 +1,2 @@
+.build
+Package.resolved

Samples/Dinner/Package.swift

@@ -0,0 +1,23 @@
+// swift-tools-version:5.3
+import PackageDescription
+
+let package = Package(
+    name: "onboarding",
+    platforms: [
+        .macOS("14.0.0"),
+    ],
+    products: [
+        .executable(name: "onboarding", targets: ["Onboarding"]),
+    ],
+    dependencies: [
+        // This example uses the following tracer implementation:
+        .package(url: "https://github.com/slashmo/swift-otel", .branch("main")),
+        .package(url: "https://github.com/apple/swift-log.git", from: "1.5.0"),
+    ],
+    targets: [
+        .target(name: "Onboarding", dependencies: [
+            .product(name: "OpenTelemetry", package: "swift-otel"),
+            .product(name: "OtlpGRPCSpanExporting", package: "swift-otel"),
+        ]),
+    ]
+)

Samples/Dinner/README.md

@@ -0,0 +1,18 @@
+## Tracing Dinner Sample App
+
+In order to try this sample app, and visualize traces it produces, you should first run docker-compose in order
+to launch a docker containers which host a Zipkin UI and collector:
+
+```
+# cd Samples/Dinner
+
+docker-compose -f docker/docker-compose.yaml up --build
+```
+
+and then run the sample app which will produce a number of traces:
+
+```
+swift run -c release
+```
+
+Refer to the "Trace Your Application" guide in the documentation to learn more about how to interpret this sample.

Samples/Dinner/Sources/Onboarding/Clock+Extensions.swift

@@ -0,0 +1,29 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Distributed Tracing open source project
+//
+// Copyright (c) 2020-2023 Apple Inc. and the Swift Distributed Tracing project
+// authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift OpenTelemetry open source project
+//
+// Copyright (c) 2021 Moritz Lang and the Swift OpenTelemetry project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+func sleep(for duration: ContinuousClock.Duration) async {
+  try? await Task.sleep(until: ContinuousClock.now + duration, clock: .continuous)
+}

Samples/Dinner/Sources/Onboarding/Dinner.swift

@@ -0,0 +1,90 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Distributed Tracing open source project
+//
+// Copyright (c) 2020-2023 Apple Inc. and the Swift Distributed Tracing project
+// authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift OpenTelemetry open source project
+//
+// Copyright (c) 2021 Moritz Lang and the Swift OpenTelemetry project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+
+import Tracing
+
+func makeDinner() async throws -> Meal {
+  try await InstrumentationSystem.tracer.withSpan("makeDinner") { _ in
+    await sleep(for: .milliseconds(200))
+
+    async let veggies = try chopVegetables()
+    async let meat = marinateMeat()
+    async let oven = preheatOven(temperature: 350)
+    // ...
+    return try await cook(veggies, meat, oven)
+  }
+}
+
+func chopVegetables() async throws -> [Vegetable] {
+  try await otelChopping1.tracer().withSpan("chopVegetables") { _ in
+    // Chop the vegetables...!
+    //
+    // However, since chopping is a very difficult operation,
+    // one chopping task can be performed at the same time on a single service!
+    // (Imagine that... we cannot parallelize these two tasks, and need to involve another service).
+    async let carrot = try chop(.carrot, tracer: otelChopping1.tracer())
+    async let potato = try chop(.potato, tracer: otelChopping2.tracer())
+    return try await [carrot, potato]
+  }
+}
+
+func chop(_ vegetable: Vegetable, tracer: any Tracer) async throws -> Vegetable {
+  await tracer.withSpan("chop-\(vegetable)") { _ in
+    await sleep(for: .seconds(5))
+    // ...
+    return vegetable // "chopped"
+  }
+}
+
+func marinateMeat() async -> Meat {
+  await sleep(for: .milliseconds(620))
+
+  return await InstrumentationSystem.tracer.withSpan("marinateMeat") { _ in
+    await sleep(for: .seconds(3))
+    // ...
+    return Meat()
+  }
+}
+
+func preheatOven(temperature: Int) async -> Oven {
+  await InstrumentationSystem.tracer.withSpan("preheatOven") { _ in
+    // ...
+    await sleep(for: .seconds(6))
+    return Oven()
+  }
+}
+
+func cook(_: Any, _: Any, _: Any) async -> Meal {
+  await InstrumentationSystem.tracer.withSpan("cook") { span in
+    span.addEvent("children-asking-if-done-already")
+    await sleep(for: .seconds(3))
+    span.addEvent("children-asking-if-done-already-again")
+    await sleep(for: .seconds(2))
+    // ...
+    return Meal()
+  }
+}

Samples/Dinner/Sources/Onboarding/Model.swift

@@ -0,0 +1,35 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Distributed Tracing open source project
+//
+// Copyright (c) 2020-2023 Apple Inc. and the Swift Distributed Tracing project
+// authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift OpenTelemetry open source project
+//
+// Copyright (c) 2021 Moritz Lang and the Swift OpenTelemetry project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+
+struct Meal: Sendable {}
+struct Meat: Sendable {}
+struct Oven: Sendable {}
+enum Vegetable: Sendable {
+  case potato
+  case carrot
+}
+

Samples/Dinner/Sources/Onboarding/main.swift

@@ -0,0 +1,77 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Distributed Tracing open source project
+//
+// Copyright (c) 2020-2023 Apple Inc. and the Swift Distributed Tracing project
+// authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift OpenTelemetry open source project
+//
+// Copyright (c) 2021 Moritz Lang and the Swift OpenTelemetry project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+
+import Logging
+import NIO
+import OpenTelemetry
+import OtlpGRPCSpanExporting
+import Tracing
+
+// ==== ----------------------------------------------------------------------------------------------------------------
+
+let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+
+LoggingSystem.bootstrap { label in
+  var handler = StreamLogHandler.standardOutput(label: label)
+  handler.logLevel = .trace
+  return handler
+}
+
+// ==== ----------------------------------------------------------------------------------------------------------------
+// MARK: - Configure OTel
+
+let exporter = OtlpGRPCSpanExporter(config: OtlpGRPCSpanExporter.Config(eventLoopGroup: group))
+let processor = OTel.SimpleSpanProcessor(exportingTo: exporter)
+let otel = OTel(serviceName: "DinnerService", eventLoopGroup: group, processor: processor)
+
+let otelChopping1 = OTel(serviceName: "ChoppingService-1", eventLoopGroup: group, processor: processor)
+let otelChopping2 = OTel(serviceName: "ChoppingService-2", eventLoopGroup: group, processor: processor)
+
+// First start `OTel`, then bootstrap the instrumentation system.
+// This makes sure that all components are ready to begin handling spans.
+try otel.start().wait()
+try otelChopping1.start().wait()
+try otelChopping2.start().wait()
+
+// By bootstrapping the instrumentation system, our dependencies
+// compatible with "Swift Distributed Tracing" will also automatically
+// use the "OpenTelemetry Swift" Tracer 🚀.
+InstrumentationSystem.bootstrap(otel.tracer())
+
+// ==== ----------------------------------------------------------------------------------------------------------------
+// MARK: - Run the sample app
+
+let dinner = try await makeDinner()
+
+// ==== ----------------------------------------------------------------------------------------------------------------
+// MARK: - Shutdown
+
+// Wait a second to let the exporter finish before shutting down.
+sleep(2)
+
+try otel.shutdown().wait()
+try group.syncShutdownGracefully()

Samples/Dinner/docker/collector-config.yaml

@@ -0,0 +1,24 @@
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: otel-collector:4317
+
+exporters:
+  logging:
+    verbosity: detailed
+
+  jaeger:
+    endpoint: "jaeger:14250"
+    tls:
+      insecure: true
+
+  zipkin:
+    endpoint: "http://zipkin:9411/api/v2/spans"
+
+
+service:
+  pipelines:
+    traces:
+      receivers: otlp
+      exporters: [logging, jaeger, zipkin]

Samples/Dinner/docker/docker-compose.yaml

@@ -0,0 +1,26 @@
+version: '3'
+services:
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:latest
+    command: ["--config=/etc/config.yaml"]
+    volumes:
+      - ./collector-config.yaml:/etc/config.yaml
+    ports:
+      - "4317:4317"
+    networks: [exporter]
+    depends_on: [zipkin, jaeger]
+
+  zipkin:
+    image: openzipkin/zipkin:latest
+    ports:
+      - "9411:9411"
+    networks: [exporter]
+
+  jaeger:
+    image: jaegertracing/all-in-one
+    ports:
+      - "16686:16686"
+    networks: [exporter]
+
+networks:
+  exporter: