+docc prepare for docc publishing (#118)
* +docc prepare for docc publishing * fix test discovery on 5.5 and 5.6 * Delete Package@swift-5.6.swift * Update Package.swift * Apply suggestions from code review Co-authored-by: Yim Lee <yim_lee@apple.com> Co-authored-by: Yim Lee <yim_lee@apple.com>
This commit is contained in:
Konrad `ktoso` Malawski
GitHub
parent
bd1b935c8e
commit
bcea8c19fe
|
|
@ -1,4 +1,4 @@
|
|||
// swift-tools-version:4.2
|
||||
// swift-tools-version:5.6
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Metrics API open source project
|
||||
|
|
@ -22,6 +22,10 @@ let package = Package(
|
|||
.library(name: "Metrics", targets: ["Metrics"]),
|
||||
.library(name: "MetricsTestKit", targets: ["MetricsTestKit"]),
|
||||
],
|
||||
dependencies: [
|
||||
// ~~~ SwiftPM Plugins ~~~
|
||||
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "CoreMetrics",
|
||||
|
|
|
|||
|
|
@ -0,0 +1,43 @@
|
|||
// swift-tools-version:4.2
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Metrics API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Metrics API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Metrics API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-metrics",
|
||||
products: [
|
||||
.library(name: "CoreMetrics", targets: ["CoreMetrics"]),
|
||||
.library(name: "Metrics", targets: ["Metrics"]),
|
||||
.library(name: "MetricsTestKit", targets: ["MetricsTestKit"]),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "CoreMetrics",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "Metrics",
|
||||
dependencies: ["CoreMetrics"]
|
||||
),
|
||||
.target(
|
||||
name: "MetricsTestKit",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "MetricsTests",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
// swift-tools-version:5.0
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Metrics API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Metrics API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Metrics API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-metrics",
|
||||
products: [
|
||||
.library(name: "CoreMetrics", targets: ["CoreMetrics"]),
|
||||
.library(name: "Metrics", targets: ["Metrics"]),
|
||||
.library(name: "MetricsTestKit", targets: ["MetricsTestKit"]),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "CoreMetrics",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "Metrics",
|
||||
dependencies: ["CoreMetrics"]
|
||||
),
|
||||
.target(
|
||||
name: "MetricsTestKit",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "MetricsTests",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
// swift-tools-version:5.1
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Metrics API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Metrics API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Metrics API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-metrics",
|
||||
products: [
|
||||
.library(name: "CoreMetrics", targets: ["CoreMetrics"]),
|
||||
.library(name: "Metrics", targets: ["Metrics"]),
|
||||
.library(name: "MetricsTestKit", targets: ["MetricsTestKit"]),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "CoreMetrics",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "Metrics",
|
||||
dependencies: ["CoreMetrics"]
|
||||
),
|
||||
.target(
|
||||
name: "MetricsTestKit",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "MetricsTests",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
// swift-tools-version:5.2
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Metrics API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Metrics API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Metrics API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-metrics",
|
||||
products: [
|
||||
.library(name: "CoreMetrics", targets: ["CoreMetrics"]),
|
||||
.library(name: "Metrics", targets: ["Metrics"]),
|
||||
.library(name: "MetricsTestKit", targets: ["MetricsTestKit"]),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "CoreMetrics",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "Metrics",
|
||||
dependencies: ["CoreMetrics"]
|
||||
),
|
||||
.target(
|
||||
name: "MetricsTestKit",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "MetricsTests",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
// swift-tools-version:5.3
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Metrics API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Metrics API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Metrics API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-metrics",
|
||||
products: [
|
||||
.library(name: "CoreMetrics", targets: ["CoreMetrics"]),
|
||||
.library(name: "Metrics", targets: ["Metrics"]),
|
||||
.library(name: "MetricsTestKit", targets: ["MetricsTestKit"]),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "CoreMetrics",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "Metrics",
|
||||
dependencies: ["CoreMetrics"]
|
||||
),
|
||||
.target(
|
||||
name: "MetricsTestKit",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "MetricsTests",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
// swift-tools-version:5.4
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Metrics API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Metrics API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Metrics API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-metrics",
|
||||
products: [
|
||||
.library(name: "CoreMetrics", targets: ["CoreMetrics"]),
|
||||
.library(name: "Metrics", targets: ["Metrics"]),
|
||||
.library(name: "MetricsTestKit", targets: ["MetricsTestKit"]),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "CoreMetrics",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "Metrics",
|
||||
dependencies: ["CoreMetrics"]
|
||||
),
|
||||
.target(
|
||||
name: "MetricsTestKit",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "MetricsTests",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
// swift-tools-version:5.5
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Metrics API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Metrics API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Metrics API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-metrics",
|
||||
products: [
|
||||
.library(name: "CoreMetrics", targets: ["CoreMetrics"]),
|
||||
.library(name: "Metrics", targets: ["Metrics"]),
|
||||
.library(name: "MetricsTestKit", targets: ["MetricsTestKit"]),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "CoreMetrics",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "Metrics",
|
||||
dependencies: ["CoreMetrics"]
|
||||
),
|
||||
.target(
|
||||
name: "MetricsTestKit",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "MetricsTests",
|
||||
dependencies: ["Metrics"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
|
@ -0,0 +1,96 @@
|
|||
# ``CoreMetrics``
|
||||
|
||||
A Metrics API package for Swift.
|
||||
|
||||
## Overview
|
||||
|
||||
Almost all production server software needs to emit metrics information for observability. Because it's unlikely that all parties can agree on one specific metrics backend implementation, this API is designed to establish a standard that can be implemented by various metrics libraries which then post the metrics data to backends like [Prometheus](https://prometheus.io/), [Graphite](https://graphiteapp.org), publish over [statsd](https://github.com/statsd/statsd), write to disk, etc.
|
||||
|
||||
This is the beginning of a community-driven open-source project actively seeking contributions, be it code, documentation, or ideas. Apart from contributing to SwiftMetrics itself, we need metrics compatible libraries which send the metrics over to backend such as the ones mentioned above. What SwiftMetrics provides today is covered in the [API docs](https://apple.github.io/swift-metrics/), but it will continue to evolve with community input.
|
||||
|
||||
## Getting started
|
||||
|
||||
If you have a server-side Swift application, or maybe a cross-platform (e.g. Linux, macOS) application or library, and you would like to emit metrics, targeting this metrics API package is a great idea. Below you'll find all you need to know to get started.
|
||||
|
||||
### Adding the dependency
|
||||
|
||||
To add a dependency on the metrics API package, you need to declare it in your `Package.swift`:
|
||||
|
||||
```swift
|
||||
// swift-metrics 1.x and 2.x are almost API compatible, so most clients should use
|
||||
.package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"),
|
||||
```
|
||||
|
||||
and to your application/library target, add "Metrics" to your dependencies:
|
||||
|
||||
```swift
|
||||
.target(
|
||||
name: "BestExampleApp",
|
||||
dependencies: [
|
||||
// ...
|
||||
.product(name: "Metrics", package: "swift-metrics"),
|
||||
]
|
||||
),
|
||||
```
|
||||
|
||||
### Emitting metrics information
|
||||
|
||||
```swift
|
||||
// 1) let's import the metrics API package
|
||||
import Metrics
|
||||
|
||||
// 2) we need to create a concrete metric object, the label works similarly to a `DispatchQueue` label
|
||||
let counter = Counter(label: "com.example.BestExampleApp.numberOfRequests")
|
||||
|
||||
// 3) we're now ready to use it
|
||||
counter.increment()
|
||||
```
|
||||
|
||||
### Selecting a metrics backend implementation (applications only)
|
||||
|
||||
Note: If you are building a library, you don't need to concern yourself with this section. It is the end users of your library (the applications) who will decide which metrics backend to use. Libraries should never change the metrics implementation as that is something owned by the application.
|
||||
|
||||
SwiftMetrics only provides the metrics system API. As an application owner, you need to select a metrics backend (such as the ones mentioned above) to make the metrics information useful.
|
||||
|
||||
Selecting a backend is done by adding a dependency on the desired backend client implementation and invoking the `MetricsSystem.bootstrap` function at the beginning of the program:
|
||||
|
||||
```swift
|
||||
MetricsSystem.bootstrap(SelectedMetricsImplementation())
|
||||
```
|
||||
|
||||
This instructs the `MetricsSystem` to install `SelectedMetricsImplementation` (actual name will differ) as the metrics backend to use.
|
||||
|
||||
> Tip: Refer to the project's [README](https://github.com/apple/swift-metrics) for an up-to-date list of backend implementations.
|
||||
|
||||
### Swift Metrics Extras
|
||||
|
||||
You may also be interested in some "extra" modules which are collected in the [Swift Metrics Extras](https://github.com/apple/swift-metrics-extras) repository.
|
||||
|
||||
## Detailed design
|
||||
|
||||
### Architecture
|
||||
|
||||
We believe that for the Swift on Server ecosystem, it's crucial to have a metrics API that can be adopted by anybody so a multitude of libraries from different parties can all provide metrics information. More concretely this means that we believe all the metrics events from all libraries should end up in the same place, be one of the backends mentioned above or wherever else the application owner may choose.
|
||||
|
||||
In the real world, there are so many opinions over how exactly a metrics system should behave, how metrics should be aggregated and calculated, and where/how to persist them. We think it's not feasible to wait for one metrics package to support everything that a specific deployment needs while still being simple enough to use and remain performant. That's why we decided to split the problem into two:
|
||||
|
||||
1. a metrics API
|
||||
2. a metrics backend implementation
|
||||
|
||||
This package only provides the metrics API itself, and therefore, SwiftMetrics is a "metrics API package." SwiftMetrics can be configured (using `MetricsSystem.bootstrap`) to choose any compatible metrics backend implementation. This way, packages can adopt the API, and the application can choose any compatible metrics backend implementation without requiring any changes from any of the libraries.
|
||||
|
||||
This API was designed with the contributors to the Swift on Server community and approved by the SSWG (Swift Server Work Group) to the "sandbox level" of the SSWG's incubation process.
|
||||
|
||||
[pitch](https://forums.swift.org/t/metrics/19353) |
|
||||
[discussion](https://forums.swift.org/t/discussion-server-metrics-api/) |
|
||||
[feedback](https://forums.swift.org/t/feedback-server-metrics-api/)
|
||||
|
||||
|
||||
## Topics
|
||||
|
||||
### Metric types
|
||||
|
||||
- ``Gauge``
|
||||
- ``Recorder``
|
||||
- ``Counter``
|
||||
- ``Timer``
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
# ``Metrics``
|
||||
|
||||
A Metrics API package for Swift.
|
||||
|
||||
Refer to `CoreMetrics` module documentation for the majority of types.
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
# ``MetricsTestKit``
|
||||
|
||||
A set of tools for testing Metrics emitting libraries.
|
||||
|
||||
## Overview
|
||||
|
||||
This module offers a ``TestMetrics`` type which can be used to bootstrap the metrics system and then assert metric values on it.
|
||||
|
||||
## Example
|
||||
|
||||
```swift
|
||||
import XCTest
|
||||
import Metrics
|
||||
import MetricsTestKit
|
||||
|
||||
final class ExampleTests: XCTestCase {
|
||||
var metrics: TestMetrics! = TestMetrics()
|
||||
|
||||
override func setUp() {
|
||||
MetricsSystem.bootstrapInternal(self.metrics)
|
||||
}
|
||||
|
||||
override func tearDown() async throws {
|
||||
self.metrics = nil
|
||||
MetricsSystem.bootstrapInternal(NOOPMetricsHandler.instance)
|
||||
}
|
||||
|
||||
func test_example() async throws {
|
||||
// Create a metric using the bootstrapped test metrics backend:
|
||||
Gauge(label: "example").record(100)
|
||||
|
||||
// extract the `TestGauge` out of the
|
||||
let gauge = try self.metrics.expectGauge("example")
|
||||
gauge.lastValue?.shouldEqual(6)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Topics
|
||||
|
||||
### Test metrics
|
||||
|
||||
- ``TestRecorder``
|
||||
- ``TestCounter``
|
||||
- ``TestTimer``
|
||||
|
|
@ -11,7 +11,8 @@ services:
|
|||
|
||||
test:
|
||||
image: swift-metrics:20.04-5.5
|
||||
environment: []
|
||||
environment:
|
||||
- FORCE_TEST_DISCOVERY=--enable-test-discovery
|
||||
#- SANITIZER_ARG=--sanitize=thread
|
||||
|
||||
shell:
|
||||
|
|
|
|||
|
|
@ -11,7 +11,8 @@ services:
|
|||
|
||||
test:
|
||||
image: swift-metrics:20.04-5.6
|
||||
environment: []
|
||||
environment:
|
||||
- FORCE_TEST_DISCOVERY=--enable-test-discovery
|
||||
#- SANITIZER_ARG=--sanitize=thread
|
||||
|
||||
shell:
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ services:
|
|||
|
||||
test:
|
||||
<<: *common
|
||||
command: /bin/bash -xcl "swift test -Xswiftc -warnings-as-errors $${SANITIZER_ARG-}"
|
||||
command: /bin/bash -xcl "swift test -Xswiftc -warnings-as-errors $${FORCE_TEST_DISCOVERY-} $${SANITIZER_ARG-}"
|
||||
|
||||
# util
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,16 @@
|
|||
#!/bin/bash
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the Swift Metrics API open source project
|
||||
##
|
||||
## Copyright (c) 2018-2019 Apple Inc. and the Swift Metrics API project authors
|
||||
## Licensed under Apache License v2.0
|
||||
##
|
||||
## See LICENSE.txt for license information
|
||||
## See CONTRIBUTORS.txt for the list of Swift Metrics API project authors
|
||||
##
|
||||
## SPDX-License-Identifier: Apache-2.0
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
|
||||
swift package --disable-sandbox preview-documentation --target "$1"
|
||||
|
|
@ -86,7 +86,7 @@ for language in swift-or-c bash dtrace; do
|
|||
matching_files=( -name '*' )
|
||||
case "$language" in
|
||||
swift-or-c)
|
||||
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)
|
||||
exceptions=( -name Package.swift -o -name "Package@swift-*.swift" )
|
||||
matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' )
|
||||
cat > "$tmp" <<"EOF"
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
|
|
|||
Loading…
Reference in New Issue