prometheus: Prometheus Haskell Client

[ bsd3, library, metrics, monitoring, system, web ] [ Propose Tags ] [ Report a vulnerability ]
Prometheus Haskell Client

A simple and modern, type safe, performance focused, idiomatic Haskell client for Prometheus monitoring. Specifically there is no use of unsafe IO or manual ByteString construction from lists of bytes. Batteries-included web server.

A key design element of this library is that the RegistryT monad transformer is only required for registering new time series. Once the time series is registered, new data samples may just be added in the IO monad.

Note: Version 0.* supports Prometheus v1.0 and version 2.* supports Prometheus v2.0.

Usage Example
module Example where

import           Control.Monad.IO.Class                         (liftIO)
import           System.Metrics.Prometheus.Http.Scrape          (serveMetricsT)
import           System.Metrics.Prometheus.Concurrent.RegistryT
import           System.Metrics.Prometheus.Metric.Counter       (inc)
import           System.Metrics.Prometheus.MetricId

main :: IO ()
main = runRegistryT $ do
    -- Labels can be defined as lists or added to an empty label set
    connectSuccessGauge <- registerGauge "example_connections" (fromList [("login", "success")])
    connectFailureGauge <- registerGauge "example_connections" (addLabel "login" "failure" mempty)
    connectCounter <- registerCounter "example_connection_total" mempty
    latencyHistogram <- registerHistogram "example_round_trip_latency_ms" mempty [10, 20..100]

    liftIO $ inc connectCounter -- increment a counter

    -- [...] pass metric handles to the rest of the app

    serveMetricsT 8080 ["metrics"] -- http://localhost:8080/metric server
Advanced Usage

A Registry and StateT-based RegistryT are available for unit testing or generating lists of `[IO a]` actions that can be sequenced and returned from pure code to be applied.


[Skip to Readme]

Flags

Automatic Flags
NameDescriptionDefault
buildexamples

Build the Example.hs file. This is normally only used for testing.

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.1.0.3, 0.1.1, 0.2.0, 0.3.0, 0.3.1, 0.3.2, 0.3.2.1, 0.4.0, 0.4.1, 0.4.2, 0.5.0, 2.0.0, 2.0.1, 2.0.2, 2.1.0, 2.1.1, 2.1.2, 2.1.3, 2.2.1, 2.2.2, 2.2.3, 2.2.4, 2.3.0
Dependencies atomic-primops (>=0.8 && <0.9), base (>=4.9 && <5), bytestring (>=0.10 && <0.13), containers (>=0.5 && <0.8), http-client (>=0.4 && <0.8), http-client-tls (>=0.3 && <0.4), http-types (>=0.8 && <0.13), network-uri (>=2.5 && <2.7), prometheus, text (>=1.2 && <2.2), transformers (>=0.4 && <0.7), wai (>=3.2 && <3.3), warp (>=3.2 && <3.5) [details]
License BSD-3-Clause
Copyright Bitnomial, Inc. (c) 2016-2023
Author Luke Hoersten
Maintainer luke@bitnomial.com, opensource@bitnomial.com
Category Metrics, Monitoring, Web, System
Home page http://github.com/bitnomial/prometheus
Bug tracker http://github.com/bitnomial/prometheus/issues
Source repo head: git clone https://github.com/bitnomial/prometheus
Uploaded by wraithm at 2024-08-07T17:50:14Z
Distributions LTSHaskell:2.3.0, NixOS:2.2.4, Stackage:2.3.0
Reverse Dependencies 5 direct, 1 indirect [details]
Executables prometheus-example
Downloads 24186 total (216 in the last 30 days)
Rating 2.25 (votes: 2) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-08-07 [all 1 reports]

Readme for prometheus-2.3.0

[back to package description]

Prometheus Haskell Client

Build Status Hackage

A simple and modern, type safe, performance focused, idiomatic Haskell client for Prometheus monitoring. Specifically there is no use of unsafe IO or manual ByteString construction from lists of bytes. Batteries-included web server.

A key design element of this library is that the RegistryT monad transformer is only required for registering new time series. Once the time series is registered, new data samples may just be added in the IO monad.

Note: Version 0.* supports Prometheus v1.0 and version 2.* supports Prometheus v2.0.

Usage Example

{-# LANGUAGE OverloadedStrings #-}

module Example where

import           Control.Monad.IO.Class                         (liftIO)
import           System.Metrics.Prometheus.Http.Scrape          (serveMetricsT)
import           System.Metrics.Prometheus.Concurrent.RegistryT
import           System.Metrics.Prometheus.Metric.Counter       (inc)
import           System.Metrics.Prometheus.MetricId

main :: IO ()
main = runRegistryT $ do
    -- Labels can be defined as lists or added to an empty label set
    connectSuccessGauge <- registerGauge "example_connections" (fromList [("login", "success")])
    connectFailureGauge <- registerGauge "example_connections" (addLabel "login" "failure" mempty)
    connectCounter <- registerCounter "example_connection_total" mempty
    latencyHistogram <- registerHistogram "example_round_trip_latency_ms" mempty [10, 20..100]

    liftIO $ inc connectCounter -- increment a counter

    -- [...] pass metric handles to the rest of the app

    serveMetricsT 8080 ["metrics"] -- http://localhost:8080/metrics server

Advanced Usage

A Registry and StateT-based RegistryT are available for unit testing or generating lists of [IO a] actions that can be sequenced and returned from pure code to be applied.

Concurrency Model

Metrics are "values" and the Registry is the map of "name_labels" to metric "keys".

Metrics may be created/registered at any point, not just at start up, in the RegistryT monad transformer. Thread the RegistryT through your transformer stack to tell the type system you intend to register new metrics in that call stack. The RegistryT has a thread safe version in the Concurrent module.

The metrics are thread safe on their own and do not require locking the entire registry to update them. They use high performance check-and-set atomic primitives. This is because metrics may be updated many times in between scrapes where the Reigstry needs to be lock. You do NOT want to lock all the metrics just to update one.

The scraping operation of the server to collect all the metrics locks the registry to ensure no new metrics are being created/keyed in a race with the scrape.

Tasks

  • Implement help docstrings.
  • Implement GHC-specific metrics.
  • Implement summary metric.
  • Encode name and labels on register.
  • Implement ReaderT for Concurrent Registry.
  • Library documentation and example.
  • Name and label validation