apple · yim-lee · Aug 5, 2022 · Jul 28, 2022 · Jul 28, 2022 · Aug 1, 2022
diff --git a/Package.swift b/Package.swift
@@ -1,10 +1,10 @@
-// swift-tools-version:5.0
+// swift-tools-version:5.6
 
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftStatsdClient open source project
 //
-// Copyright (c) 2019 the SwiftStatsdClient project authors
+// Copyright (c) 2019-2022 the SwiftStatsdClient project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -24,9 +24,13 @@ let package = Package(
     dependencies: [
         .package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
         .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
     ],
     targets: [
-        .target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
+        .target(name: "StatsdClient", dependencies: [
+            .product(name: "CoreMetrics", package: "swift-metrics"),
+            .product(name: "NIO", package: "swift-nio"),
+        ]),
         .testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
     ]
 )
diff --git a/Package@swift-5.0.swift b/Package@swift-5.0.swift
@@ -0,0 +1,32 @@
+// swift-tools-version:5.0
+
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftStatsdClient open source project
+//
+// Copyright (c) 2019 the SwiftStatsdClient project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-statsd-client",
+    products: [
+        .library(name: "StatsdClient", targets: ["StatsdClient"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
+    ],
+    targets: [
+        .target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
+        .testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
+    ]
+)
diff --git a/Package@swift-5.1.swift b/Package@swift-5.1.swift
@@ -0,0 +1,32 @@
+// swift-tools-version:5.0
+
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftStatsdClient open source project
+//
+// Copyright (c) 2019 the SwiftStatsdClient project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-statsd-client",
+    products: [
+        .library(name: "StatsdClient", targets: ["StatsdClient"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
+    ],
+    targets: [
+        .target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
+        .testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
+    ]
+)
diff --git a/Package@swift-5.2.swift b/Package@swift-5.2.swift
@@ -0,0 +1,32 @@
+// swift-tools-version:5.0
+
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftStatsdClient open source project
+//
+// Copyright (c) 2019 the SwiftStatsdClient project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-statsd-client",
+    products: [
+        .library(name: "StatsdClient", targets: ["StatsdClient"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
+    ],
+    targets: [
+        .target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
+        .testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
+    ]
+)
diff --git a/Package@swift-5.3.swift b/Package@swift-5.3.swift
@@ -0,0 +1,32 @@
+// swift-tools-version:5.0
+
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftStatsdClient open source project
+//
+// Copyright (c) 2019 the SwiftStatsdClient project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-statsd-client",
+    products: [
+        .library(name: "StatsdClient", targets: ["StatsdClient"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
+    ],
+    targets: [
+        .target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
+        .testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
+    ]
+)
diff --git a/Package@swift-5.4.swift b/Package@swift-5.4.swift
@@ -0,0 +1,32 @@
+// swift-tools-version:5.0
+
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftStatsdClient open source project
+//
+// Copyright (c) 2019 the SwiftStatsdClient project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-statsd-client",
+    products: [
+        .library(name: "StatsdClient", targets: ["StatsdClient"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
+    ],
+    targets: [
+        .target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
+        .testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
+    ]
+)
diff --git a/Package@swift-5.5.swift b/Package@swift-5.5.swift
@@ -0,0 +1,32 @@
+// swift-tools-version:5.0
+
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftStatsdClient open source project
+//
+// Copyright (c) 2019 the SwiftStatsdClient project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-statsd-client",
+    products: [
+        .library(name: "StatsdClient", targets: ["StatsdClient"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
+    ],
+    targets: [
+        .target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
+        .testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
+    ]
+)
diff --git a/README.md b/README.md
@@ -1,36 +1,36 @@
 # SwiftStatsDClient
 
 a metrics backend for [swift-metrics](https://github.com/apple/swift-metrics) that uses the [statsd](https://github.com/b/statsd_spec) protocol, and can be used to integrate applications with observability solutions that support `statsd` including:
-* [aws](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-custom-metrics-statsd.html)
-* [azure](https://docs.microsoft.com/en-us/azure/azure-monitor/platform/data-platform)
-* [google cloud](https://cloud.google.com/monitoring/agent/plugins/statsd)
-* [ibm cloud](https://cloud.ibm.com/catalog/services/ibm-cloud-monitoring-with-sysdig)
-* [grafana](https://grafana.com)
-* [graphite](https://graphiteapp.org)
-* many others
+* [AWS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-custom-metrics-statsd.html)
+* [Azure](https://docs.microsoft.com/en-us/azure/azure-monitor/platform/data-platform)
+* [Google Cloud](https://cloud.google.com/monitoring/agent/plugins/statsd)
+* [IBM Cloud](https://cloud.ibm.com/catalog/services/ibm-cloud-monitoring-with-sysdig)
+* [Grafana](https://grafana.com)
+* [Graphite](https://graphiteapp.org)
+* Many others
 
 ## Getting started
 
-create an instance of the `StatsdClient` and boostrap the `MetricsSystem` in your application's main:
+Create an instance of the `StatsdClient` and boostrap the `MetricsSystem` in your application's `main`:
 
 ```swift
 let statsdClient = try StatsdClient(host: host, port: port)
 MetricsSystem.bootstrap(statsdClient)
 ```
 
-see https://github.com/apple/swift-metrics#selecting-a-metrics-backend-implementation-applications-only
+See [selecting a metrics backend implementation](https://github.com/apple/swift-metrics#selecting-a-metrics-backend-implementation-applications-only) for more information.
 
-remeber to also shutdown the client before you application terminates:
+Remember to also shutdown the client before you application terminates:
 
 ```swift
 statsdClient.shutdown()
 ```
 
 ## Architecture
 
-the statsd client uses [swift-nio](https://github.com/apple/swift-nio) to establish a UDP connection to the statsd server
+`StatsdClient` uses [SwiftNIO](https://github.com/apple/swift-nio) to establish a UDP connection to the `statsd` server.
 
-metrics types are mapped as follwoing:
+Metrics types are mapped as following:
 * Counter -> Counter
 * Gauge -> Gauge
 * Recorder -> Histogram

diff --git a/Sources/StatsdClient/Docs.docc/index.md b/Sources/StatsdClient/Docs.docc/index.md
@@ -0,0 +1,54 @@
+# ``StatsdClient``
+
+A metrics backend implementation using the StatsD protocol.
+
+## Overview
+
+StatsdClient is a metrics backend for [SwiftMetrics](https://github.com/apple/swift-metrics) that uses the [StatsD](https://github.com/b/statsd_spec) protocol, and can be used to integrate applications with observability solutions that support StatsD including:
+* [AWS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-custom-metrics-statsd.html)
+* [Azure](https://docs.microsoft.com/en-us/azure/azure-monitor/platform/data-platform)
+* [Google Cloud](https://cloud.google.com/monitoring/agent/plugins/statsd)
+* [IBM Cloud](https://cloud.ibm.com/catalog/services/ibm-cloud-monitoring-with-sysdig)
+* [Grafana](https://grafana.com)
+* [Graphite](https://graphiteapp.org)
+* Many others
+
+## Getting started
+
+Create an instance of the ``StatsdClient/StatsdClient`` and boostrap the `MetricsSystem` in your application's `main`:
+
+```swift
+let statsdClient = try StatsdClient(host: host, port: port)
+MetricsSystem.bootstrap(statsdClient)
+```
+
+See [selecting a metrics backend implementation](https://github.com/apple/swift-metrics#selecting-a-metrics-backend-implementation-applications-only) for more information.
+
+Remember to also shutdown the client before you application terminates:
+
+```swift
+statsdClient.shutdown()
+```
+
+## Architecture
+
+``StatsdClient/StatsdClient`` uses [SwiftNIO](https://github.com/apple/swift-nio) to establish a UDP connection to the `statsd` server.
+
+Metrics types are mapped as following:
+* Counter -> Counter
+* Gauge -> Gauge
+* Recorder -> Histogram
+* Timer -> Timer
+
+## Topics
+
+### Client API
+
+- ``StatsdClient/init(eventLoopGroupProvider:host:port:metricNameSanitizer:)``
+- ``StatsdClient/shutdown(_:)``
+
+### Metrics API
+
+- ``StatsdClient/makeCounter(label:dimensions:)``
+- ``StatsdClient/makeRecorder(label:dimensions:aggregate:)``
+- ``StatsdClient/makeTimer(label:dimensions:)``
diff --git a/Sources/StatsdClient/StatsdClient.swift b/Sources/StatsdClient/StatsdClient.swift
@@ -2,7 +2,7 @@
 //
 // This source file is part of the SwiftStatsdClient open source project
 //
-// Copyright (c) 2019 the SwiftStatsdClient project authors
+// Copyright (c) 2019-2022 the SwiftStatsdClient project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -26,12 +26,12 @@ public final class StatsdClient: MetricsFactory {
     private var timers = [String: TimerHandler]() // protected by a lock
     private let lock = Lock()
 
-    /// Create a new instance of `StatsdClient`
+    /// Create a new instance of `StatsdClient`.
     ///
-    /// - parameters:
-    ///     - eventLoopGroupProvider: The `EventLoopGroupProvider` to use, uses`createNew` strategy by default.
-    ///     - host: The `statsd` server host.
-    ///     - port: The `statsd` server port.
+    /// - Parameters:
+    ///   - eventLoopGroupProvider: The ``EventLoopGroupProvider`` to use, uses ``EventLoopGroupProvider/createNew`` strategy by default.
+    ///   - host: The `statsd` server host.
+    ///   - port: The `statsd` server port.
     public init(
         eventLoopGroupProvider: EventLoopGroupProvider = .createNew,
         host: String,
@@ -42,12 +42,12 @@ public final class StatsdClient: MetricsFactory {
         self.client = Client(eventLoopGroupProvider: eventLoopGroupProvider, address: address, metricNameSanitizer: metricNameSanitizer)
     }
 
-    /// Shutdown the client. This is a noop when using a `shared` `EventLoopGroupProvider` strategy.
+    /// Shutdown the client. This is a noop when using the ``EventLoopGroupProvider/shared(_:)`` strategy.
     ///
-    /// - Note: It is required to call `shutdown` before terminating the program. `StatsdClient` client will assert it was cleanly shut down as part of it destructor.
+    /// - Note: It is required to call this method before terminating the program. `StatsdClient` will assert it was cleanly shut down as part of its destructor.
     ///
-    /// - parameters:
-    ///     - callback: A caalback for when shutdown is complete
+    /// - Parameters:
+    ///   - callback: A callback for when shutdown is complete.
     public func shutdown(_ callback: @escaping (Error?) -> Void) {
         self.client.shutdown(callback)
     }

diff --git a/docker/docker-compose.2004.56.yaml b/docker/docker-compose.2004.56.yaml
@@ -11,3 +11,5 @@ services:
 
   test:
     image: swift-statsd-client:20.04-5.6
+    environment:
+      - FORCE_TEST_DISCOVERY=--enable-test-discovery
diff --git a/docker/docker-compose.2004.57.yaml b/docker/docker-compose.2004.57.yaml
@@ -10,3 +10,5 @@ services:
 
   test:
     image: swift-statsd-client:20.04-5.7
+    environment:
+      - FORCE_TEST_DISCOVERY=--enable-test-discovery
diff --git a/docker/docker-compose.2004.main.yaml b/docker/docker-compose.2004.main.yaml
@@ -10,3 +10,5 @@ services:
 
   test:
     image: swift-statsd-client:20.04-main
+    environment:
+      - FORCE_TEST_DISCOVERY=--enable-test-discovery
diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml
@@ -28,4 +28,4 @@ services:
 
   test:
     <<: *common
-    command: /bin/bash -cl "swift test"
+    command: /bin/bash -cl "swift test $${FORCE_TEST_DISCOVERY-}"