histogram.go 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637
  1. // Copyright 2015 The Prometheus Authors
  2. // Licensed under the Apache License, Version 2.0 (the "License");
  3. // you may not use this file except in compliance with the License.
  4. // You may obtain a copy of the License at
  5. //
  6. // http://www.apache.org/licenses/LICENSE-2.0
  7. //
  8. // Unless required by applicable law or agreed to in writing, software
  9. // distributed under the License is distributed on an "AS IS" BASIS,
  10. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11. // See the License for the specific language governing permissions and
  12. // limitations under the License.
  13. package prometheus
  14. import (
  15. "fmt"
  16. "math"
  17. "runtime"
  18. "sort"
  19. "sync"
  20. "sync/atomic"
  21. "time"
  22. //lint:ignore SA1019 Need to keep deprecated package for compatibility.
  23. "github.com/golang/protobuf/proto"
  24. dto "github.com/prometheus/client_model/go"
  25. )
  26. // A Histogram counts individual observations from an event or sample stream in
  27. // configurable buckets. Similar to a summary, it also provides a sum of
  28. // observations and an observation count.
  29. //
  30. // On the Prometheus server, quantiles can be calculated from a Histogram using
  31. // the histogram_quantile function in the query language.
  32. //
  33. // Note that Histograms, in contrast to Summaries, can be aggregated with the
  34. // Prometheus query language (see the documentation for detailed
  35. // procedures). However, Histograms require the user to pre-define suitable
  36. // buckets, and they are in general less accurate. The Observe method of a
  37. // Histogram has a very low performance overhead in comparison with the Observe
  38. // method of a Summary.
  39. //
  40. // To create Histogram instances, use NewHistogram.
  41. type Histogram interface {
  42. Metric
  43. Collector
  44. // Observe adds a single observation to the histogram.
  45. Observe(float64)
  46. }
  47. // bucketLabel is used for the label that defines the upper bound of a
  48. // bucket of a histogram ("le" -> "less or equal").
  49. const bucketLabel = "le"
  50. // DefBuckets are the default Histogram buckets. The default buckets are
  51. // tailored to broadly measure the response time (in seconds) of a network
  52. // service. Most likely, however, you will be required to define buckets
  53. // customized to your use case.
  54. var (
  55. DefBuckets = []float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10}
  56. errBucketLabelNotAllowed = fmt.Errorf(
  57. "%q is not allowed as label name in histograms", bucketLabel,
  58. )
  59. )
  60. // LinearBuckets creates 'count' buckets, each 'width' wide, where the lowest
  61. // bucket has an upper bound of 'start'. The final +Inf bucket is not counted
  62. // and not included in the returned slice. The returned slice is meant to be
  63. // used for the Buckets field of HistogramOpts.
  64. //
  65. // The function panics if 'count' is zero or negative.
  66. func LinearBuckets(start, width float64, count int) []float64 {
  67. if count < 1 {
  68. panic("LinearBuckets needs a positive count")
  69. }
  70. buckets := make([]float64, count)
  71. for i := range buckets {
  72. buckets[i] = start
  73. start += width
  74. }
  75. return buckets
  76. }
  77. // ExponentialBuckets creates 'count' buckets, where the lowest bucket has an
  78. // upper bound of 'start' and each following bucket's upper bound is 'factor'
  79. // times the previous bucket's upper bound. The final +Inf bucket is not counted
  80. // and not included in the returned slice. The returned slice is meant to be
  81. // used for the Buckets field of HistogramOpts.
  82. //
  83. // The function panics if 'count' is 0 or negative, if 'start' is 0 or negative,
  84. // or if 'factor' is less than or equal 1.
  85. func ExponentialBuckets(start, factor float64, count int) []float64 {
  86. if count < 1 {
  87. panic("ExponentialBuckets needs a positive count")
  88. }
  89. if start <= 0 {
  90. panic("ExponentialBuckets needs a positive start value")
  91. }
  92. if factor <= 1 {
  93. panic("ExponentialBuckets needs a factor greater than 1")
  94. }
  95. buckets := make([]float64, count)
  96. for i := range buckets {
  97. buckets[i] = start
  98. start *= factor
  99. }
  100. return buckets
  101. }
  102. // HistogramOpts bundles the options for creating a Histogram metric. It is
  103. // mandatory to set Name to a non-empty string. All other fields are optional
  104. // and can safely be left at their zero value, although it is strongly
  105. // encouraged to set a Help string.
  106. type HistogramOpts struct {
  107. // Namespace, Subsystem, and Name are components of the fully-qualified
  108. // name of the Histogram (created by joining these components with
  109. // "_"). Only Name is mandatory, the others merely help structuring the
  110. // name. Note that the fully-qualified name of the Histogram must be a
  111. // valid Prometheus metric name.
  112. Namespace string
  113. Subsystem string
  114. Name string
  115. // Help provides information about this Histogram.
  116. //
  117. // Metrics with the same fully-qualified name must have the same Help
  118. // string.
  119. Help string
  120. // ConstLabels are used to attach fixed labels to this metric. Metrics
  121. // with the same fully-qualified name must have the same label names in
  122. // their ConstLabels.
  123. //
  124. // ConstLabels are only used rarely. In particular, do not use them to
  125. // attach the same labels to all your metrics. Those use cases are
  126. // better covered by target labels set by the scraping Prometheus
  127. // server, or by one specific metric (e.g. a build_info or a
  128. // machine_role metric). See also
  129. // https://prometheus.io/docs/instrumenting/writing_exporters/#target-labels-not-static-scraped-labels
  130. ConstLabels Labels
  131. // Buckets defines the buckets into which observations are counted. Each
  132. // element in the slice is the upper inclusive bound of a bucket. The
  133. // values must be sorted in strictly increasing order. There is no need
  134. // to add a highest bucket with +Inf bound, it will be added
  135. // implicitly. The default value is DefBuckets.
  136. Buckets []float64
  137. }
  138. // NewHistogram creates a new Histogram based on the provided HistogramOpts. It
  139. // panics if the buckets in HistogramOpts are not in strictly increasing order.
  140. //
  141. // The returned implementation also implements ExemplarObserver. It is safe to
  142. // perform the corresponding type assertion. Exemplars are tracked separately
  143. // for each bucket.
  144. func NewHistogram(opts HistogramOpts) Histogram {
  145. return newHistogram(
  146. NewDesc(
  147. BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
  148. opts.Help,
  149. nil,
  150. opts.ConstLabels,
  151. ),
  152. opts,
  153. )
  154. }
  155. func newHistogram(desc *Desc, opts HistogramOpts, labelValues ...string) Histogram {
  156. if len(desc.variableLabels) != len(labelValues) {
  157. panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels, labelValues))
  158. }
  159. for _, n := range desc.variableLabels {
  160. if n == bucketLabel {
  161. panic(errBucketLabelNotAllowed)
  162. }
  163. }
  164. for _, lp := range desc.constLabelPairs {
  165. if lp.GetName() == bucketLabel {
  166. panic(errBucketLabelNotAllowed)
  167. }
  168. }
  169. if len(opts.Buckets) == 0 {
  170. opts.Buckets = DefBuckets
  171. }
  172. h := &histogram{
  173. desc: desc,
  174. upperBounds: opts.Buckets,
  175. labelPairs: makeLabelPairs(desc, labelValues),
  176. counts: [2]*histogramCounts{{}, {}},
  177. now: time.Now,
  178. }
  179. for i, upperBound := range h.upperBounds {
  180. if i < len(h.upperBounds)-1 {
  181. if upperBound >= h.upperBounds[i+1] {
  182. panic(fmt.Errorf(
  183. "histogram buckets must be in increasing order: %f >= %f",
  184. upperBound, h.upperBounds[i+1],
  185. ))
  186. }
  187. } else {
  188. if math.IsInf(upperBound, +1) {
  189. // The +Inf bucket is implicit. Remove it here.
  190. h.upperBounds = h.upperBounds[:i]
  191. }
  192. }
  193. }
  194. // Finally we know the final length of h.upperBounds and can make buckets
  195. // for both counts as well as exemplars:
  196. h.counts[0].buckets = make([]uint64, len(h.upperBounds))
  197. h.counts[1].buckets = make([]uint64, len(h.upperBounds))
  198. h.exemplars = make([]atomic.Value, len(h.upperBounds)+1)
  199. h.init(h) // Init self-collection.
  200. return h
  201. }
  202. type histogramCounts struct {
  203. // sumBits contains the bits of the float64 representing the sum of all
  204. // observations. sumBits and count have to go first in the struct to
  205. // guarantee alignment for atomic operations.
  206. // http://golang.org/pkg/sync/atomic/#pkg-note-BUG
  207. sumBits uint64
  208. count uint64
  209. buckets []uint64
  210. }
  211. type histogram struct {
  212. // countAndHotIdx enables lock-free writes with use of atomic updates.
  213. // The most significant bit is the hot index [0 or 1] of the count field
  214. // below. Observe calls update the hot one. All remaining bits count the
  215. // number of Observe calls. Observe starts by incrementing this counter,
  216. // and finish by incrementing the count field in the respective
  217. // histogramCounts, as a marker for completion.
  218. //
  219. // Calls of the Write method (which are non-mutating reads from the
  220. // perspective of the histogram) swap the hot–cold under the writeMtx
  221. // lock. A cooldown is awaited (while locked) by comparing the number of
  222. // observations with the initiation count. Once they match, then the
  223. // last observation on the now cool one has completed. All cool fields must
  224. // be merged into the new hot before releasing writeMtx.
  225. //
  226. // Fields with atomic access first! See alignment constraint:
  227. // http://golang.org/pkg/sync/atomic/#pkg-note-BUG
  228. countAndHotIdx uint64
  229. selfCollector
  230. desc *Desc
  231. writeMtx sync.Mutex // Only used in the Write method.
  232. // Two counts, one is "hot" for lock-free observations, the other is
  233. // "cold" for writing out a dto.Metric. It has to be an array of
  234. // pointers to guarantee 64bit alignment of the histogramCounts, see
  235. // http://golang.org/pkg/sync/atomic/#pkg-note-BUG.
  236. counts [2]*histogramCounts
  237. upperBounds []float64
  238. labelPairs []*dto.LabelPair
  239. exemplars []atomic.Value // One more than buckets (to include +Inf), each a *dto.Exemplar.
  240. now func() time.Time // To mock out time.Now() for testing.
  241. }
  242. func (h *histogram) Desc() *Desc {
  243. return h.desc
  244. }
  245. func (h *histogram) Observe(v float64) {
  246. h.observe(v, h.findBucket(v))
  247. }
  248. func (h *histogram) ObserveWithExemplar(v float64, e Labels) {
  249. i := h.findBucket(v)
  250. h.observe(v, i)
  251. h.updateExemplar(v, i, e)
  252. }
  253. func (h *histogram) Write(out *dto.Metric) error {
  254. // For simplicity, we protect this whole method by a mutex. It is not in
  255. // the hot path, i.e. Observe is called much more often than Write. The
  256. // complication of making Write lock-free isn't worth it, if possible at
  257. // all.
  258. h.writeMtx.Lock()
  259. defer h.writeMtx.Unlock()
  260. // Adding 1<<63 switches the hot index (from 0 to 1 or from 1 to 0)
  261. // without touching the count bits. See the struct comments for a full
  262. // description of the algorithm.
  263. n := atomic.AddUint64(&h.countAndHotIdx, 1<<63)
  264. // count is contained unchanged in the lower 63 bits.
  265. count := n & ((1 << 63) - 1)
  266. // The most significant bit tells us which counts is hot. The complement
  267. // is thus the cold one.
  268. hotCounts := h.counts[n>>63]
  269. coldCounts := h.counts[(^n)>>63]
  270. // Await cooldown.
  271. for count != atomic.LoadUint64(&coldCounts.count) {
  272. runtime.Gosched() // Let observations get work done.
  273. }
  274. his := &dto.Histogram{
  275. Bucket: make([]*dto.Bucket, len(h.upperBounds)),
  276. SampleCount: proto.Uint64(count),
  277. SampleSum: proto.Float64(math.Float64frombits(atomic.LoadUint64(&coldCounts.sumBits))),
  278. }
  279. var cumCount uint64
  280. for i, upperBound := range h.upperBounds {
  281. cumCount += atomic.LoadUint64(&coldCounts.buckets[i])
  282. his.Bucket[i] = &dto.Bucket{
  283. CumulativeCount: proto.Uint64(cumCount),
  284. UpperBound: proto.Float64(upperBound),
  285. }
  286. if e := h.exemplars[i].Load(); e != nil {
  287. his.Bucket[i].Exemplar = e.(*dto.Exemplar)
  288. }
  289. }
  290. // If there is an exemplar for the +Inf bucket, we have to add that bucket explicitly.
  291. if e := h.exemplars[len(h.upperBounds)].Load(); e != nil {
  292. b := &dto.Bucket{
  293. CumulativeCount: proto.Uint64(count),
  294. UpperBound: proto.Float64(math.Inf(1)),
  295. Exemplar: e.(*dto.Exemplar),
  296. }
  297. his.Bucket = append(his.Bucket, b)
  298. }
  299. out.Histogram = his
  300. out.Label = h.labelPairs
  301. // Finally add all the cold counts to the new hot counts and reset the cold counts.
  302. atomic.AddUint64(&hotCounts.count, count)
  303. atomic.StoreUint64(&coldCounts.count, 0)
  304. for {
  305. oldBits := atomic.LoadUint64(&hotCounts.sumBits)
  306. newBits := math.Float64bits(math.Float64frombits(oldBits) + his.GetSampleSum())
  307. if atomic.CompareAndSwapUint64(&hotCounts.sumBits, oldBits, newBits) {
  308. atomic.StoreUint64(&coldCounts.sumBits, 0)
  309. break
  310. }
  311. }
  312. for i := range h.upperBounds {
  313. atomic.AddUint64(&hotCounts.buckets[i], atomic.LoadUint64(&coldCounts.buckets[i]))
  314. atomic.StoreUint64(&coldCounts.buckets[i], 0)
  315. }
  316. return nil
  317. }
  318. // findBucket returns the index of the bucket for the provided value, or
  319. // len(h.upperBounds) for the +Inf bucket.
  320. func (h *histogram) findBucket(v float64) int {
  321. // TODO(beorn7): For small numbers of buckets (<30), a linear search is
  322. // slightly faster than the binary search. If we really care, we could
  323. // switch from one search strategy to the other depending on the number
  324. // of buckets.
  325. //
  326. // Microbenchmarks (BenchmarkHistogramNoLabels):
  327. // 11 buckets: 38.3 ns/op linear - binary 48.7 ns/op
  328. // 100 buckets: 78.1 ns/op linear - binary 54.9 ns/op
  329. // 300 buckets: 154 ns/op linear - binary 61.6 ns/op
  330. return sort.SearchFloat64s(h.upperBounds, v)
  331. }
  332. // observe is the implementation for Observe without the findBucket part.
  333. func (h *histogram) observe(v float64, bucket int) {
  334. // We increment h.countAndHotIdx so that the counter in the lower
  335. // 63 bits gets incremented. At the same time, we get the new value
  336. // back, which we can use to find the currently-hot counts.
  337. n := atomic.AddUint64(&h.countAndHotIdx, 1)
  338. hotCounts := h.counts[n>>63]
  339. if bucket < len(h.upperBounds) {
  340. atomic.AddUint64(&hotCounts.buckets[bucket], 1)
  341. }
  342. for {
  343. oldBits := atomic.LoadUint64(&hotCounts.sumBits)
  344. newBits := math.Float64bits(math.Float64frombits(oldBits) + v)
  345. if atomic.CompareAndSwapUint64(&hotCounts.sumBits, oldBits, newBits) {
  346. break
  347. }
  348. }
  349. // Increment count last as we take it as a signal that the observation
  350. // is complete.
  351. atomic.AddUint64(&hotCounts.count, 1)
  352. }
  353. // updateExemplar replaces the exemplar for the provided bucket. With empty
  354. // labels, it's a no-op. It panics if any of the labels is invalid.
  355. func (h *histogram) updateExemplar(v float64, bucket int, l Labels) {
  356. if l == nil {
  357. return
  358. }
  359. e, err := newExemplar(v, h.now(), l)
  360. if err != nil {
  361. panic(err)
  362. }
  363. h.exemplars[bucket].Store(e)
  364. }
  365. // HistogramVec is a Collector that bundles a set of Histograms that all share the
  366. // same Desc, but have different values for their variable labels. This is used
  367. // if you want to count the same thing partitioned by various dimensions
  368. // (e.g. HTTP request latencies, partitioned by status code and method). Create
  369. // instances with NewHistogramVec.
  370. type HistogramVec struct {
  371. *metricVec
  372. }
  373. // NewHistogramVec creates a new HistogramVec based on the provided HistogramOpts and
  374. // partitioned by the given label names.
  375. func NewHistogramVec(opts HistogramOpts, labelNames []string) *HistogramVec {
  376. desc := NewDesc(
  377. BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
  378. opts.Help,
  379. labelNames,
  380. opts.ConstLabels,
  381. )
  382. return &HistogramVec{
  383. metricVec: newMetricVec(desc, func(lvs ...string) Metric {
  384. return newHistogram(desc, opts, lvs...)
  385. }),
  386. }
  387. }
  388. // GetMetricWithLabelValues returns the Histogram for the given slice of label
  389. // values (same order as the VariableLabels in Desc). If that combination of
  390. // label values is accessed for the first time, a new Histogram is created.
  391. //
  392. // It is possible to call this method without using the returned Histogram to only
  393. // create the new Histogram but leave it at its starting value, a Histogram without
  394. // any observations.
  395. //
  396. // Keeping the Histogram for later use is possible (and should be considered if
  397. // performance is critical), but keep in mind that Reset, DeleteLabelValues and
  398. // Delete can be used to delete the Histogram from the HistogramVec. In that case, the
  399. // Histogram will still exist, but it will not be exported anymore, even if a
  400. // Histogram with the same label values is created later. See also the CounterVec
  401. // example.
  402. //
  403. // An error is returned if the number of label values is not the same as the
  404. // number of VariableLabels in Desc (minus any curried labels).
  405. //
  406. // Note that for more than one label value, this method is prone to mistakes
  407. // caused by an incorrect order of arguments. Consider GetMetricWith(Labels) as
  408. // an alternative to avoid that type of mistake. For higher label numbers, the
  409. // latter has a much more readable (albeit more verbose) syntax, but it comes
  410. // with a performance overhead (for creating and processing the Labels map).
  411. // See also the GaugeVec example.
  412. func (v *HistogramVec) GetMetricWithLabelValues(lvs ...string) (Observer, error) {
  413. metric, err := v.metricVec.getMetricWithLabelValues(lvs...)
  414. if metric != nil {
  415. return metric.(Observer), err
  416. }
  417. return nil, err
  418. }
  419. // GetMetricWith returns the Histogram for the given Labels map (the label names
  420. // must match those of the VariableLabels in Desc). If that label map is
  421. // accessed for the first time, a new Histogram is created. Implications of
  422. // creating a Histogram without using it and keeping the Histogram for later use
  423. // are the same as for GetMetricWithLabelValues.
  424. //
  425. // An error is returned if the number and names of the Labels are inconsistent
  426. // with those of the VariableLabels in Desc (minus any curried labels).
  427. //
  428. // This method is used for the same purpose as
  429. // GetMetricWithLabelValues(...string). See there for pros and cons of the two
  430. // methods.
  431. func (v *HistogramVec) GetMetricWith(labels Labels) (Observer, error) {
  432. metric, err := v.metricVec.getMetricWith(labels)
  433. if metric != nil {
  434. return metric.(Observer), err
  435. }
  436. return nil, err
  437. }
  438. // WithLabelValues works as GetMetricWithLabelValues, but panics where
  439. // GetMetricWithLabelValues would have returned an error. Not returning an
  440. // error allows shortcuts like
  441. // myVec.WithLabelValues("404", "GET").Observe(42.21)
  442. func (v *HistogramVec) WithLabelValues(lvs ...string) Observer {
  443. h, err := v.GetMetricWithLabelValues(lvs...)
  444. if err != nil {
  445. panic(err)
  446. }
  447. return h
  448. }
  449. // With works as GetMetricWith but panics where GetMetricWithLabels would have
  450. // returned an error. Not returning an error allows shortcuts like
  451. // myVec.With(prometheus.Labels{"code": "404", "method": "GET"}).Observe(42.21)
  452. func (v *HistogramVec) With(labels Labels) Observer {
  453. h, err := v.GetMetricWith(labels)
  454. if err != nil {
  455. panic(err)
  456. }
  457. return h
  458. }
  459. // CurryWith returns a vector curried with the provided labels, i.e. the
  460. // returned vector has those labels pre-set for all labeled operations performed
  461. // on it. The cardinality of the curried vector is reduced accordingly. The
  462. // order of the remaining labels stays the same (just with the curried labels
  463. // taken out of the sequence – which is relevant for the
  464. // (GetMetric)WithLabelValues methods). It is possible to curry a curried
  465. // vector, but only with labels not yet used for currying before.
  466. //
  467. // The metrics contained in the HistogramVec are shared between the curried and
  468. // uncurried vectors. They are just accessed differently. Curried and uncurried
  469. // vectors behave identically in terms of collection. Only one must be
  470. // registered with a given registry (usually the uncurried version). The Reset
  471. // method deletes all metrics, even if called on a curried vector.
  472. func (v *HistogramVec) CurryWith(labels Labels) (ObserverVec, error) {
  473. vec, err := v.curryWith(labels)
  474. if vec != nil {
  475. return &HistogramVec{vec}, err
  476. }
  477. return nil, err
  478. }
  479. // MustCurryWith works as CurryWith but panics where CurryWith would have
  480. // returned an error.
  481. func (v *HistogramVec) MustCurryWith(labels Labels) ObserverVec {
  482. vec, err := v.CurryWith(labels)
  483. if err != nil {
  484. panic(err)
  485. }
  486. return vec
  487. }
  488. type constHistogram struct {
  489. desc *Desc
  490. count uint64
  491. sum float64
  492. buckets map[float64]uint64
  493. labelPairs []*dto.LabelPair
  494. }
  495. func (h *constHistogram) Desc() *Desc {
  496. return h.desc
  497. }
  498. func (h *constHistogram) Write(out *dto.Metric) error {
  499. his := &dto.Histogram{}
  500. buckets := make([]*dto.Bucket, 0, len(h.buckets))
  501. his.SampleCount = proto.Uint64(h.count)
  502. his.SampleSum = proto.Float64(h.sum)
  503. for upperBound, count := range h.buckets {
  504. buckets = append(buckets, &dto.Bucket{
  505. CumulativeCount: proto.Uint64(count),
  506. UpperBound: proto.Float64(upperBound),
  507. })
  508. }
  509. if len(buckets) > 0 {
  510. sort.Sort(buckSort(buckets))
  511. }
  512. his.Bucket = buckets
  513. out.Histogram = his
  514. out.Label = h.labelPairs
  515. return nil
  516. }
  517. // NewConstHistogram returns a metric representing a Prometheus histogram with
  518. // fixed values for the count, sum, and bucket counts. As those parameters
  519. // cannot be changed, the returned value does not implement the Histogram
  520. // interface (but only the Metric interface). Users of this package will not
  521. // have much use for it in regular operations. However, when implementing custom
  522. // Collectors, it is useful as a throw-away metric that is generated on the fly
  523. // to send it to Prometheus in the Collect method.
  524. //
  525. // buckets is a map of upper bounds to cumulative counts, excluding the +Inf
  526. // bucket.
  527. //
  528. // NewConstHistogram returns an error if the length of labelValues is not
  529. // consistent with the variable labels in Desc or if Desc is invalid.
  530. func NewConstHistogram(
  531. desc *Desc,
  532. count uint64,
  533. sum float64,
  534. buckets map[float64]uint64,
  535. labelValues ...string,
  536. ) (Metric, error) {
  537. if desc.err != nil {
  538. return nil, desc.err
  539. }
  540. if err := validateLabelValues(labelValues, len(desc.variableLabels)); err != nil {
  541. return nil, err
  542. }
  543. return &constHistogram{
  544. desc: desc,
  545. count: count,
  546. sum: sum,
  547. buckets: buckets,
  548. labelPairs: makeLabelPairs(desc, labelValues),
  549. }, nil
  550. }
  551. // MustNewConstHistogram is a version of NewConstHistogram that panics where
  552. // NewConstHistogram would have returned an error.
  553. func MustNewConstHistogram(
  554. desc *Desc,
  555. count uint64,
  556. sum float64,
  557. buckets map[float64]uint64,
  558. labelValues ...string,
  559. ) Metric {
  560. m, err := NewConstHistogram(desc, count, sum, buckets, labelValues...)
  561. if err != nil {
  562. panic(err)
  563. }
  564. return m
  565. }
  566. type buckSort []*dto.Bucket
  567. func (s buckSort) Len() int {
  568. return len(s)
  569. }
  570. func (s buckSort) Swap(i, j int) {
  571. s[i], s[j] = s[j], s[i]
  572. }
  573. func (s buckSort) Less(i, j int) bool {
  574. return s[i].GetUpperBound() < s[j].GetUpperBound()
  575. }