Skip to content
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

Jump to bottom

Add a wrapper to add a timestamp to a metric #443

Merged
merged 2 commits into from
Aug 21, 2018
Merged

Add a wrapper to add a timestamp to a metric #443

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
5240f7e
Add a wrapper to add a timestamp to a metric
Aug 18, 2018
abaece0
Fix import grouping
Aug 18, 2018
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
38 changes: 36 additions & 2 deletions prometheus/examples_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,12 @@ import (
"runtime"
"sort"
"strings"
"time"

dto "github.com/prometheus/client_model/go"
"github.com/golang/protobuf/proto"
"github.com/prometheus/common/expfmt"

"github.com/golang/protobuf/proto"
dto "github.com/prometheus/client_model/go"

"github.com/prometheus/client_golang/prometheus"
)
Expand Down Expand Up @@ -751,3 +752,36 @@ temperature_kelvin 4.5
// temperature_kelvin{location="inside"} 298.44
// temperature_kelvin{location="outside"} 273.14
}

func ExampleNewMetricWithTimestamp() {
desc := prometheus.NewDesc(
"temperature_kelvin",
"Current temperature in Kelvin.",
nil, nil,
)

// Create a constant gauge from values we got from an external
// temperature reporting system. Those values are reported with a slight
// delay, so we want to add the timestamp of the actual measurement.
temperatureReportedByExternalSystem := 298.15
timeReportedByExternalSystem := time.Date(2009, time.November, 10, 23, 0, 0, 12345678, time.UTC)
s := prometheus.NewMetricWithTimestamp(
timeReportedByExternalSystem,
prometheus.MustNewConstMetric(
desc, prometheus.GaugeValue, temperatureReportedByExternalSystem,
),
)

// Just for demonstration, let's check the state of the gauge by
// (ab)using its Write method (which is usually only used by Prometheus
// internally).
metric := &dto.Metric{}
s.Write(metric)
fmt.Println(proto.MarshalTextString(metric))

// Output:
// gauge: <
// value: 298.15
// >
// timestamp_ms: 1257894000012
}
31 changes: 31 additions & 0 deletions prometheus/metric.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@ package prometheus

import (
"strings"
"time"

"github.com/gogo/protobuf/proto"

dto "github.com/prometheus/client_model/go"
)
Expand Down Expand Up @@ -142,3 +145,31 @@ func NewInvalidMetric(desc *Desc, err error) Metric {
func (m *invalidMetric) Desc() *Desc { return m.desc }

func (m *invalidMetric) Write(*dto.Metric) error { return m.err }

type timestampedMetric struct {
Metric
t time.Time
}

func (m timestampedMetric) Write(pb *dto.Metric) error {
e := m.Metric.Write(pb)
pb.TimestampMs = proto.Int64(m.t.Unix()*1000 + int64(m.t.Nanosecond()/1000000))
Copy link

Choose a reason for hiding this comment

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

Probably does not make a difference, but I’d return early in case of an error

Copy link
Member Author

Choose a reason for hiding this comment

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

Somehow my comment here got lost.

It probably really doesn't make a difference, but I find it a bit more robust to set the timestamp even in case of an error. We don't explicitly document to not make any use of the protomessage after an error is returned, so there might be a future use where the error conveys some message that looking at the proto message still makes sense.

Right now, of course, nobody should ever look at the proto message after an error, but then it doesn't matter if we set the timestamp or not.

return e
}

// NewMetricWithTimestamp returns a new Metric wrapping the provided Metric in a
Copy link
Contributor

Choose a reason for hiding this comment

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

This sounds like it works with direct instrumenation, I think we should try to limit this to MustNewConstMetric. Everyone I've seen trying to do timestamps on direct instrumentation was otherwise using the library incorrectly.

Copy link
Member Author

Choose a reason for hiding this comment

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

The usual use case is already described in the doc comment. Artificially limiting this to the output of MustNewConstMetric (and MustNewConstSummary and MustNewConstHistogram and NewConstMetric and NewConstSummary and NewConstHistogram) would be weird and cumbersome. Using this wrapper is arcane enough to not happen accidentally. Whoever elects to use such a contraption without reading the doc comments is on their own.

Copy link
Member Author

Choose a reason for hiding this comment

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

Additional point: Since the timestamp is immutable, people that incorrectly wrap metrics from direct instrumentation will quickly notice that they are exposing the same timestamp forever.

Copy link
Contributor

Choose a reason for hiding this comment

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

That's true.

// way that it has an explicit timestamp set to the provided Time. This is only
// useful in rare cases as the timestamp of a Prometheus metric should usually
// be set by the Prometheus server during scraping. Exceptions include mirroring
// metrics with given timestamps from other metric
// sources.
//
// NewMetricWithTimestamp works best with MustNewConstMetric,
// MustNewConstHistogram, and MustNewConstSummary, see example.
//
// Currently, the exposition formats used by Prometheus are limited to
// millisecond resolution. Thus, the provided time will be rounded down to the
// next full millisecond value.
func NewMetricWithTimestamp(t time.Time, m Metric) Metric {
return timestampedMetric{Metric: m, t: t}
}