Demonstration of an alternative Prometheus API

• API geared aimed at application developers rather than Prometheus experts.
• Name-based metrics; no need to create instances or handle registration.
• Cleaner timer / summary syntax, via resource/try
• Aim is to simplify Prometheus adoption, reduce excessive code intrusion.
• Lexical compatibility with Codahale/Dropwizard Metrics API, simplifying complete migration.
• Regular Prometheus API can always be used directly for more advanced cases (unclear what those might be).

Also @AlertRule API for defining alert rules in Java code and exporting rules files to disk (Prometheus 1.x format, or YAML for 2.x).

Example:

private final PrometheusMetrics metrics;

public void onUserLogin(Object event) {
    metrics.gauge("Sessions.open").inc();
    metrics.counter("Sessions.total").inc();
}

public String handleLogin() {
    try (Context timer = metrics.summary("Sessions.handleLogin").time()) {
        return "Login handled!";
    }
}

Features:

Application prefix:

Configure a common prefix...

@Value("${spring.application.name}")  // "MyApp"
private String prefixToUse;

@Bean
public PrometheusMetrics prometheusMetrics(CollectorRegistry collector) {
    return new PrometheusMetrics(collector, prefixToUse);
}

All created metrics will use that (normalised) prefix:

metrics.counter("counter_1").inc();
assertThat(samplesString(registry)).startsWith("[Name: myapp_counter_1 Type: COUNTER ");

---

Helpful descriptions:

Defaulted if not set:

metrics.timer("transaction");  // ==> "transaction"

metrics.timer("transaction", "Transaction time");  // ==> "Transaction time"

Alternatively, load a Java Properties file like:

transaction = Transaction time

when you create your PrometheusMetrics object, e.g.

final Properties props = new Properties();
try (Reader r = Files.newReader( new File("descriptions.properties"), Charsets.UTF_8)) {
    props.load(r);
}

metrics.setDescriptionMappings(props);

Now you can use the simpler API:

metrics.timer("transaction");  // ==> "Transaction time"

---

More helpful summary quantiles:

By default, summaries will get the following percentiles, rather than a simple median:

50%, 75%, 90%, 95%, 99%, 99.9%

---

Error counts implemented via labels:

metrics.error("salesforce");

assertThat(registry.getSampleValue("myapp_errors", \
                                    new String[]{"error_type"}, \
                                    new String[]{"salesforce"})).isEqualTo(1.0d);
// ...

metrics.error("transaction");

assertThat(registry.getSampleValue("myapp_errors", \
                                    new String[]{"error_type"}, \
                                    new String[]{"transaction"})).isEqualTo(1.0d);

---

All names sanitised to ensure no invalid characters

• All names lowercased
• ., -, #, seamlessly mapped to _