Skip to content

Commit 9f7bb34

Browse files
yim-leeyim-lee
committed
DocC setup
1 parent 84414ef commit 9f7bb34

File tree

5 files changed

+119
-28
lines changed

5 files changed

+119
-28
lines changed

‎[email protected]‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// swift-tools-version:5.6
2+
3+
//===----------------------------------------------------------------------===//
4+
//
5+
// This source file is part of the SwiftStatsdClient open source project
6+
//
7+
// Copyright (c) 2022 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+
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
28+
],
29+
targets: [
30+
.target(name: "StatsdClient", dependencies: [
31+
.product(name: "CoreMetrics", package: "swift-metrics"),
32+
.product(name: "NIO", package: "swift-nio"),
33+
]),
34+
.testTarget(name: "StatsdClientTests", dependencies: ["StatsdClient"]),
35+
]
36+
)

‎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/Documentation.docc/index.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
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+
### Metrics API
46+
47+
- ``StatsdClient/makeCounter(label:dimensions:)``
48+
- ``StatsdClient/makeRecorder(label:dimensions:aggregate:)``
49+
- ``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
}

‎scripts/soundness.sh‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
##
44
## This source file is part of the SwiftStatsdClient open source project
55
##
6-
## Copyright (c) 2019 the SwiftStatsdClient project authors
6+
## Copyright (c) 2019-2022 the SwiftStatsdClient project authors
77
## Licensed under Apache License v2.0
88
##
99
## See LICENSE.txt for license information
@@ -14,8 +14,14 @@
1414
##===----------------------------------------------------------------------===##
1515

1616
set -eu
17+
1718
here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
1819

20+
function replace_acceptable_years() {
21+
# this needs to replace all acceptable forms with 'YEARS'
22+
sed -e 's/20[12][901]-202[012]/YEARS/' -e 's/2019/YEARS/' -e 's/202[012]/YEARS/'
23+
}
24+
1925
printf "=> Checking for unacceptable language... "
2026
# This greps for unacceptable terminology. The square bracket[s] are so that
2127
# "git grep" doesn't find the lines that greps :).
@@ -67,14 +73,14 @@ for language in swift-or-c bash dtrace; do
6773
matching_files=( -name '*' )
6874
case "$language" in
6975
swift-or-c)
70-
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)
76+
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 [email protected] -o -name CNIOSHA1.h -o -name c_nio_sha1.c -o -name ifaddrs-android.c -o -name ifaddrs-android.h)
7177
matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' )
7278
cat > "$tmp" <<"EOF"
7379
//===----------------------------------------------------------------------===//
7480
//
7581
// This source file is part of the SwiftStatsdClient open source project
7682
//
77-
// Copyright (c) 2019 the SwiftStatsdClient project authors
83+
// Copyright (c) YEARS the SwiftStatsdClient project authors
7884
// Licensed under Apache License v2.0
7985
//
8086
// See LICENSE.txt for license information
@@ -93,7 +99,7 @@ EOF
9399
##
94100
## This source file is part of the SwiftStatsdClient open source project
95101
##
96-
## Copyright (c) 2019 the SwiftStatsdClient project authors
102+
## Copyright (c) YEARS the SwiftStatsdClient project authors
97103
## Licensed under Apache License v2.0
98104
##
99105
## See LICENSE.txt for license information
@@ -112,7 +118,7 @@ EOF
112118
*
113119
* This source file is part of the SwiftStatsdClient open source project
114120
*
115-
* Copyright (c) 2019 the SwiftStatsdClient project authors
121+
* Copyright (c) YEARS the SwiftStatsdClient project authors
116122
* Licensed under Apache License v2.0
117123
*
118124
* See LICENSE.txt for license information
@@ -137,7 +143,7 @@ EOF
137143
\( \! -path './.build/*' -a \
138144
\( "${matching_files[@]}" \) -a \
139145
\( \! \( "${exceptions[@]}" \) \) \) | while read line; do
140-
if [[ "$(cat "$line" | head -n $expected_lines | shasum)" != "$expected_sha" ]]; then
146+
if [[ "$(cat "$line" | replace_acceptable_years | head -n $expected_lines | shasum)" != "$expected_sha" ]]; then
141147
printf "\033[0;31mmissing headers in file '$line'!\033[0m\n"
142148
diff -u <(cat "$line" | head -n $expected_lines) "$tmp"
143149
exit 1

0 commit comments

Comments
 (0)