Skip to content

Commit b7ed98c

Browse files
fabianfettFranzBuschhamzahrmalik
authored
Add docs for version 2.0 (#100)
- Removed overly verbose issue and pr templates - Removed documentation from README - Readme now links to spi documentation page - Added docc documentation - Removed last usages of `TimeHistogram` Co-authored-by: Franz Busch <[email protected]> Co-authored-by: hamzahrmalik <[email protected]>
1 parent 26e2b29 commit b7ed98c

File tree

9 files changed

+276
-240
lines changed

9 files changed

+276
-240
lines changed

‎.github/ISSUE_TEMPLATE/BUG_REPORT.md

Lines changed: 0 additions & 32 deletions
This file was deleted.

‎.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md

Lines changed: 0 additions & 23 deletions
This file was deleted.

‎.github/ISSUE_TEMPLATE/OTHER.md

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎README.md

Lines changed: 12 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -1,139 +1,23 @@
1-
[![Swift 5.2](https://img.shields.io/badge/swift-5.2-orange.svg?style=flat)](http://swift.org)
1+
# Swift Prometheus
22

3-
# SwiftPrometheus, Prometheus client for Swift
3+
[![sswg:sandbox](https://img.shields.io/badge/sswg-sandbox-yellow.svg)][SSWG-Incubation]
4+
[![Documentation](http://img.shields.io/badge/read_the-docs-2196f3.svg)][Documentation]
45

5-
A prometheus client for Swift supporting counters, gauges, histograms, summaries and info.
6-
7-
# Installation
8-
9-
SwiftPrometheus is available through SPM. To include it in your project add the following dependency to your `Package.swift`:
10-
```swift
11-
.package(url: "https://github.com/swift-server-community/SwiftPrometheus.git", from: "1.0.2")
12-
```
13-
14-
# Usage
15-
16-
To see a working demo, see [PrometheusExample](./Sources/PrometheusExample/main.swift).
17-
18-
First, we have to create an instance of our `PrometheusClient`:
19-
20-
```swift
21-
import Prometheus
22-
let myProm = PrometheusClient()
23-
```
24-
25-
## Usage with SwiftMetrics
26-
_For more details about swift-metrics, please view [the GitHub repo](https://github.com/apple/swift-metrics)._
27-
28-
Starting with SwiftPrometheus [1.0.0-alpha.10](https://github.com/swift-server-community/SwiftPrometheus/releases/tag/1.0.0-alpha.10) `MetricsSystem` is no longer directly configured with a `PrometheusClient`.
29-
30-
Instead, create a `PrometheusMetricsFactory` instance wrapping a `PrometheusClient`.
31-
32-
```swift
33-
let myProm = PrometheusClient()
34-
MetricsSystem.bootstrap(PrometheusMetricsFactory(client: myProm))
35-
```
36-
37-
Along with a `PrometheusClient`, `PrometheusMetricsFactory` can take a `Configuration` object setting the following properties:
38-
- A `LabelSanitizer` used to sanitize metric names to valid Prometheus values. A default implementation is provided.
39-
- The Prometheus metric type to use for swift-metrics' `Timer`. Can be a `Histogram` or a `Summary`. Note that when using `Histogram`, `preferredDisplayUnit` will not be observed.
40-
- Default buckets for use by aggregating swift-metrics `Recorder` instances.
41-
42-
### Before Alpha 10
43-
44-
To use SwiftPrometheus with swift-metrics, you need to configure the backend inside the `MetricsSystem`:
45-
46-
```swift
47-
import Metrics
48-
import Prometheus
49-
let myProm = PrometheusClient()
50-
MetricsSystem.bootstrap(myProm)
51-
```
52-
53-
To use prometheus-specific features in a later stage of your program, or to get your metrics out of the system, there is a convenience method added to `MetricsSystem`:
54-
55-
```swift
56-
// This returns the same instance passed in to `.bootstrap()` earlier.
57-
let promInstance = try MetricsSystem.prometheus()
58-
print(promInstance.collect())
59-
```
60-
61-
You can then use the same APIs described in the rest of this README.
62-
63-
## Counter
64-
65-
Counters go up (they can only increase in value), and reset when the process restarts.
66-
67-
```swift
68-
let counter = myProm.createCounter(forType: Int.self, named: "my_counter")
69-
counter.inc() // Increment by 1
70-
counter.inc(12) // Increment by given value
71-
```
72-
73-
## Gauge
74-
75-
Gauges can go up and down, they represent a "point-in-time" snapshot of a value. This is similar to the speedometer of a car.
76-
77-
```swift
78-
let gauge = myProm.createGauge(forType: Int.self, named: "my_gauge")
79-
gauge.inc() // Increment by 1
80-
gauge.dec(19) // Decrement by given value
81-
gauge.set(12) // Set to a given value
82-
```
83-
84-
## Histogram
85-
86-
Histograms track the size and number of events in buckets. This allows for aggregatable calculation of quantiles.
87-
88-
```swift
89-
let histogram = myProm.createHistogram(forType: Double.self, named: "my_histogram")
90-
histogram.observe(4.7) // Observe the given value
91-
```
92-
93-
## Summary
94-
95-
Summaries track the size and number of events
96-
97-
```swift
98-
let summary = myProm.createSummary(forType: Double.self, named: "my_summary")
99-
summary.observe(4.7) // Observe the given value
100-
```
101-
102-
## Labels
103-
All metric types support adding labels, allowing for grouping of related metrics. Labels are passed when recording values to your metric as an instance of `DimensionLabels`, or as an array of `(String, String)`.
104-
105-
Example with a counter:
106-
107-
```swift
108-
let counter = myProm.createCounter(forType: Int.self, named: "my_counter", helpText: "Just a counter")
109-
110-
let counter = prom.createCounter(forType: Int.self, named: "my_counter", helpText: "Just a counter")
111-
112-
counter.inc(12, .init([("route", "/users")]))
113-
// OR
114-
counter.inc(12, [("route", "/users")])
115-
```
116-
117-
# Exporting
118-
119-
Prometheus itself is designed to "pull" metrics from a destination. Following this pattern, SwiftPrometheus is designed to expose metrics, as opposed to submitted/exporting them directly to Prometheus itself. SwiftPrometheus produces a formatted string that Prometheus can parse, which can be integrated into your own application.
120-
121-
By default, this should be accessible on your main serving port, at the `/metrics` endpoint. An example in [Vapor](https://vapor.codes) 4 syntax looks like:
122-
123-
```swift
124-
app.get("metrics") { req async throws -> String in
125-
return try await MetricsSystem.prometheus().collect()
126-
}
127-
```
6+
A prometheus client for Swift supporting counters, gauges and histograms. Swift Prometheus
7+
implements the Swift Metrics API.
1288

1299
## Security
13010

13111
Please see [SECURITY.md](SECURITY.md) for details on the security process.
13212

133-
# Contributing
13+
## Contributing
13414

13515
All contributions are most welcome!
13616

137-
If you think of some cool new feature that should be included, please [create an issue](https://github.com/swift-server-community/SwiftPrometheus/issues/new/choose). Or, if you want to implement it yourself, [fork this repo](https://github.com/swift-server-community/SwiftPrometheus/fork) and submit a PR!
17+
If you think of some cool new feature that should be included, please [create an issue](https://github.com/swift-server/swift-prometheus/issues/new).
18+
Or, if you want to implement it yourself, [fork this repo](https://github.com/swift-server/swift-prometheus/fork) and submit a PR!
19+
20+
If you find a bug or have issues, please [create an issue](https://github.com/swift-server-community/SwiftPrometheus/issues/new) explaining your problems. Please include as much information as possible, so it's easier for us to reproduce (Framework, OS, Swift version, terminal output, etc.)
13821

139-
If you find a bug or have issues, please [create an issue](https://github.com/swift-server-community/SwiftPrometheus/issues/new/choose) 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.)
22+
[Documentation]: https://swiftpackageindex.com/swift-server/swift-prometheus/documentation/prometheus
23+
[SSWG-Incubation]: https://www.swift.org/sswg/incubation-process.html

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

Lines changed: 65 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,77 @@ A prometheus client library for Swift.
55
## Overview
66

77
``Prometheus`` supports creating ``Counter``s, ``Gauge``s and ``Histogram``s and exporting their
8-
values in the Prometheus export format.
8+
values in the Prometheus text format.
9+
10+
``Prometheus`` integrates with [Swift Metrics](doc:swift-metrics).
11+
12+
## Installation
13+
14+
``Prometheus`` is available through Swift Package Manager. To include it in your project add the
15+
following dependency to your `Package.swift`:
16+
17+
```swift
18+
.package(url: "https://github.com/swift-server/swift-prometheus.git", from: "2.0.0-alpha")
19+
```
20+
21+
Next, add the dependency to your target:
22+
23+
```swift
24+
.target(
25+
name: "MyTarget",
26+
dependencies: [
27+
// your other dependencies
28+
.product(name: "Prometheus", package: "swift-prometheus"),
29+
]
30+
),
31+
```
32+
33+
## Usage
34+
35+
In your Swift file you must first `import Prometheus`:
36+
37+
```swift
38+
import Prometheus
39+
```
40+
41+
Next you need to create a ``PrometheusCollectorRegistry``, which you use to create ``Counter``s,
42+
``Gauge``s and ``Histogram``s.
43+
44+
```swift
45+
let registry = PrometheusCollectorRegistry()
46+
47+
let myCounter = registry.makeCounter(name: "my_counter")
48+
myCounter.increment()
49+
50+
let myGauge = registry.makeGauge(name: "my_gauge")
51+
myGauge.increment()
52+
myGauge.decrement()
53+
```
54+
55+
Lastly, you can use your ``PrometheusCollectorRegistry`` to generate a Prometheus export in the
56+
text representation:
57+
58+
```swift
59+
var buffer = [UInt8]()
60+
buffer.reserveCapacity(1024) // potentially smart moves to reduce the number of reallocations
61+
registry.emit(into: buffer)
62+
63+
print(String(decoding: buffer, as: Unicode.UTF8.self))
64+
```
965

1066
## Topics
1167

12-
### Collectors
68+
### Getting started
69+
70+
- <doc:swift-metrics>
71+
- ``PrometheusCollectorRegistry``
72+
- ``PrometheusMetricsFactory``
73+
74+
75+
### Metrics
1376

1477
- ``Counter``
1578
- ``Gauge``
1679
- ``Histogram``
17-
- ``Bucketable``
1880
- ``DurationHistogram``
1981
- ``ValueHistogram``

0 commit comments

Comments
 (0)