Swiftpack.co - Package - MrLotU/SwiftPrometheus

CircleCISwift 5.0

SwiftPrometheus, Prometheus client for Swift

A prometheus client for Swift supporting counters, gauges, histograms, summaries and info.

Installation

SwiftPormetheus is available through SPM. To include it in your project add the following dependency to your Package.swift:

        .package(url: "https://github.com/MrLotU/SwiftPrometheus.git", from: "1.0.0-alpha")

NOTE: For NIO 1 use from: "0.4.0-alpha" instead.

Usage

To see a working demo, see PrometheusExample.

First, we have to create an instance of our PrometheusClient:

import Prometheus
let myProm = PrometheusClient()

Usage with SwiftMetrics

For more details about swift-metrics, please view the GitHub repo.

To use SwiftPrometheus with swift-metrics, you need to configure the backend inside the MetricsSystem:

import Metrics
import Prometheus
let myProm = PrometheusClient()
MetricsSystem.bootstrap(myProm)

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:

// This returns the same instance passed in to `.bootstrap()` earlier.
let promInstance = try MetricsSystem.prometheus()
print(promInstance.collect())

You can then use the same APIs described in the rest of this README.

Counter

Counters go up (they can only increase in value), and reset when the process restarts.

let counter = myProm.createCounter(forType: Int.self, named: "my_counter")
counter.inc() // Increment by 1
counter.inc(12) // Increment by given value

Gauge

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.

let gauge = myProm.createGauge(forType: Int.self, named: "my_gauge")
gauge.inc() // Increment by 1
gauge.dec(19) // Decrement by given value
gauge.set(12) // Set to a given value

Histogram

Histograms track the size and number of events in buckets. This allows for aggregatable calculation of quantiles.

let histogram = myProm.createHistogram(forType: Double.self, named: "my_histogram")
histogram.observe(4.7) // Observe the given value

Summary

Summaries track the size and number of events

let summary = myProm.createSummary(forType: Double.self, named: "my_summary")
summary.observe(4.7) // Observe the given value

Labels

All metric types support adding labels, allowing for grouping of related metrics.

Example with a counter:

struct RouteLabels: MetricLabels {
   var route: String = "*"
}

let counter = myProm.createCounter(forType: Int.self, named: "my_counter", helpText: "Just a counter", withLabelType: RouteLabels.self)

let counter = prom.createCounter(forType: Int.self, named: "my_counter", helpText: "Just a counter", withLabelType: RouteLabels.self)

counter.inc(12, .init(route: "/"))

Exporting

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.

By default, this should be accessible on your main serving port, at the /metrics endpoint. An example in Vapor syntax looks like:

router.get("/metrics") { request -> String in
    return myProm.collect()
}

Contributing

All contributions are most welcome!

If you think of some cool new feature that should be included, please create an issue. Or, if you want to implement it yourself, fork this repo and submit a PR!

If you find a bug or have issues, please create an issue 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.)

Github

link
Stars: 12
Help us keep the lights on

Releases

0.4.0-alpha.1 - Aug 27, 2019

Version 0.4.0 Alpha 1

This version provides backwards compatibility to NIO 1.x.x

1.0.0-alpha.3 - Aug 27, 2019

BREAKING: This release drops support for NIO 1.x. There will be a SwiftPrometheus version 0.x released soon for NIO 1.x soon.

Changes:

  • Transform PrometheusClient.collect to return a promise or take a callback. #12 (@MrLotU )

1.0.0-alpha.2 - Jul 13, 2019

Breaking changes:

  • Merge Prometheus and PrometheusMetrics into 1 target. https://github.com/MrLotU/SwiftPrometheus/pull/9 (@Yasumoto )
  • When using the swift-metrics APIs, Gauge.record() now calls PromGauge.set() instead of .add() https://github.com/MrLotU/SwiftPrometheus/commit/31d6964f7240125b07235a1f75e2601dbea74680 (@ktoso)

Other:

  • Updated doc comment typos.
  • Updated README

1.0.0-alpha.1 - Jul 5, 2019

Alpha 1 of SwiftPrometheus 1.0.0.

This includes an implementation of a standalone PrometheusClient and has support for using SwiftPrometheus with swift-metrics

0.3.0 - Apr 16, 2019

Includes fixes in regards to the new async API. Thanks @Yasumoto for #2!