commit c56f6c20cde6c15a634a09da6d456df3c828bf8e Author: Konrad `ktoso` Malawski Date: Thu Nov 12 18:28:09 2020 +0900 Initial commit, project structure diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..0c1dcb1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,20 @@ +### Expected behavior +_[what you expected to happen]_ + +### Actual behavior +_[what actually happened]_ + +### Steps to reproduce + +1. ... +2. ... + +### If possible, minimal yet complete reproducer code (or URL to code) + +_[anything to help us reproducing the issue]_ + +### SwiftMetrics version/commit hash + +_[the SwiftMetrics tag/commit hash]_ + +### Swift & OS version (output of `swift --version && uname -a`) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..ab90c7b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,13 @@ +_[One line description of your change]_ + +### Motivation: + +_[Explain here the context, and why you're making that change. What is the problem you're trying to solve.]_ + +### Modifications: + +_[Describe the modifications you've done.]_ + +### Result: + +_[After your change, what will change.]_ diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2b01b4f --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +.DS_Store +/.build +/Packages +/*.xcodeproj +.xcode +.SourceKitten +*.orig +.swiftpm +.idea diff --git a/.mailmap b/.mailmap new file mode 100644 index 0000000..660d914 --- /dev/null +++ b/.mailmap @@ -0,0 +1,2 @@ +Tomer Doron +Konrad `ktoso` Malawski diff --git a/.swiftformat b/.swiftformat new file mode 100644 index 0000000..ffccb20 --- /dev/null +++ b/.swiftformat @@ -0,0 +1,13 @@ +# file options + +--swiftversion 5.0 +--exclude .build + +# format options + +--self insert +--patternlet inline +--stripunusedargs unnamed-only +--ifdef no-indent + +# rules diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..b98ccc7 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,55 @@ +# Code of Conduct +To be a truly great community, SwiftMetrics needs to welcome developers from all walks of life, +with different backgrounds, and with a wide range of experience. A diverse and friendly +community will have more great ideas, more unique perspectives, and produce more great +code. We will work diligently to make the SwiftMetrics community welcoming to everyone. + +To give clarity of what is expected of our members, SwiftMetrics has adopted the code of conduct +defined by [contributor-covenant.org](https://www.contributor-covenant.org). This document is used across many open source +communities, and we think it articulates our values well. The full text is copied below: + +### Contributor Code of Conduct v1.3 +As contributors and maintainers of this project, and in the interest of fostering an open and +welcoming community, we pledge to respect all people who contribute through reporting +issues, posting feature requests, updating documentation, submitting pull requests or patches, +and other activities. + +We are committed to making participation in this project a harassment-free experience for +everyone, regardless of level of experience, gender, gender identity and expression, sexual +orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or +nationality. + +Examples of unacceptable behavior by participants include: +- The use of sexualized language or imagery +- Personal attacks +- Trolling or insulting/derogatory comments +- Public or private harassment +- Publishing other’s private information, such as physical or electronic addresses, without explicit permission +- Other unethical or unprofessional conduct + +Project maintainers have the right and responsibility to remove, edit, or reject comments, +commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of +Conduct, or to ban temporarily or permanently any contributor for other behaviors that they +deem inappropriate, threatening, offensive, or harmful. + +By adopting this Code of Conduct, project maintainers commit themselves to fairly and +consistently applying these principles to every aspect of managing this project. Project +maintainers who do not follow or enforce the Code of Conduct may be permanently removed +from the project team. + +This code of conduct applies both within project spaces and in public spaces when an +individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by +contacting a project maintainer at [swift-server-conduct@group.apple.com](mailto:swift-server-conduct@group.apple.com). All complaints will be reviewed and +investigated and will result in a response that is deemed necessary and appropriate to the +circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter +of an incident. + +*This policy is adapted from the Contributor Code of Conduct [version 1.3.0](https://contributor-covenant.org/version/1/3/0/).* + +### Reporting +A working group of community members is committed to promptly addressing any [reported issues](mailto:swift-server-conduct@group.apple.com). +Working group members are volunteers appointed by the project lead, with a +preference for individuals with varied backgrounds and perspectives. Membership is expected +to change regularly, and may grow or shrink. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fa0b621 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,96 @@ +## Legal + +By submitting a pull request, you represent that you have the right to license +your contribution to Apple and the community, and agree by submitting the patch +that your contributions are licensed under the Apache 2.0 license (see +`LICENSE.txt`). + +## How to submit a bug report + +Please ensure to specify the following: + +* SwiftMetrics commit hash +* Contextual information (e.g. what you were trying to achieve with SwiftMetrics) +* Simplest possible steps to reproduce + * More complex the steps are, lower the priority will be. + * A pull request with failing test case is preferred, but it's just fine to paste the test case into the issue description. +* Anything that might be relevant in your opinion, such as: + * Swift version or the output of `swift --version` + * OS version and the output of `uname -a` + * Network configuration + +### Example + +``` +SwiftMetrics commit hash: b17a8a9f0f814c01a56977680cb68d8a779c951f + +Context: +While testing my application that uses with SwiftMetrics, I noticed that ... + +Steps to reproduce: +1. ... +2. ... +3. ... +4. ... + +$ swift --version +Swift version 4.0.2 (swift-4.0.2-RELEASE) +Target: x86_64-unknown-linux-gnu + +Operating system: Ubuntu Linux 16.04 64-bit + +$ uname -a +Linux beefy.machine 4.4.0-101-generic #124-Ubuntu SMP Fri Nov 10 18:29:59 UTC 2017 x86_64 x86_64 x86_64 GNU/Linux + +My system has IPv6 disabled. +``` + +## Writing a Patch + +A good SwiftMetrics patch is: + +1. Concise, and contains as few changes as needed to achieve the end result. +2. Tested, ensuring that any tests provided failed before the patch and pass after it. +3. Documented, adding API documentation as needed to cover new functions and properties. +4. Accompanied by a great commit message, using our commit message template. + +### Commit Message Template + +We require that your commit messages match our template. The easiest way to do that is to get git to help you by explicitly using the template. To do that, `cd` to the root of our repository and run: + + git config commit.template dev/git.commit.template + +### Make sure Tests work on Linux + +SwiftMetrics uses XCTest to run tests on both macOS and Linux. While the macOS version of XCTest is able to use the Objective-C runtime to discover tests at execution time, the Linux version is not. +For this reason, whenever you add new tests **you have to run a script** that generates the hooks needed to run those tests on Linux, or our CI will complain that the tests are not all present on Linux. To do this, merely execute `ruby ./scripts/generate_linux_tests.rb` at the root of the package and check the changes it made. + +### Run `./scripts/sanity.sh` + +The scripts directory contains a [sanity.sh script](https://github.com/apple/swift-metrics/blob/main/scripts/sanity.sh) +that enforces additional checks, like license headers and formatting style. + +Please make sure to `./scripts/sanity.sh` before pushing a change upstream, otherwise it is likely the PR validation will fail +on minor changes such as a missing `self.` or similar formatting issues. + +> The script also executes the above mentioned `generate_linux_tests.rb`. + +For frequent contributors, we recommend adding the script as a [git pre-push hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks), which you can do via executing the following command in the project root directory: + +```bash +cat << EOF > .git/hooks/pre-push +#!/bin/bash + +if [[ -f "scripts/sanity.sh" ]]; then + scripts/sanity.sh +fi +EOF +``` + +Which makes the script execute, and only allow the `git push` to complete if the check has passed. + +In the case of formatting issues, you can then `git add` the formatting changes, and attempt the push again. + +## How to contribute your work + +Please open a pull request at https://github.com/apple/swift-metrics. Make sure the CI passes, and then wait for code review. diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt new file mode 100644 index 0000000..4a6af0d --- /dev/null +++ b/CONTRIBUTORS.txt @@ -0,0 +1,21 @@ +For the purpose of tracking copyright, this is the list of individuals and +organizations who have contributed source code to the Swift Metrics API. + +For employees of an organization/company where the copyright of work done +by employees of that company is held by the company itself, only the company +needs to be listed here. + +## COPYRIGHT HOLDERS + +- Apple Inc. (all contributors with '@apple.com') + +### Contributors + +- Cory Benfield +- Jari (LotU) +- Konrad `ktoso` Malawski +- tomer doron + +**Updating this list** + +Please do not edit this file manually. It is generated using `./scripts/generate_contributors_list.sh`. If a name is misspelled or appearing multiple times: add an entry in `./.mailmap` diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/NOTICE.txt b/NOTICE.txt new file mode 100644 index 0000000..27044bd --- /dev/null +++ b/NOTICE.txt @@ -0,0 +1,43 @@ + + The SwiftMetrics Project + ======================== + +Please visit the SwiftMetrics web site for more information: + + * https://github.com/apple/swift-metrics + +Copyright 2018, 2019 The SwiftMetrics Project + +The SwiftMetrics Project licenses this file to you under the Apache License, +version 2.0 (the "License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at: + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +License for the specific language governing permissions and limitations +under the License. + +Also, please refer to each LICENSE..txt file, which is located in +the 'license' directory of the distribution file, for the license terms of the +components that this product depends on. + +------------------------------------------------------------------------------- + +This product contains a derivation of the Tony Stone's 'process_test_files.rb'. + + * LICENSE (Apache License 2.0): + * https://www.apache.org/licenses/LICENSE-2.0 + * HOMEPAGE: + * https://codegists.com/snippet/ruby/generate_xctest_linux_runnerrb_tonystone_ruby + +--- + +This product contains a derivation of the lock implementation and various scripts from SwiftNIO. + + * LICENSE (Apache License 2.0): + * https://www.apache.org/licenses/LICENSE-2.0 + * HOMEPAGE: + * https://github.com/apple/swift-nio diff --git a/Package.swift b/Package.swift new file mode 100644 index 0000000..0d9dca7 --- /dev/null +++ b/Package.swift @@ -0,0 +1,33 @@ +// 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: "SystemMetrics", targets: ["SystemMetrics"]), + ], + targets: [ + .target( + name: "SystemMetrics", + dependencies: [] + ), + .testTarget( + name: "SystemMetricsTests", + dependencies: ["SystemMetrics"] + ), + ] +) diff --git a/README.md b/README.md new file mode 100644 index 0000000..ca6258a --- /dev/null +++ b/README.md @@ -0,0 +1,288 @@ +# SwiftMetrics + +A Metrics API package for Swift. + +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: ["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. + +As the API has just launched, not many implementations exist yet. If you are interested in implementing one see the "Implementing a metrics backend" section below explaining how to do so. List of existing SwiftMetrics API compatible libraries: + +- [SwiftPrometheus](https://github.com/MrLotU/SwiftPrometheus), support for [Prometheus](https://prometheus.io) +- [StatsD Client](https://github.com/apple/swift-statsd-client), support for StatsD +- Your library? [Get in touch!](https://forums.swift.org/c/server) + +## 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/) + +### Metric types + +The API supports four metric types: + +`Counter`: A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart. For example, you can use a counter to represent the number of requests served, tasks completed, or errors. + +```swift +counter.increment(by: 100) +``` + +`Recorder`: A recorder collects observations within a time window (usually things like response sizes) and *can* provide aggregated information about the data sample, for example count, sum, min, max and various quantiles. + +```swift +recorder.record(100) +``` + +`Gauge`: A Gauge is a metric that represents a single numerical value that can arbitrarily go up and down. Gauges are typically used for measured values like temperatures or current memory usage, but also "counts" that can go up and down, like the number of active threads. Gauges are modeled as a `Recorder` with a sample size of 1 that does not perform any aggregation. + +```swift +gauge.record(100) +``` + +`Timer`: A timer collects observations within a time window (usually things like request duration) and provides aggregated information about the data sample, for example min, max and various quantiles. It is similar to a `Recorder` but specialized for values that represent durations. + +```swift +timer.recordMilliseconds(100) +``` + +### Implementing a metrics backend (e.g. Prometheus client library) + +Note: Unless you need to implement a custom metrics backend, everything in this section is likely not relevant, so please feel free to skip. + +As seen above, each constructor for `Counter`, `Timer`, `Recorder` and `Gauge` provides a metric object. This uncertainty obscures the selected metrics backend calling these constructors by design. _Each application_ can select and configure its desired backend. The application sets up the metrics backend it wishes to use. Configuring the metrics backend is straightforward: + +```swift +let metricsImplementation = MyFavoriteMetricsImplementation() +MetricsSystem.bootstrap(metricsImplementation) +``` + +This instructs the `MetricsSystem` to install `MyFavoriteMetricsImplementation` as the metrics backend (`MetricsFactory`) to use. This should only be done once at the beginning of the program. + +Given the above, an implementation of a metric backend needs to conform to `protocol MetricsFactory`: + +```swift +public protocol MetricsFactory { + func makeCounter(label: String, dimensions: [(String, String)]) -> CounterHandler + func makeRecorder(label: String, dimensions: [(String, String)], aggregate: Bool) -> RecorderHandler + func makeTimer(label: String, dimensions: [(String, String)]) -> TimerHandler + + func destroyCounter(_ handler: CounterHandler) + func destroyRecorder(_ handler: RecorderHandler) + func destroyTimer(_ handler: TimerHandler) +} +``` + +The `MetricsFactory` is responsible for instantiating the concrete metrics classes that capture the metrics and perform aggregation and calculation of various quantiles as needed. + +**Counter** + +```swift +public protocol CounterHandler: AnyObject { + func increment(by: Int64) + func reset() +} +``` + +**Timer** + +```swift +public protocol TimerHandler: AnyObject { + func recordNanoseconds(_ duration: Int64) +} +``` + +**Recorder** + +```swift +public protocol RecorderHandler: AnyObject { + func record(_ value: Int64) + func record(_ value: Double) +} +``` + +#### Dealing with Overflows + +Implementaton of metric objects that deal with integers, like `Counter` and `Timer` should be careful with overflow. The expected behavior is to cap at `.max`, and never crash the program due to overflow . For example: + +```swift +class ExampleCounter: CounterHandler { + var value: Int64 = 0 + func increment(by amount: Int64) { + let result = self.value.addingReportingOverflow(amount) + if result.overflow { + self.value = Int64.max + } else { + self.value = result.partialValue + } + } +} +``` + +#### Full example + +Here is a full, but contrived, example of an in-memory implementation: + +```swift +class SimpleMetricsLibrary: MetricsFactory { + init() {} + + func makeCounter(label: String, dimensions: [(String, String)]) -> CounterHandler { + return ExampleCounter(label, dimensions) + } + + func makeRecorder(label: String, dimensions: [(String, String)], aggregate: Bool) -> RecorderHandler { + let maker: (String, [(String, String)]) -> RecorderHandler = aggregate ? ExampleRecorder.init : ExampleGauge.init + return maker(label, dimensions) + } + + func makeTimer(label: String, dimensions: [(String, String)]) -> TimerHandler { + return ExampleTimer(label, dimensions) + } + + // implementation is stateless, so nothing to do on destroy calls + func destroyCounter(_ handler: CounterHandler) {} + func destroyRecorder(_ handler: RecorderHandler) {} + func destroyTimer(_ handler: TimerHandler) {} + + private class ExampleCounter: CounterHandler { + init(_: String, _: [(String, String)]) {} + + let lock = NSLock() + var value: Int64 = 0 + func increment(by amount: Int64) { + self.lock.withLock { + self.value += amount + } + } + + func reset() { + self.lock.withLock { + self.value = 0 + } + } + } + + private class ExampleRecorder: RecorderHandler { + init(_: String, _: [(String, String)]) {} + + private let lock = NSLock() + var values = [(Int64, Double)]() + func record(_ value: Int64) { + self.record(Double(value)) + } + + func record(_ value: Double) { + // TODO: sliding window + lock.withLock { + values.append((Date().nanoSince1970, value)) + self._count += 1 + self._sum += value + self._min = Swift.min(self._min, value) + self._max = Swift.max(self._max, value) + } + } + + var _sum: Double = 0 + var sum: Double { + return self.lock.withLock { _sum } + } + + private var _count: Int = 0 + var count: Int { + return self.lock.withLock { _count } + } + + private var _min: Double = 0 + var min: Double { + return self.lock.withLock { _min } + } + + private var _max: Double = 0 + var max: Double { + return self.lock.withLock { _max } + } + } + + private class ExampleGauge: RecorderHandler { + init(_: String, _: [(String, String)]) {} + + let lock = NSLock() + var _value: Double = 0 + func record(_ value: Int64) { + self.record(Double(value)) + } + + func record(_ value: Double) { + self.lock.withLock { _value = value } + } + } + + private class ExampleTimer: ExampleRecorder, TimerHandler { + func recordNanoseconds(_ duration: Int64) { + super.record(duration) + } + } +} +``` + +Do not hesitate to get in touch as well, over on https://forums.swift.org/c/server diff --git a/Tests/LinuxMain.swift b/Tests/LinuxMain.swift new file mode 100644 index 0000000..f01997b --- /dev/null +++ b/Tests/LinuxMain.swift @@ -0,0 +1,30 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// +// +// LinuxMain.swift +// +import XCTest + +/// +/// NOTE: This file was generated by generate_linux_tests.rb +/// +/// Do NOT edit this file directly as it will be regenerated automatically when needed. +/// + +#if os(Linux) || os(FreeBSD) +@testable import MetricsTests + +XCTMain([ +]) +#endif diff --git a/dev/git.commit.template b/dev/git.commit.template new file mode 100644 index 0000000..c52bfa1 --- /dev/null +++ b/dev/git.commit.template @@ -0,0 +1,14 @@ +One line description of your change + +Motivation: + +Explain here the context, and why you're making that change. +What is the problem you're trying to solve. + +Modifications: + +Describe the modifications you've done. + +Result: + +After your change, what will change. diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 0000000..3f2a2e7 --- /dev/null +++ b/docker/Dockerfile @@ -0,0 +1,32 @@ +ARG swift_version=5.0 +ARG ubuntu_version=bionic +ARG base_image=swift:$swift_version-$ubuntu_version +FROM $base_image +# needed to do again after FROM due to docker limitation +ARG swift_version +ARG ubuntu_version + +# set as UTF-8 +RUN apt-get update && apt-get install -y locales locales-all +ENV LC_ALL en_US.UTF-8 +ENV LANG en_US.UTF-8 +ENV LANGUAGE en_US.UTF-8 + +# dependencies +RUN apt-get update && apt-get install -y wget +RUN apt-get update && apt-get install -y lsof dnsutils netcat-openbsd net-tools curl jq # used by integration tests + +# ruby and jazzy for docs generation +RUN apt-get update && apt-get install -y ruby ruby-dev libsqlite3-dev +RUN gem install jazzy --no-ri --no-rdoc + +# tools +RUN mkdir -p $HOME/.tools +RUN echo 'export PATH="$HOME/.tools:$PATH"' >> $HOME/.profile + +# swiftformat (until part of the toolchain) + +ARG swiftformat_version=0.44.6 +RUN git clone --branch $swiftformat_version --depth 1 https://github.com/nicklockwood/SwiftFormat $HOME/.tools/swift-format +RUN cd $HOME/.tools/swift-format && swift build -c release +RUN ln -s $HOME/.tools/swift-format/.build/release/swiftformat $HOME/.tools/swiftformat diff --git a/docker/docker-compose.1804.50.yaml b/docker/docker-compose.1804.50.yaml new file mode 100644 index 0000000..25062b1 --- /dev/null +++ b/docker/docker-compose.1804.50.yaml @@ -0,0 +1,16 @@ +version: "3" + +services: + + runtime-setup: + image: swift-metrics:18.04-5.0 + build: + args: + ubuntu_version: "bionic" + swift_version: "5.0" + + test: + image: swift-metrics:18.04-5.0 + + shell: + image: swift-metrics:18.04-5.0 diff --git a/docker/docker-compose.1804.51.yaml b/docker/docker-compose.1804.51.yaml new file mode 100644 index 0000000..c10b821 --- /dev/null +++ b/docker/docker-compose.1804.51.yaml @@ -0,0 +1,18 @@ +version: "3" + +services: + + runtime-setup: + image: swift-metrics:18.04-5.1 + build: + args: + ubuntu_version: "bionic" + swift_version: "5.1" + + test: + image: swift-metrics:18.04-5.1 + environment: [] + #- SANITIZER_ARG=--sanitize=thread + + shell: + image: swift-metrics:18.04-5.1 diff --git a/docker/docker-compose.1804.52.yaml b/docker/docker-compose.1804.52.yaml new file mode 100644 index 0000000..ee6f33c --- /dev/null +++ b/docker/docker-compose.1804.52.yaml @@ -0,0 +1,18 @@ +version: "3" + +services: + + runtime-setup: + image: swift-metrics:18.04-5.2 + build: + args: + ubuntu_version: "bionic" + swift_version: "5.2" + + test: + image: swift-metrics:18.04-5.2 + environment: [] + #- SANITIZER_ARG=--sanitize=thread + + shell: + image: swift-metrics:18.04-5.2 diff --git a/docker/docker-compose.1804.53.yaml b/docker/docker-compose.1804.53.yaml new file mode 100644 index 0000000..484b1e7 --- /dev/null +++ b/docker/docker-compose.1804.53.yaml @@ -0,0 +1,18 @@ +version: "3" + +services: + + runtime-setup: + image: swift-metrics:18.04-5.3 + build: + args: + ubuntu_version: "bionic" + swift_version: "5.3" + + test: + image: swift-metrics:18.04-5.3 + environment: [] + #- SANITIZER_ARG=--sanitize=thread + + shell: + image: swift-metrics:18.04-5.3 diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml new file mode 100644 index 0000000..38c4d41 --- /dev/null +++ b/docker/docker-compose.yaml @@ -0,0 +1,43 @@ +# this file is not designed to be run directly +# instead, use the docker-compose.. files +# eg docker-compose -f docker/docker-compose.yaml -f docker/docker-compose.1804.50.yaml run test +version: "3" + +services: + + runtime-setup: + image: swift-metrics:default + build: + context: . + dockerfile: Dockerfile + + common: &common + image: swift-metrics:default + depends_on: [runtime-setup] + volumes: + - ~/.ssh:/root/.ssh + - ..:/code:z + working_dir: /code + cap_drop: + - CAP_NET_RAW + - CAP_NET_BIND_SERVICE + + sanity: + <<: *common + command: /bin/bash -xcl "./scripts/sanity.sh" + + docs: + <<: *common + environment: + - CI + command: /bin/bash -xcl "./scripts/generate_docs.sh" + + test: + <<: *common + command: /bin/bash -xcl "swift test -Xswiftc -warnings-as-errors $${SANITIZER_ARG-}" + + # util + + shell: + <<: *common + entrypoint: /bin/bash diff --git a/scripts/build_podspec.sh b/scripts/build_podspec.sh new file mode 100755 index 0000000..6ccb6e2 --- /dev/null +++ b/scripts/build_podspec.sh @@ -0,0 +1,94 @@ +#!/bin/bash +##===----------------------------------------------------------------------===## +## +## This source file is part of the Swift Metrics API open source project +## +## Copyright (c) 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 +## +##===----------------------------------------------------------------------===## + +##===----------------------------------------------------------------------===## +## +## This source file is part of the SwiftNIO open source project +## +## Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors +## Licensed under Apache License v2.0 +## +## See LICENSE.txt for license information +## See CONTRIBUTORS.txt for the list of SwiftNIO project authors +## +## SPDX-License-Identifier: Apache-2.0 +## +##===----------------------------------------------------------------------===## + +set -eu + +function usage() { + echo "$0 [-u] version" + echo + echo "OPTIONS:" + echo " -u: Additionally upload the podspec" +} + +upload=false +while getopts ":u" opt; do + case $opt in + u) + upload=true + ;; + \?) + usage + exit 1 + ;; + esac +done +shift "$((OPTIND-1))" + +if [[ $# -eq 0 ]]; then + echo "Must provide target version" + exit 1 +fi + +version=$1 +name="SwiftMetrics" + +here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" +tmpdir=$(mktemp -d /tmp/.build_podspecsXXXXXX) +echo "Building podspec in $tmpdir" + + cat >> "${tmpdir}/${name}.podspec" <<- EOF +Pod::Spec.new do |s| + s.name = '$name' + s.version = '$version' + s.license = { :type => 'Apache 2.0', :file => 'LICENSE.txt' } + s.summary = 'A Metrics API for Swift.' + s.homepage = 'https://github.com/apple/swift-metrics' + s.author = 'Apple Inc.' + s.source = { :git => 'https://github.com/apple/swift-metrics.git', :tag => s.version.to_s } + s.documentation_url = 'https://apple.github.io/swift-metrics' + s.module_name = '$name' + + s.swift_version = '4.2' + s.cocoapods_version = '>=1.6.0' + s.ios.deployment_target = '8.0' + s.osx.deployment_target = '10.9' + s.tvos.deployment_target = '9.0' + s.watchos.deployment_target = '2.0' + + s.source_files = 'Sources/CoreMetrics/**/*.swift' +end +EOF + +if $upload; then + echo "Uploading ${tmpdir}/${name}.podspec" + pod trunk push "${tmpdir}/${name}.podspec" +else + echo "Linting ${tmpdir}/${name}.podspec" + pod spec lint "${tmpdir}/${name}.podspec" +fi diff --git a/scripts/check_no_api_breakages.sh b/scripts/check_no_api_breakages.sh new file mode 100755 index 0000000..9aa989c --- /dev/null +++ b/scripts/check_no_api_breakages.sh @@ -0,0 +1,136 @@ +#!/bin/bash +##===----------------------------------------------------------------------===## +## +## This source file is part of the Swift Metrics API open source project +## +## Copyright (c) 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 +## +##===----------------------------------------------------------------------===## + +##===----------------------------------------------------------------------===## +## +## This source file is part of the SwiftNIO open source project +## +## Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors +## Licensed under Apache License v2.0 +## +## See LICENSE.txt for license information +## See CONTRIBUTORS.txt for the list of SwiftNIO project authors +## +## SPDX-License-Identifier: Apache-2.0 +## +##===----------------------------------------------------------------------===## + +set -eu + +# repodir +function all_modules() { + local repodir="$1" + ( + set -eu + cd "$repodir" + swift package dump-package | jq '.products | + map(select(.type | has("library") )) | + map(.name) | .[]' | tr -d '"' + ) +} + +# repodir tag output +function build_and_do() { + local repodir=$1 + local tag=$2 + local output=$3 + + ( + cd "$repodir" + git checkout -q "$tag" + swift build + while read -r module; do + swift api-digester -sdk "$sdk" -dump-sdk -module "$module" \ + -o "$output/$module.json" -I "$repodir/.build/debug" + done < <(all_modules "$repodir") + ) +} + +function usage() { + echo >&2 "Usage: $0 REPO-GITHUB-URL NEW-VERSION OLD-VERSIONS..." + echo >&2 + echo >&2 "This script requires a Swift 5.1+ toolchain." + echo >&2 + echo >&2 "Examples:" + echo >&2 + echo >&2 "Check between master and tag 2.1.1 of swift-nio:" + echo >&2 " $0 https://github.com/apple/swift-nio master 2.1.1" + echo >&2 + echo >&2 "Check between HEAD and commit 64cf63d7 using the provided toolchain:" + echo >&2 " xcrun --toolchain org.swift.5120190702a $0 ../some-local-repo HEAD 64cf63d7" +} + +if [[ $# -lt 3 ]]; then + usage + exit 1 +fi + +sdk=/ +if [[ "$(uname -s)" == Darwin ]]; then + sdk=$(xcrun --show-sdk-path) +fi + +hash jq 2> /dev/null || { echo >&2 "ERROR: jq must be installed"; exit 1; } +tmpdir=$(mktemp -d /tmp/.check-api_XXXXXX) +repo_url=$1 +new_tag=$2 +shift 2 + +repodir="$tmpdir/repo" +git clone "$repo_url" "$repodir" +git -C "$repodir" fetch -q origin '+refs/pull/*:refs/remotes/origin/pr/*' +errors=0 + +for old_tag in "$@"; do + mkdir "$tmpdir/api-old" + mkdir "$tmpdir/api-new" + + echo "Checking public API breakages from $old_tag to $new_tag" + + build_and_do "$repodir" "$new_tag" "$tmpdir/api-new/" + build_and_do "$repodir" "$old_tag" "$tmpdir/api-old/" + + for f in "$tmpdir/api-new"/*; do + f=$(basename "$f") + report="$tmpdir/$f.report" + if [[ ! -f "$tmpdir/api-old/$f" ]]; then + echo "NOTICE: NEW MODULE $f" + continue + fi + + echo -n "Checking $f... " + swift api-digester -sdk "$sdk" -diagnose-sdk \ + --input-paths "$tmpdir/api-old/$f" -input-paths "$tmpdir/api-new/$f" 2>&1 \ + > "$report" 2>&1 + + if ! shasum "$report" | grep -q cefc4ee5bb7bcdb7cb5a7747efa178dab3c794d5; then + echo ERROR + echo >&2 "==============================" + echo >&2 "ERROR: public API change in $f" + echo >&2 "==============================" + cat >&2 "$report" + errors=$(( errors + 1 )) + else + echo OK + fi + done + rm -rf "$tmpdir/api-new" "$tmpdir/api-old" +done + +if [[ "$errors" == 0 ]]; then + echo "OK, all seems good" +fi +echo done +exit "$errors" diff --git a/scripts/generate_contributors_list.sh b/scripts/generate_contributors_list.sh new file mode 100755 index 0000000..87462fd --- /dev/null +++ b/scripts/generate_contributors_list.sh @@ -0,0 +1,39 @@ +#!/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 +## +##===----------------------------------------------------------------------===## + +set -eu +here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" +contributors=$( cd "$here"/.. && git shortlog -es | cut -f2 | sed 's/^/- /' ) + +cat > "$here/../CONTRIBUTORS.txt" <<- EOF + For the purpose of tracking copyright, this is the list of individuals and + organizations who have contributed source code to the Swift Metrics API. + + For employees of an organization/company where the copyright of work done + by employees of that company is held by the company itself, only the company + needs to be listed here. + + ## COPYRIGHT HOLDERS + + - Apple Inc. (all contributors with '@apple.com') + + ### Contributors + + $contributors + + **Updating this list** + + Please do not edit this file manually. It is generated using \`./scripts/generate_contributors_list.sh\`. If a name is misspelled or appearing multiple times: add an entry in \`./.mailmap\` +EOF diff --git a/scripts/generate_docs.sh b/scripts/generate_docs.sh new file mode 100755 index 0000000..f25e4bf --- /dev/null +++ b/scripts/generate_docs.sh @@ -0,0 +1,122 @@ +#!/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 +## +##===----------------------------------------------------------------------===## + +set -e + +my_path="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" +root_path="$my_path/.." +version=$(git describe --abbrev=0 --tags || echo "0.0.0") +modules=(CoreMetrics Metrics) + +if [[ "$(uname -s)" == "Linux" ]]; then + # build code if required + if [[ ! -d "$root_path/.build/x86_64-unknown-linux" ]]; then + swift build + fi + # setup source-kitten if required + source_kitten_source_path="$root_path/.SourceKitten" + if [[ ! -d "$source_kitten_source_path" ]]; then + git clone https://github.com/jpsim/SourceKitten.git "$source_kitten_source_path" + fi + source_kitten_path="$source_kitten_source_path/.build/x86_64-unknown-linux/debug" + if [[ ! -d "$source_kitten_path" ]]; then + rm -rf "$source_kitten_source_path/.swift-version" + cd "$source_kitten_source_path" && swift build && cd "$root_path" + fi + # generate + mkdir -p "$root_path/.build/sourcekitten" + for module in "${modules[@]}"; do + if [[ ! -f "$root_path/.build/sourcekitten/$module.json" ]]; then + "$source_kitten_path/sourcekitten" doc --spm-module $module > "$root_path/.build/sourcekitten/$module.json" + fi + done +fi + +[[ -d docs/$version ]] || mkdir -p docs/$version +[[ -d swift-metrics.xcodeproj ]] || swift package generate-xcodeproj + +# run jazzy +if ! command -v jazzy > /dev/null; then + gem install jazzy --no-ri --no-rdoc +fi + +jazzy_dir="$root_path/.build/jazzy" +rm -rf "$jazzy_dir" +mkdir -p "$jazzy_dir" + +module_switcher="$jazzy_dir/README.md" +jazzy_args=(--clean + --author 'SwiftMetrics team' + --readme "$module_switcher" + --author_url https://github.com/apple/swift-metrics + --github_url https://github.com/apple/swift-metrics + --github-file-prefix https://github.com/apple/swift-metrics/tree/$version + --theme fullwidth + --xcodebuild-arguments -scheme,swift-metrics-Package) +cat > "$module_switcher" <<"EOF" +# SwiftMetrics Docs + +SwiftMetrics is a Swift metrics API package. + +To get started with SwiftMetrics, [`import Metrics`](../CoreMetrics/index.html). The most important types are: + +* [`Counter`](https://apple.github.io/swift-metrics/docs/current/CoreMetrics/Classes/Counter.html) +* [`Timer`](https://apple.github.io/swift-metrics/docs/current/CoreMetrics/Classes/Timer.html) +* [`Recorder`](https://apple.github.io/swift-metrics/docs/current/CoreMetrics/Classes/Recorder.html) +* [`Gauge`](https://apple.github.io/swift-metrics/docs/current/CoreMetrics/Classes/Gauge.html) + +SwiftMetrics contains multiple modules: +EOF + +for module in "${modules[@]}"; do + echo " - [$module](../$module/index.html)" >> "$module_switcher" +done + +for module in "${modules[@]}"; do + echo "processing $module" + args=("${jazzy_args[@]}" --output "$jazzy_dir/docs/$version/$module" --docset-path "$jazzy_dir/docset/$version/$module" + --module "$module" --module-version $version + --root-url "https://apple.github.io/swift-metrics/docs/$version/$module/") + if [[ -f "$root_path/.build/sourcekitten/$module.json" ]]; then + args+=(--sourcekitten-sourcefile "$root_path/.build/sourcekitten/$module.json") + fi + jazzy "${args[@]}" +done + +# push to github pages +if [[ $PUSH == true ]]; then + BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD) + GIT_AUTHOR=$(git --no-pager show -s --format='%an <%ae>' HEAD) + git fetch origin +gh-pages:gh-pages + git checkout gh-pages + rm -rf "docs/$version" + rm -rf "docs/current" + cp -r "$jazzy_dir/docs/$version" docs/ + cp -r "docs/$version" docs/current + git add --all docs + echo '' > index.html + git add index.html + touch .nojekyll + git add .nojekyll + changes=$(git diff-index --name-only HEAD) + if [[ -n "$changes" ]]; then + echo -e "changes detected\n$changes" + git commit --author="$GIT_AUTHOR" -m "publish $version docs" + git push origin gh-pages + else + echo "no changes detected" + fi + git checkout -f $BRANCH_NAME +fi diff --git a/scripts/generate_linux_tests.rb b/scripts/generate_linux_tests.rb new file mode 100755 index 0000000..eef6ecd --- /dev/null +++ b/scripts/generate_linux_tests.rb @@ -0,0 +1,231 @@ +#!/usr/bin/env ruby + +# +# process_test_files.rb +# +# Copyright 2016 Tony Stone +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# Created by Tony Stone on 5/4/16. +# +require 'getoptlong' +require 'fileutils' +require 'pathname' + +include FileUtils + +# +# This ruby script will auto generate LinuxMain.swift and the +XCTest.swift extension files for Swift Package Manager on Linux platforms. +# +# See https://github.com/apple/swift-corelibs-xctest/blob/master/Documentation/Linux.md +# +def header(fileName) + string = <<-eos +//===----------------------------------------------------------------------===// +// +// 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 XCTest + +/// +/// NOTE: This file was generated by generate_linux_tests.rb +/// +/// Do NOT edit this file directly as it will be regenerated automatically when needed. +/// + eos + + string + .sub('', File.basename(fileName)) + .sub('', Time.now.to_s) +end + +def createExtensionFile(fileName, classes) + extensionFile = fileName.sub! '.swift', '+XCTest.swift' + print 'Creating file: ' + extensionFile + "\n" + + File.open(extensionFile, 'w') do |file| + file.write header(extensionFile) + file.write "\n" + + for classArray in classes + file.write 'extension ' + classArray[0] + " {\n" + file.write ' static var allTests: [(String, (' + classArray[0] + ") -> () throws -> Void)] {\n" + file.write " return [\n" + + for funcName in classArray[1] + file.write ' ("' + funcName + '", ' + funcName + "),\n" + end + + file.write " ]\n" + file.write " }\n" + file.write "}\n" + end + end +end + +def createLinuxMain(testsDirectory, allTestSubDirectories, files) + fileName = testsDirectory + '/LinuxMain.swift' + print 'Creating file: ' + fileName + "\n" + + File.open(fileName, 'w') do |file| + file.write header(fileName) + file.write "\n" + + file.write "#if os(Linux) || os(FreeBSD)\n" + for testSubDirectory in allTestSubDirectories.sort { |x, y| x <=> y } + file.write '@testable import ' + testSubDirectory + "\n" + end + file.write "\n" + file.write "XCTMain([\n" + + testCases = [] + for classes in files + for classArray in classes + testCases << classArray[0] + end + end + + for testCase in testCases.sort { |x, y| x <=> y } + file.write ' testCase(' + testCase + ".allTests),\n" + end + file.write "])\n" + file.write "#endif\n" + end +end + +def parseSourceFile(fileName) + puts 'Parsing file: ' + fileName + "\n" + + classes = [] + currentClass = nil + inIfLinux = false + inElse = false + ignore = false + + # + # Read the file line by line + # and parse to find the class + # names and func names + # + File.readlines(fileName).each do |line| + if inIfLinux + if /\#else/.match(line) + inElse = true + ignore = true + else + if /\#end/.match(line) + inElse = false + inIfLinux = false + ignore = false + end + end + else + if /\#if[ \t]+os\(Linux\)/.match(line) + inIfLinux = true + ignore = false + end + end + + next if ignore + # Match class or func + match = line[/class[ \t]+[a-zA-Z0-9_]*(?=[ \t]*:[ \t]*XCTestCase)|func[ \t]+test[a-zA-Z0-9_]*(?=[ \t]*\(\))/, 0] + if match + + if match[/class/, 0] == 'class' + className = match.sub(/^class[ \t]+/, '') + # + # Create a new class / func structure + # and add it to the classes array. + # + currentClass = [className, []] + classes << currentClass + else # Must be a func + funcName = match.sub(/^func[ \t]+/, '') + # + # Add each func name the the class / func + # structure created above. + # + currentClass[1] << funcName + end + end + end + classes +end + +# +# Main routine +# +# + +testsDirectory = 'Tests' + +options = GetoptLong.new(['--tests-dir', GetoptLong::OPTIONAL_ARGUMENT]) +options.quiet = true + +begin + options.each do |option, value| + case option + when '--tests-dir' + testsDirectory = value + end + end +rescue GetoptLong::InvalidOption +end + +allTestSubDirectories = [] +allFiles = [] + +Dir[testsDirectory + '/*'].each do |subDirectory| + next unless File.directory?(subDirectory) + directoryHasClasses = false + Dir[subDirectory + '/*Test{s,}.swift'].each do |fileName| + next unless File.file? fileName + fileClasses = parseSourceFile(fileName) + + # + # If there are classes in the + # test source file, create an extension + # file for it. + # + next unless fileClasses.count > 0 + createExtensionFile(fileName, fileClasses) + directoryHasClasses = true + allFiles << fileClasses + end + + if directoryHasClasses + allTestSubDirectories << Pathname.new(subDirectory).split.last.to_s + end +end + +# +# Last step is the create a LinuxMain.swift file that +# references all the classes and funcs in the source files. +# +if allFiles.count > 0 + createLinuxMain(testsDirectory, allTestSubDirectories, allFiles) +end +# eof diff --git a/scripts/sanity.sh b/scripts/sanity.sh new file mode 100755 index 0000000..6e73704 --- /dev/null +++ b/scripts/sanity.sh @@ -0,0 +1,153 @@ +#!/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 +## +##===----------------------------------------------------------------------===## + +##===----------------------------------------------------------------------===## +## +## This source file is part of the SwiftNIO open source project +## +## Copyright (c) 2017-2019 Apple Inc. and the SwiftNIO project authors +## Licensed under Apache License v2.0 +## +## See LICENSE.txt for license information +## See CONTRIBUTORS.txt for the list of SwiftNIO project authors +## +## SPDX-License-Identifier: Apache-2.0 +## +##===----------------------------------------------------------------------===## + +set -eu +here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" + +function replace_acceptable_years() { + # this needs to replace all acceptable forms with 'YEARS' + sed -e 's/2018-2019/YEARS/' -e 's/2019/YEARS/' +} + +printf "=> Checking linux tests... " +FIRST_OUT="$(git status --porcelain)" +ruby "$here/../scripts/generate_linux_tests.rb" > /dev/null +SECOND_OUT="$(git status --porcelain)" +if [[ "$FIRST_OUT" != "$SECOND_OUT" ]]; then + printf "\033[0;31mmissing changes!\033[0m\n" + git --no-pager diff + exit 1 +else + printf "\033[0;32mokay.\033[0m\n" +fi + +printf "=> Checking format... " +FIRST_OUT="$(git status --porcelain)" +swiftformat . > /dev/null 2>&1 +SECOND_OUT="$(git status --porcelain)" +if [[ "$FIRST_OUT" != "$SECOND_OUT" ]]; then + printf "\033[0;31mformatting issues!\033[0m\n" + git --no-pager diff + exit 1 +else + printf "\033[0;32mokay.\033[0m\n" +fi + +printf "=> Checking license headers\n" +tmp=$(mktemp /tmp/.swift-metrics-sanity_XXXXXX) + +for language in swift-or-c bash dtrace; do + printf " * $language... " + declare -a matching_files + declare -a exceptions + expections=( ) + 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) + matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' ) + cat > "$tmp" <<"EOF" +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Metrics API open source project +// +// Copyright (c) YEARS 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 +// +//===----------------------------------------------------------------------===// +EOF + ;; + bash) + matching_files=( -name '*.sh' ) + cat > "$tmp" <<"EOF" +#!/bin/bash +##===----------------------------------------------------------------------===## +## +## This source file is part of the Swift Metrics API open source project +## +## Copyright (c) YEARS 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 +## +##===----------------------------------------------------------------------===## +EOF + ;; + dtrace) + matching_files=( -name '*.d' ) + cat > "$tmp" <<"EOF" +#!/usr/sbin/dtrace -q -s +/*===----------------------------------------------------------------------===* + * + * This source file is part of the Swift Metrics API open source project + * + * Copyright (c) YEARS 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 + * + *===----------------------------------------------------------------------===*/ +EOF + ;; + *) + echo >&2 "ERROR: unknown language '$language'" + ;; + esac + + expected_lines=$(cat "$tmp" | wc -l) + expected_sha=$(cat "$tmp" | shasum) + + ( + cd "$here/.." + find . \ + \( \! -path './.build/*' -a \ + \( "${matching_files[@]}" \) -a \ + \( \! \( "${exceptions[@]}" \) \) \) | while read line; do + if [[ "$(cat "$line" | replace_acceptable_years | head -n $expected_lines | shasum)" != "$expected_sha" ]]; then + printf "\033[0;31mmissing headers in file '$line'!\033[0m\n" + diff -u <(cat "$line" | replace_acceptable_years | head -n $expected_lines) "$tmp" + exit 1 + fi + done + printf "\033[0;32mokay.\033[0m\n" + ) +done + +rm "$tmp"