Prometheus.jl

Introduction

This package is a Julia client for Prometheus. If you are not familiar with Prometheus it is recommended to browse the upstream documentation. The documentation here focuses on the Julia client.

Two of the basic concepts of a Prometheus client are Registries and Collectors. Registries are collections of collectors, and the collectors are the units responsible to record and capture metrics. Client libraries implement a default registry which all collectors implicity register with, so for basic usage there is no need to interact with a registry (see Default registry).

The third important concept is Exposition of the collected metrics. Typically metrics are exposed over a HTTP server, as in the Quickstart-example just below. See the section about Exposition for more details and examples on how metrics can be exposed.

Quickstart

Install Prometheus.jl and HTTP.jl using the package manager:
```
pkg> add Prometheus HTTP
```

Paste the following code into a Julia REPL.

# Load the packages
using Prometheus, HTTP

# Create a Counter metric
const request_counter = Prometheus.Counter("request_count", "Number of handled requests")

# Start a HTTP server on localhost port 8000 to server the metrics
server = HTTP.listen!(8000) do http
    Prometheus.inc(request_counter) # Increment the request counter
    return Prometheus.expose(http)  # Expose the metrics
end

Visit http://localhost:8000 in your browser. You will see something like the following
```
# HELP gc_alloc_bytes_total Total number of allocated bytes
# TYPE gc_alloc_bytes_total counter
gc_alloc_bytes_total 365578814

[...]

# HELP request_count Number of handled requests
# TYPE request_count counter
request_count 1
```
The output contains some default metrics related to the running process, as well as the request counter that we added ourselves. Every time you refresh, the counter will increment its value. close(server) will shutdown the server.

Collectors

This section documents the collectors that are currently supported. This include the "basic" collectors (Counter, Gauge, Histogram, Summary) as well as some custom collectors (GCCollector, ProcessCollector). There is also a section on how to implement your own collector, see Custom collectors.

Upstream documentation:

Counter

Quoting the upstream documentation:

A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart. For example, you can use a counter to represent the number of requests served, tasks completed, or errors.
Do not use a counter to expose a value that can decrease. For example, do not use a counter for the number of currently running processes; instead use a gauge.

Counter API reference

Prometheus.Counter — Method

Prometheus.Counter(name, help; registry=DEFAULT_REGISTRY)

Construct a Counter collector.

Arguments

name :: String: the name of the counter metric.
help :: String: the documentation for the counter metric.

Keyword arguments

registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. If not specified the default registry is used. Pass registry = nothing to skip registration.

Methods

Prometheus.inc: increment the counter.