Skip to content

Exemplar API sketch #641

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Exemplar API sketch #641

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e9cfb59
WIP exemplar API
fitzoh Mar 17, 2021
04a3bde
add @throws clause and fix punctuation
fitzoh Mar 17, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions simpleclient/src/main/java/io/prometheus/client/Counter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@
import java.util.List;
import java.util.Map;

import sun.reflect.generics.reflectiveObjects.NotImplementedException;

/**
* Counter metric, to track counts of events or running totals.
* <p>
Expand Down Expand Up @@ -135,6 +137,24 @@ public void inc(double amt) {
}
value.add(amt);
}
/**
* Increment the counter by given amount and update the exemplar for the series.
*
* @param amt the amount to increment the counter by
* @param exemplarLabels a set of key value pairs used to create the exemplar
*
* @throws IllegalArgumentException If amt is negative.
* @throws IllegalArgumentException if exemplarLabels is null.
* @throws IllegalArgumentException if exemplarLabels does not contain an even number of values.
* @throws IllegalArgumentException if exemplarLabels contains any invalid labels.
* @throws IllegalArgumentException if the combined length of the exemplarLabels is greater than 64.
*/
Comment on lines +140 to +151
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Initial golang documentation that I can probably borrow from a little more heavily:
https://github.com/prometheus/client_golang/blob/c32ffd121f40843d8ce747536467bb091678fd87/prometheus/counter.go#L44-L51

There were two things I wanted to point out here.

Do we want to copy the go behavior of ignoring null labels?
I'm inclined to say that null labels are invalid and that the user should use inc instead.

Exceptions for invalid labels scare me a bit as well. Having instrumentation code throw an exception because your dynamically generated label ended up a little too long sounds like a not fun user experience, but I don't have a better alternative other than logging an error or incrementing an internal error counter.

public void incWithExemplar(double amt, String... exemplarLabels){
//TODO exemplar label validation
inc(amt);
//TODO update exemplar
throw new NotImplementedException();
}
/**
* Get the value of the counter.
*/
Expand Down Expand Up @@ -163,6 +183,12 @@ public void inc() {
public void inc(double amt) {
noLabelsChild.inc(amt);
}
/**
*
*/
public void incWithExemplar(double amt, String... exemplarLabels){
noLabelsChild.incWithExemplar(amt, exemplarLabels);
}

/**
* Get the value of the counter.
Expand Down
25 changes: 25 additions & 0 deletions simpleclient/src/main/java/io/prometheus/client/Histogram.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@
import java.util.Map;
import java.util.concurrent.Callable;

import sun.reflect.generics.reflectiveObjects.NotImplementedException;

/**
* Histogram metric, to track distributions of events.
* <p>
Expand Down Expand Up @@ -266,6 +268,23 @@ public void observe(double amt) {
}
sum.add(amt);
}
/**
* Observe the given amount and update the exemplar for the bucket.
*
* @param amt the amount to observe
* @param exemplarLabels a set of key value pairs used to create the exemplar
*
* @throws IllegalArgumentException if exemplarLabels is null.
* @throws IllegalArgumentException if exemplarLabels does not contain an even number of values.
* @throws IllegalArgumentException if exemplarLabels contains any invalid labels.
* @throws IllegalArgumentException if the combined length of the exemplarLabels is greater than 64.
*/
public void observeWithExemplar(double amt, String... exemplarLabels) {
//TODO exemplar label validation
observe(amt);
//TODO update exemplar
throw new NotImplementedException();
}
/**
* Start a timer to track a duration.
* <p>
Expand Down Expand Up @@ -297,6 +316,12 @@ public Value get() {
public void observe(double amt) {
noLabelsChild.observe(amt);
}
/**
*
*/
public void observeWithExemplar(double amt, String... exemplarLabels) {
noLabelsChild.observeWithExemplar(amt, exemplarLabels);
}
/**
* Start a timer to track a duration on the histogram with no labels.
* <p>
Expand Down