Skip to content

Commit de124db

Browse files
MrLotUMrLotU
committed
README & GH Templates
Signed-off-by: MrLotU <[email protected]>
1 parent 817312b commit de124db

File tree

10 files changed

+432
-97
lines changed

10 files changed

+432
-97
lines changed

‎.github/ISSUE_TEMPLATE/BUG_REPORT.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
name: 🐛 Bug Report
3+
about: If something isn't working as expected 🤔
4+
5+
---
6+
<!-- 🚀 Thank you for contributing! --->
7+
8+
<!-- Provide a brief description of the issue here. -->
9+
<!-- Pretend you are explaining it to a friend, not yourself! -->
10+
11+
### Steps to reproduce
12+
13+
<!-- Tell us how to reproduce this issue. -->
14+
<!-- Please provide as much detail as possible (the more code snippets, the better)! -->
15+
<!-- If we cannot recreate it, we will not be able to figure out how to fix it. -->
16+
17+
### Expected behavior
18+
19+
<!-- Tell us what you expect to happen (what should happen once we fix the issue). -->
20+
21+
### Actual behavior
22+
23+
<!-- Tell us what is actually happening (what is broken/not working correctly). -->
24+
25+
### Environment
26+
27+
<!-- We must know your exact environment or it is very difficult to help. -->
28+
29+
* OS version:
30+
* Swift version:
31+
* Serverside Swift Framework:
32+
* Framework version:

‎.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
name: 🚀 Feature Request
3+
about: A suggestion for a new feature ✨
4+
5+
---
6+
7+
<!-- 🚀 Thank you for contributing! --->
8+
9+
### Feature Request
10+
11+
<!-- Provide a brief description of the feature here. -->
12+
13+
#### Motivation Behind Feature
14+
<!-- Why should this feature be implemented? What problem does it solve? -->
15+
16+
#### Feature Description
17+
<!-- Describe your feature request in detail -->
18+
<!-- Please provide any code examples or screenshots of what this feature would look like -->
19+
<!-- Are there any drawbacks? Will this break anything for existing users? -->
20+
21+
#### Alternatives or Workarounds
22+
<!-- Describe alternatives or workarounds you are currently using -->
23+
<!-- Are there ways to do this with existing actions and plugins? -->

‎.github/ISSUE_TEMPLATE/OTHER.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
name: Other issues
3+
about: If something else is on your mind
4+
5+
---
6+
7+
<!-- 🚀 Thank you for contributing! --->
8+
9+
<!-- Provide a brief description of the issue here. -->

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<!-- 🚀 Thank you for contributing! --->
2+
3+
<!-- Provide a brief description of the PR here. -->
4+
5+
### Checklist
6+
- [ ] The provided tests still run.
7+
- [ ] I've created new tests where needed.
8+
- [ ] I've updated the documentation if necessary.
9+
10+
### Motivation and Context
11+
<!-- Why is this change required? What problem does it solve? -->
12+
<!-- If it fixes an open issue, please link to the issue here. -->
13+
14+
### Description
15+
<!-- Describe your changes in detail -->
16+
<!-- Please describe in detail how you tested your changes. -->

‎Package.swift‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,15 @@
11
// swift-tools-version:4.2
2-
// The swift-tools-version declares the minimum version of Swift required to build this package.
32

43
import PackageDescription
54

65
let package = Package(
76
name: "SwiftPrometheus",
87
products: [
9-
// Products define the executables and libraries produced by a package, and make them visible to other packages.
108
.library(
119
name: "SwiftPrometheus",
1210
targets: ["Prometheus"]),
1311
],
14-
dependencies: [
15-
// Dependencies declare other packages that this package depends on.
16-
// .package(url: /* package url */, from: "1.0.0"),
17-
],
1812
targets: [
19-
// Targets are the basic building blocks of a package. A target can define a module or a test suite.
20-
// Targets can depend on other targets in this package, and on products in packages which this package depends on.
2113
.target(
2214
name: "Prometheus",
2315
dependencies: []),

‎README.md‎

Lines changed: 103 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,104 @@
1-
# SwiftPrometheus
1+
[![Build Status](https://travis-ci.com/MrLotU/SwiftPrometheus.svg?branch=master)](https://travis-ci.com/MrLotU/SwiftPrometheus) [![Swift 4.2](https://img.shields.io/badge/swift-4.2-orange.svg?style=flat)](http://swift.org)
22

3-
A description of this package.
3+
# SwiftPrometheus, Prometheus client for Swift
4+
5+
A prometheus client for Swift supporting counters, gauges, histograms, summaries and info.
6+
7+
# Usage
8+
9+
For examples, see [main.swift](./Sources/PrometheusExample/main.swift)
10+
11+
## Counter
12+
13+
Counters go up, and reset when the process restarts.
14+
15+
```swift
16+
let counter = Prometheus.shared.createCounter(forType: Int.self, named: "my_counter")
17+
counter.inc() // Increment by 1
18+
counter.inc(12) // Increment by given value
19+
```
20+
21+
## Gauge
22+
23+
Gauges can go up and down
24+
25+
```swift
26+
let gauge = Prometheus.shared.createGauge(forType: Int.self, named: "my_gauge")
27+
gauge.inc() // Increment by 1
28+
gauge.dec(19) // Decrement by given value
29+
gauge.set(12) // Set to a given value
30+
```
31+
32+
## Histogram
33+
34+
Histograms track the size and number of events in buckets. This allows for aggregatable calculation of quantiles.
35+
36+
```swift
37+
let histogram = Prometheus.shared.createHistogram(forType: Double.self, named: "my_histogram")
38+
histogram.observe(4.7) // Observe the given value
39+
```
40+
41+
## Summary
42+
43+
Summaries track the size and number of events
44+
45+
```swift
46+
let summary = Prometheus.shared.createSummary(forType: Double.self, named: "my_summary")
47+
summary.observe(4.7) // Observe the given value
48+
```
49+
50+
## Info
51+
52+
Info tracks key-value information, usually about a whole target.
53+
54+
```swift
55+
struct MyInfoStruct: MetricLabels {
56+
let value: String
57+
58+
init() {
59+
self.value = "abc"
60+
}
61+
62+
init(_ v: String) {
63+
self.value = v
64+
}
65+
}
66+
67+
let info = Prometheus.shared.createInfo(named: "my_info", helpText: "Just some info", labelType: MyInfoStruct.self)
68+
69+
info.info(MyInfoStruct("def"))
70+
```
71+
72+
## Labels
73+
All metric types support adding labels, allowing for grouping of related metrics.
74+
75+
Example with a counter:
76+
```swift
77+
struct RouteLabels: MetricLabels {
78+
var route: String = "*"
79+
}
80+
81+
let counter = Prometheus.shared.createCounter(forType: Int.self, named: "my_counter", helpText: "Just a counter", withLabelType: RouteLabels.self)
82+
83+
counter.inc(12, .init(route: "/"))
84+
```
85+
86+
# Exporting
87+
88+
To keep SwiftPrometheus as clean and leight weitght as possible, there is no way of exporting metrics to Prometheus. All you can do is get a formatted string that Prometheus can use, so you can integrate it in your own Serverside Swift application
89+
90+
This could look something like this:
91+
```swift
92+
router.get("/metrics") { request -> String in
93+
return Prometheus.shared.getMetrics()
94+
}
95+
```
96+
Here, I used [Vapor](https://github.com/vapor/vapor) syntax, but this will work with any web framework, since it's just returning a plain String.
97+
98+
# Contributing
99+
100+
All contributions are most welcome!
101+
102+
If you think of some crazy cool new feature that should be included, please [create an issue](https://github.com/MrLotU/SwiftPrometheus/issues/new). Or, if you want to implement it yourself, [fork this repo](https://github.com/MrLotU/SwiftPrometheus/fork) and submit a PR!
103+
104+
If you find a bug or have issues, please [create an issue](https://github.com/MrLotU/SwiftPrometheus/issues/new) explaining your problems. Please include as much information as possible, so it's easier for me to reproduce (Framework, OS, Swift version, terminal output, etc.)

‎Sources/PrometheusExample/main.swift‎

Lines changed: 83 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,87 @@
11
import Prometheus
22

3-
//struct MyCodable: MetricLabels {
4-
// var thing: String = "*"
5-
//}
6-
//
7-
//let codable1 = MyCodable(thing: "Thing1")
8-
//let codable2 = MyCodable(thing: "Thing2")
9-
//
10-
//let counter = Prometheus.shared.createCounter(forType: Int.self, named: "my_counter", helpText: "Just a counter", initialValue: 12, withLabelType: MyCodable.self)
11-
//
12-
//counter.inc(5)
13-
//counter.inc(Int.random(in: 0...100), codable2)
14-
//counter.inc(Int.random(in: 0...100), codable1)
15-
//
16-
//let gauge = Prometheus.shared.createGauge(forType: Int.self, named: "my_gauge", helpText: "Just a gauge", initialValue: 12, withLabelType: MyCodable.self)
17-
//
18-
//gauge.inc(100)
19-
//gauge.inc(Int.random(in: 0...100), codable2)
20-
//gauge.inc(Int.random(in: 0...100), codable1)
21-
//
22-
//struct HistogramThing: HistogramLabels {
23-
// var le: String = ""
24-
// let route: String
25-
//
26-
// init() {
27-
// self.route = "*"
28-
// }
29-
//
30-
// init(_ route: String) {
31-
// self.route = route
32-
// }
33-
//}
34-
//
35-
//let histogram = Prometheus.shared.createHistogram(forType: Double.self, named: "my_histogram", helpText: "Just a histogram", labels: HistogramThing.self)
36-
//
37-
//for _ in 0...Int.random(in: 10...50) {
38-
// histogram.observe(Double.random(in: 0...1))
39-
//}
40-
//
41-
//for _ in 0...Int.random(in: 10...50) {
42-
// histogram.observe(Double.random(in: 0...1), HistogramThing("/test"))
43-
//}
44-
//
45-
//struct SummaryThing: SummaryLabels {
46-
// var quantile: String = ""
47-
// let route: String
48-
//
49-
// init() {
50-
// self.route = "*"
51-
// }
52-
//
53-
// init(_ route: String) {
54-
// self.route = route
55-
// }
56-
//}
57-
//
58-
//let summary = Prometheus.shared.createSummary(forType: Double.self, named: "my_summary", helpText: "Just a summary", labels: SummaryThing.self)
59-
//
60-
//for _ in 0...Int.random(in: 100...1000) {
61-
// summary.observe(Double.random(in: 0...10000))
62-
//}
63-
//
64-
//for _ in 0...Int.random(in: 100...1000) {
65-
// summary.observe(Double.random(in: 0...10000), SummaryThing("/test"))
66-
//}
67-
68-
//struct MyInfoStruct: MetricLabels {
69-
// let version: String
70-
// let major: String
71-
//
72-
// init() {
73-
// self.version = "1.0.0"
74-
// self.major = "1"
75-
// }
76-
//
77-
// init(_ v: String, _ m: String) {
78-
// self.version = v
79-
// self.major = m
80-
// }
81-
//}
82-
//
83-
//let info = Prometheus.shared.createInfo(named: "my_info", helpText: "Just some info", labelType: MyInfoStruct.self)
84-
//
85-
//info.info(MyInfoStruct("2.0.0", "2"))
3+
struct MyCodable: MetricLabels {
4+
var thing: String = "*"
5+
}
6+
7+
let codable1 = MyCodable(thing: "Thing1")
8+
let codable2 = MyCodable(thing: "Thing2")
9+
10+
let counter = Prometheus.shared.createCounter(forType: Int.self, named: "my_counter", helpText: "Just a counter", initialValue: 12, withLabelType: MyCodable.self)
11+
12+
counter.inc(5)
13+
counter.inc(Int.random(in: 0...100), codable2)
14+
counter.inc(Int.random(in: 0...100), codable1)
15+
16+
let gauge = Prometheus.shared.createGauge(forType: Int.self, named: "my_gauge", helpText: "Just a gauge", initialValue: 12, withLabelType: MyCodable.self)
17+
18+
gauge.inc(100)
19+
gauge.inc(Int.random(in: 0...100), codable2)
20+
gauge.inc(Int.random(in: 0...100), codable1)
21+
22+
struct HistogramThing: HistogramLabels {
23+
var le: String = ""
24+
let route: String
25+
26+
init() {
27+
self.route = "*"
28+
}
29+
30+
init(_ route: String) {
31+
self.route = route
32+
}
33+
}
34+
35+
let histogram = Prometheus.shared.createHistogram(forType: Double.self, named: "my_histogram", helpText: "Just a histogram", labels: HistogramThing.self)
36+
37+
for _ in 0...Int.random(in: 10...50) {
38+
histogram.observe(Double.random(in: 0...1))
39+
}
40+
41+
for _ in 0...Int.random(in: 10...50) {
42+
histogram.observe(Double.random(in: 0...1), HistogramThing("/test"))
43+
}
44+
45+
struct SummaryThing: SummaryLabels {
46+
var quantile: String = ""
47+
let route: String
48+
49+
init() {
50+
self.route = "*"
51+
}
52+
53+
init(_ route: String) {
54+
self.route = route
55+
}
56+
}
57+
58+
let summary = Prometheus.shared.createSummary(forType: Double.self, named: "my_summary", helpText: "Just a summary", labels: SummaryThing.self)
59+
60+
for _ in 0...Int.random(in: 100...1000) {
61+
summary.observe(Double.random(in: 0...10000))
62+
}
63+
64+
for _ in 0...Int.random(in: 100...1000) {
65+
summary.observe(Double.random(in: 0...10000), SummaryThing("/test"))
66+
}
67+
68+
struct MyInfoStruct: MetricLabels {
69+
let version: String
70+
let major: String
71+
72+
init() {
73+
self.version = "1.0.0"
74+
self.major = "1"
75+
}
76+
77+
init(_ v: String, _ m: String) {
78+
self.version = v
79+
self.major = m
80+
}
81+
}
82+
83+
let info = Prometheus.shared.createInfo(named: "my_info", helpText: "Just some info", labelType: MyInfoStruct.self)
84+
85+
info.info(MyInfoStruct("2.0.0", "2"))
8686

8787
print(Prometheus.shared.getMetrics())

0 commit comments

Comments
 (0)