|
| 1 | +part of prometheus_client; |
| 2 | + |
| 3 | +/// Similar to a [Histogram], a [Summary] samples observations (usually things |
| 4 | +/// like request durations and response sizes). While it also provides a total |
| 5 | +/// count of observations and a sum of all observed values, it calculates |
| 6 | +/// configurable quantiles over a sliding time window. |
| 7 | +class Summary extends _SimpleCollector<SummaryChild> { |
| 8 | + static const quantileLabel = 'quantile'; |
| 9 | + |
| 10 | + /// Quantiles to observe by the summary. |
| 11 | + final List<Quantile> quantiles; |
| 12 | + |
| 13 | + /// Set the duration of the time window is, i.e. how long observations are |
| 14 | + /// kept before they are discarded. |
| 15 | + final Duration maxAge; |
| 16 | + |
| 17 | + /// Set the number of buckets used to implement the sliding time window. If |
| 18 | + /// your time window is 10 minutes, and you have ageBuckets=5, buckets will |
| 19 | + /// be switched every 2 minutes. The value is a trade-off between resources |
| 20 | + /// (memory and cpu for maintaining the bucket) and how smooth the time window |
| 21 | + /// is moved. |
| 22 | + final int ageBuckets; |
| 23 | + |
| 24 | + /// Construct a new [Summary] with a [name], [help] text, optional |
| 25 | + /// [labelNames], optional [quantiles], optional [maxAge] and optional |
| 26 | + /// [ageBuckets]. |
| 27 | + /// If [labelNames] are provided, use [labels(...)] to assign label values. |
| 28 | + /// If no [quantiles] are provided the summary only has a count and sum. |
| 29 | + /// If not provided, [maxAge] defaults to 10 minutes and [ageBuckets] to 5. |
| 30 | + Summary(String name, String help, |
| 31 | + {List<String> labelNames = const [], |
| 32 | + List<Quantile> quantiles = const [], |
| 33 | + this.maxAge = const Duration(minutes: 10), |
| 34 | + this.ageBuckets = 5}) |
| 35 | + : quantiles = List.unmodifiable(quantiles), |
| 36 | + super(name, help, labelNames: labelNames) { |
| 37 | + if (labelNames.contains(quantileLabel)) { |
| 38 | + throw ArgumentError.value(labelNames, 'labelNames', |
| 39 | + '"quantile" is a reseved label name for a summary.'); |
| 40 | + } |
| 41 | + } |
| 42 | + |
| 43 | + /// Observe a new value [v] and store it in the summary without labels. |
| 44 | + void observe(double v) { |
| 45 | + _noLabelChild.observe(v); |
| 46 | + } |
| 47 | + |
| 48 | + /// Observe the duration of [callback] and store it in the summary without |
| 49 | + /// labels. |
| 50 | + T observeDurationSync<T>(T callback()) { |
| 51 | + return _noLabelChild.observeDurationSync(callback); |
| 52 | + } |
| 53 | + |
| 54 | + /// Observe the duration of the [Future] [f] and store it in the summary |
| 55 | + /// without labels. |
| 56 | + Future<T> observeDuration<T>(Future<T> f) { |
| 57 | + return _noLabelChild.observeDuration(f); |
| 58 | + } |
| 59 | + |
| 60 | + /// Access the count of elements in a summary without labels. |
| 61 | + double get count => _noLabelChild.count; |
| 62 | + |
| 63 | + /// Access the total sum of the elements in a summary without labels. |
| 64 | + double get sum => _noLabelChild.sum; |
| 65 | + |
| 66 | + /// Access the value of each quantile of a summary without labels. |
| 67 | + Map get values => _noLabelChild.values; |
| 68 | + |
| 69 | + @override |
| 70 | + SummaryChild _createChild() => SummaryChild._(quantiles, maxAge, ageBuckets); |
| 71 | + |
| 72 | + @override |
| 73 | + Iterable<MetricFamilySamples> collect() sync* { |
| 74 | + final samples = <Sample>[]; |
| 75 | + |
| 76 | + _children.forEach((labelValues, child) { |
| 77 | + final labelNamesWithQuantile = List.of(labelNames)..add(quantileLabel); |
| 78 | + final values = child.values; |
| 79 | + |
| 80 | + for (var i = 0; i < quantiles.length; ++i) { |
| 81 | + final q = quantiles[i].quantile; |
| 82 | + samples.add(Sample(name, labelNamesWithQuantile, |
| 83 | + List.of(labelValues)..add(formatDouble(q)), values[q])); |
| 84 | + } |
| 85 | + |
| 86 | + samples |
| 87 | + .add(Sample(name + '_count', labelNames, labelValues, child.count)); |
| 88 | + samples.add(Sample(name + '_sum', labelNames, labelValues, child.sum)); |
| 89 | + }); |
| 90 | + |
| 91 | + yield MetricFamilySamples(name, MetricType.summary, help, samples); |
| 92 | + } |
| 93 | +} |
| 94 | + |
| 95 | +/// Defines a [SummaryChild] of a [Summary] with assigned [labelValues]. |
| 96 | +class SummaryChild { |
| 97 | + /// Quantiles to observe by the summary. |
| 98 | + final List<Quantile> quantiles; |
| 99 | + |
| 100 | + double _count = 0; |
| 101 | + double _sum = 0; |
| 102 | + final TimeWindowQuantiles _quantileValues; |
| 103 | + |
| 104 | + SummaryChild._(this.quantiles, Duration maxAge, int ageBuckets) |
| 105 | + : _quantileValues = quantiles.isEmpty |
| 106 | + ? null |
| 107 | + : TimeWindowQuantiles(quantiles, maxAge, ageBuckets); |
| 108 | + |
| 109 | + /// Observe a new value [v] and store it in the summary with labels. |
| 110 | + void observe(double v) { |
| 111 | + _count += 1; |
| 112 | + _sum += v; |
| 113 | + if (_quantileValues != null) { |
| 114 | + _quantileValues.insert(v); |
| 115 | + } |
| 116 | + } |
| 117 | + |
| 118 | + /// Observe the duration of [callback] and store it in the summary with |
| 119 | + /// labels. |
| 120 | + T observeDurationSync<T>(T callback()) { |
| 121 | + final stopwatch = Stopwatch()..start(); |
| 122 | + try { |
| 123 | + return callback(); |
| 124 | + } finally { |
| 125 | + observe(stopwatch.elapsedMicroseconds / Duration.microsecondsPerSecond); |
| 126 | + } |
| 127 | + } |
| 128 | + |
| 129 | + /// Observe the duration of the [Future] [f] and store it in the summary with |
| 130 | + /// labels. |
| 131 | + Future<T> observeDuration<T>(Future<T> f) async { |
| 132 | + final stopwatch = Stopwatch()..start(); |
| 133 | + try { |
| 134 | + return await f; |
| 135 | + } finally { |
| 136 | + observe(stopwatch.elapsedMicroseconds / Duration.microsecondsPerSecond); |
| 137 | + } |
| 138 | + } |
| 139 | + |
| 140 | + /// Access the count of elements in a summary with labels. |
| 141 | + double get count => _count; |
| 142 | + |
| 143 | + /// Access the total sum of the elements in a summary with labels. |
| 144 | + double get sum => _sum; |
| 145 | + |
| 146 | + /// Access the value of each quantile of a summary with labels. |
| 147 | + Map get values => Map.fromIterable(quantiles, |
| 148 | + key: (q) => q.quantile, |
| 149 | + value: (q) => _quantileValues.retrieve(q.quantile)); |
| 150 | +} |
0 commit comments