• Stars
    star
    144
  • Rank 255,590 (Top 6 %)
  • Language
    Swift
  • License
    Apache License 2.0
  • Created almost 6 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Prometheus client library for Swift

Swift 5.2

SwiftPrometheus, Prometheus client for Swift

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

Installation

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

.package(url: "https://github.com/swift-server-community/SwiftPrometheus.git", from: "1.0.2")

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.

Starting with SwiftPrometheus 1.0.0-alpha.10 MetricsSystem is no longer directly configured with a PrometheusClient.

Instead, create a PrometheusMetricsFactory instance wrapping a PrometheusClient.

let myProm = PrometheusClient()
MetricsSystem.bootstrap(PrometheusMetricsFactory(client: myProm))

Along with a PrometheusClient, PrometheusMetricsFactory can take a Configuration object setting the following properties:

  • A LabelSanitizer used to sanitize metric names to valid Prometheus values. A default implementation is provided.
  • 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.
  • Default buckets for use by aggregating swift-metrics Recorder instances.

Before Alpha 10

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. Labels are passed when recording values to your metric as an instance of DimensionLabels, or as an array of (String, String).

Example with a counter:

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

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

counter.inc(12, .init([("route", "/users")]))
// OR
counter.inc(12, [("route", "/users")])

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 4 syntax looks like:

app.get("metrics") { req async throws -> String in
    return try await MetricsSystem.prometheus().collect()
}

Security

Please see SECURITY.md for details on the security process.

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.)

More Repositories

1

swift-aws-lambda-runtime

Swift implementation of AWS Lambda Runtime
Swift
1,132
star
2

async-http-client

HTTP client library built on SwiftNIO
Swift
917
star
3

http

⚠️ Historical HTTP API - please use https://github.com/swift-server/async-http-client instead
Swift
703
star
4

vscode-swift

Visual Studio Code Extension for Swift
TypeScript
622
star
5

swift-service-lifecycle

Cleanly startup and shutdown server application, freeing resources in order before exiting.
Swift
395
star
6

work-group

⚠️ Historical workgroup organisation
352
star
7

swiftly

A Swift toolchain installer and manager, written in Swift.
Swift
337
star
8

swift-backtrace

💥 Backtraces for Swift on Linux and Windows
C
295
star
9

guides

Guides for building, debugging and deploying Swift Server applications
258
star
10

sswg

Swift Server Working Group (SSWG)
181
star
11

RediStack

Non-blocking, event-driven Swift client for Redis.
Swift
142
star
12

swift-webauthn

A Swift library for implementing the WebAuthn spec
Swift
127
star
13

swift-openapi-vapor

Vapor Bindings for the OpenAPI Generator
Swift
79
star
14

swift-kafka-client

Swift
77
star
15

swift-devcontainer-template

Visual Studio Code Development Container for Swift
Shell
54
star
16

swift-openapi-async-http-client

AsyncHTTPClient transport for Swift OpenAPI Generator.
Swift
54
star
17

security

⚠️ Historical TLS API - please use SwiftNIO instead
Swift
49
star
18

swift-aws-lambda-events

Swift implementation of AWS Lambda Events
Swift
48
star
19

swift-openapi-hummingbird

Hummingbird transport for OpenAPI generator
Shell
27
star
20

swift-memcache-gsoc

Swift
15
star
21

sswg-collection

Dockerfile
11
star
22

swift-openapi-lambda

An AWS Lambda transport for Swift OpenAPI
Swift
8
star
23

swift-service-cache

caches for swift services
6
star
24

swift-etcd-client-gsoc

Swift
5
star