Skip to content

Commit c98d70e

Browse files
yim-leeyim-lee
authored
DocC setup (#36)
* DocC setup * Fix build in newer Swift versions * Rename docc directory * Package manifest for old Swift versions rather than new * Add more API to topics * Add preview DocC script
1 parent 51ee3c8 commit c98d70e

16 files changed

+325
-32
lines changed

‎Package.swift

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
// swift-tools-version:5.0
1+
// swift-tools-version:5.6
22

33
//===----------------------------------------------------------------------===//
44
//
55
// This source file is part of the SwiftStatsdClient open source project
66
//
7-
// Copyright (c) 2019 the SwiftStatsdClient project authors
7+
// Copyright (c) 2019-2022 the SwiftStatsdClient project authors
88
// Licensed under Apache License v2.0
99
//
1010
// See LICENSE.txt for license information
@@ -24,9 +24,13 @@ let package = Package(
2424
dependencies: [
2525
.package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
2626
.package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
27+
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
2728
],
2829
targets: [
29-
.target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
30+
.target(name: "StatsdClient", dependencies: [
31+
.product(name: "CoreMetrics", package: "swift-metrics"),
32+
.product(name: "NIO", package: "swift-nio"),
33+
]),
3034
.testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
3135
]
3236
)

‎[email protected]

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// swift-tools-version:5.0
2+
3+
//===----------------------------------------------------------------------===//
4+
//
5+
// This source file is part of the SwiftStatsdClient open source project
6+
//
7+
// Copyright (c) 2019 the SwiftStatsdClient project authors
8+
// Licensed under Apache License v2.0
9+
//
10+
// See LICENSE.txt for license information
11+
// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
12+
//
13+
// SPDX-License-Identifier: Apache-2.0
14+
//
15+
//===----------------------------------------------------------------------===//
16+
17+
import PackageDescription
18+
19+
let package = Package(
20+
name: "swift-statsd-client",
21+
products: [
22+
.library(name: "StatsdClient", targets: ["StatsdClient"]),
23+
],
24+
dependencies: [
25+
.package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
26+
.package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
27+
],
28+
targets: [
29+
.target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
30+
.testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
31+
]
32+
)

‎[email protected]

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// swift-tools-version:5.0
2+
3+
//===----------------------------------------------------------------------===//
4+
//
5+
// This source file is part of the SwiftStatsdClient open source project
6+
//
7+
// Copyright (c) 2019 the SwiftStatsdClient project authors
8+
// Licensed under Apache License v2.0
9+
//
10+
// See LICENSE.txt for license information
11+
// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
12+
//
13+
// SPDX-License-Identifier: Apache-2.0
14+
//
15+
//===----------------------------------------------------------------------===//
16+
17+
import PackageDescription
18+
19+
let package = Package(
20+
name: "swift-statsd-client",
21+
products: [
22+
.library(name: "StatsdClient", targets: ["StatsdClient"]),
23+
],
24+
dependencies: [
25+
.package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
26+
.package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
27+
],
28+
targets: [
29+
.target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
30+
.testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
31+
]
32+
)

‎[email protected]

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// swift-tools-version:5.0
2+
3+
//===----------------------------------------------------------------------===//
4+
//
5+
// This source file is part of the SwiftStatsdClient open source project
6+
//
7+
// Copyright (c) 2019 the SwiftStatsdClient project authors
8+
// Licensed under Apache License v2.0
9+
//
10+
// See LICENSE.txt for license information
11+
// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
12+
//
13+
// SPDX-License-Identifier: Apache-2.0
14+
//
15+
//===----------------------------------------------------------------------===//
16+
17+
import PackageDescription
18+
19+
let package = Package(
20+
name: "swift-statsd-client",
21+
products: [
22+
.library(name: "StatsdClient", targets: ["StatsdClient"]),
23+
],
24+
dependencies: [
25+
.package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
26+
.package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
27+
],
28+
targets: [
29+
.target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
30+
.testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
31+
]
32+
)

‎[email protected]

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// swift-tools-version:5.0
2+
3+
//===----------------------------------------------------------------------===//
4+
//
5+
// This source file is part of the SwiftStatsdClient open source project
6+
//
7+
// Copyright (c) 2019 the SwiftStatsdClient project authors
8+
// Licensed under Apache License v2.0
9+
//
10+
// See LICENSE.txt for license information
11+
// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
12+
//
13+
// SPDX-License-Identifier: Apache-2.0
14+
//
15+
//===----------------------------------------------------------------------===//
16+
17+
import PackageDescription
18+
19+
let package = Package(
20+
name: "swift-statsd-client",
21+
products: [
22+
.library(name: "StatsdClient", targets: ["StatsdClient"]),
23+
],
24+
dependencies: [
25+
.package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
26+
.package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
27+
],
28+
targets: [
29+
.target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
30+
.testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
31+
]
32+
)

‎[email protected]

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// swift-tools-version:5.0
2+
3+
//===----------------------------------------------------------------------===//
4+
//
5+
// This source file is part of the SwiftStatsdClient open source project
6+
//
7+
// Copyright (c) 2019 the SwiftStatsdClient project authors
8+
// Licensed under Apache License v2.0
9+
//
10+
// See LICENSE.txt for license information
11+
// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
12+
//
13+
// SPDX-License-Identifier: Apache-2.0
14+
//
15+
//===----------------------------------------------------------------------===//
16+
17+
import PackageDescription
18+
19+
let package = Package(
20+
name: "swift-statsd-client",
21+
products: [
22+
.library(name: "StatsdClient", targets: ["StatsdClient"]),
23+
],
24+
dependencies: [
25+
.package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
26+
.package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
27+
],
28+
targets: [
29+
.target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
30+
.testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
31+
]
32+
)

‎[email protected]

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// swift-tools-version:5.0
2+
3+
//===----------------------------------------------------------------------===//
4+
//
5+
// This source file is part of the SwiftStatsdClient open source project
6+
//
7+
// Copyright (c) 2019 the SwiftStatsdClient project authors
8+
// Licensed under Apache License v2.0
9+
//
10+
// See LICENSE.txt for license information
11+
// See CONTRIBUTORS.txt for the list of SwiftStatsdClient project authors
12+
//
13+
// SPDX-License-Identifier: Apache-2.0
14+
//
15+
//===----------------------------------------------------------------------===//
16+
17+
import PackageDescription
18+
19+
let package = Package(
20+
name: "swift-statsd-client",
21+
products: [
22+
.library(name: "StatsdClient", targets: ["StatsdClient"]),
23+
],
24+
dependencies: [
25+
.package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
26+
.package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
27+
],
28+
targets: [
29+
.target(name: "StatsdClient", dependencies: ["CoreMetrics", "NIO"]),
30+
.testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
31+
]
32+
)

‎README.md

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,36 @@
11
# SwiftStatsDClient
22

33
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:
4-
* [aws](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-custom-metrics-statsd.html)
5-
* [azure](https://docs.microsoft.com/en-us/azure/azure-monitor/platform/data-platform)
6-
* [google cloud](https://cloud.google.com/monitoring/agent/plugins/statsd)
7-
* [ibm cloud](https://cloud.ibm.com/catalog/services/ibm-cloud-monitoring-with-sysdig)
8-
* [grafana](https://grafana.com)
9-
* [graphite](https://graphiteapp.org)
10-
* many others
4+
* [AWS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-custom-metrics-statsd.html)
5+
* [Azure](https://docs.microsoft.com/en-us/azure/azure-monitor/platform/data-platform)
6+
* [Google Cloud](https://cloud.google.com/monitoring/agent/plugins/statsd)
7+
* [IBM Cloud](https://cloud.ibm.com/catalog/services/ibm-cloud-monitoring-with-sysdig)
8+
* [Grafana](https://grafana.com)
9+
* [Graphite](https://graphiteapp.org)
10+
* Many others
1111

1212
## Getting started
1313

14-
create an instance of the `StatsdClient` and boostrap the `MetricsSystem` in your application's main:
14+
Create an instance of the `StatsdClient` and boostrap the `MetricsSystem` in your application's `main`:
1515

1616
```swift
1717
let statsdClient = try StatsdClient(host: host, port: port)
1818
MetricsSystem.bootstrap(statsdClient)
1919
```
2020

21-
see https://github.com/apple/swift-metrics#selecting-a-metrics-backend-implementation-applications-only
21+
See [selecting a metrics backend implementation](https://github.com/apple/swift-metrics#selecting-a-metrics-backend-implementation-applications-only) for more information.
2222

23-
remeber to also shutdown the client before you application terminates:
23+
Remember to also shutdown the client before you application terminates:
2424

2525
```swift
2626
statsdClient.shutdown()
2727
```
2828

2929
## Architecture
3030

31-
the statsd client uses [swift-nio](https://github.com/apple/swift-nio) to establish a UDP connection to the statsd server
31+
`StatsdClient` uses [SwiftNIO](https://github.com/apple/swift-nio) to establish a UDP connection to the `statsd` server.
3232

33-
metrics types are mapped as follwoing:
33+
Metrics types are mapped as following:
3434
* Counter -> Counter
3535
* Gauge -> Gauge
3636
* Recorder -> Histogram

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

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# ``StatsdClient``
2+
3+
A metrics backend implementation using the StatsD protocol.
4+
5+
## Overview
6+
7+
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:
8+
* [AWS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-custom-metrics-statsd.html)
9+
* [Azure](https://docs.microsoft.com/en-us/azure/azure-monitor/platform/data-platform)
10+
* [Google Cloud](https://cloud.google.com/monitoring/agent/plugins/statsd)
11+
* [IBM Cloud](https://cloud.ibm.com/catalog/services/ibm-cloud-monitoring-with-sysdig)
12+
* [Grafana](https://grafana.com)
13+
* [Graphite](https://graphiteapp.org)
14+
* Many others
15+
16+
## Getting started
17+
18+
Create an instance of the ``StatsdClient/StatsdClient`` and boostrap the `MetricsSystem` in your application's `main`:
19+
20+
```swift
21+
let statsdClient = try StatsdClient(host: host, port: port)
22+
MetricsSystem.bootstrap(statsdClient)
23+
```
24+
25+
See [selecting a metrics backend implementation](https://github.com/apple/swift-metrics#selecting-a-metrics-backend-implementation-applications-only) for more information.
26+
27+
Remember to also shutdown the client before you application terminates:
28+
29+
```swift
30+
statsdClient.shutdown()
31+
```
32+
33+
## Architecture
34+
35+
``StatsdClient/StatsdClient`` uses [SwiftNIO](https://github.com/apple/swift-nio) to establish a UDP connection to the `statsd` server.
36+
37+
Metrics types are mapped as following:
38+
* Counter -> Counter
39+
* Gauge -> Gauge
40+
* Recorder -> Histogram
41+
* Timer -> Timer
42+
43+
## Topics
44+
45+
### Client API
46+
47+
- ``StatsdClient/init(eventLoopGroupProvider:host:port:metricNameSanitizer:)``
48+
- ``StatsdClient/shutdown(_:)``
49+
50+
### Metrics API
51+
52+
- ``StatsdClient/makeCounter(label:dimensions:)``
53+
- ``StatsdClient/makeRecorder(label:dimensions:aggregate:)``
54+
- ``StatsdClient/makeTimer(label:dimensions:)``

‎Sources/StatsdClient/StatsdClient.swift

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
//
33
// This source file is part of the SwiftStatsdClient open source project
44
//
5-
// Copyright (c) 2019 the SwiftStatsdClient project authors
5+
// Copyright (c) 2019-2022 the SwiftStatsdClient project authors
66
// Licensed under Apache License v2.0
77
//
88
// See LICENSE.txt for license information
@@ -26,12 +26,12 @@ public final class StatsdClient: MetricsFactory {
2626
private var timers = [String: TimerHandler]() // protected by a lock
2727
private let lock = Lock()
2828

29-
/// Create a new instance of `StatsdClient`
29+
/// Create a new instance of `StatsdClient`.
3030
///
31-
/// - parameters:
32-
/// - eventLoopGroupProvider: The `EventLoopGroupProvider` to use, uses`createNew` strategy by default.
33-
/// - host: The `statsd` server host.
34-
/// - port: The `statsd` server port.
31+
/// - Parameters:
32+
/// - eventLoopGroupProvider: The ``EventLoopGroupProvider`` to use, uses ``EventLoopGroupProvider/createNew`` strategy by default.
33+
/// - host: The `statsd` server host.
34+
/// - port: The `statsd` server port.
3535
public init(
3636
eventLoopGroupProvider: EventLoopGroupProvider = .createNew,
3737
host: String,
@@ -42,12 +42,12 @@ public final class StatsdClient: MetricsFactory {
4242
self.client = Client(eventLoopGroupProvider: eventLoopGroupProvider, address: address, metricNameSanitizer: metricNameSanitizer)
4343
}
4444

45-
/// Shutdown the client. This is a noop when using a `shared` `EventLoopGroupProvider` strategy.
45+
/// Shutdown the client. This is a noop when using the ``EventLoopGroupProvider/shared(_:)`` strategy.
4646
///
47-
/// - 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.
47+
/// - 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.
4848
///
49-
/// - parameters:
50-
/// - callback: A caalback for when shutdown is complete
49+
/// - Parameters:
50+
/// - callback: A callback for when shutdown is complete.
5151
public func shutdown(_ callback: @escaping (Error?) -> Void) {
5252
self.client.shutdown(callback)
5353
}

0 commit comments

Comments
 (0)