|
| 1 | +/** |
| 2 | + * Copyright 2019, OpenCensus Authors |
| 3 | + * |
| 4 | + * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | + * you may not use this file except in compliance with the License. |
| 6 | + * You may obtain a copy of the License at |
| 7 | + * |
| 8 | + * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | + * |
| 10 | + * Unless required by applicable law or agreed to in writing, software |
| 11 | + * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | + * See the License for the specific language governing permissions and |
| 14 | + * limitations under the License. |
| 15 | + */ |
| 16 | + |
| 17 | +import {getTimestampWithProcessHRTime} from '../../common/time-util'; |
| 18 | +import {validateArrayElementsNotNull, validateNotNull} from '../../common/validations'; |
| 19 | +import {LabelKey, LabelValue, Metric, MetricDescriptor, MetricDescriptorType, TimeSeries, Timestamp} from '../export/types'; |
| 20 | +import {Meter} from '../types'; |
| 21 | +import {hashLabelValues, initializeDefaultLabels} from '../utils'; |
| 22 | +import {CumulativePoint} from './types'; |
| 23 | + |
| 24 | +/** |
| 25 | + * Cumulative metric is used to record aggregated metrics that represents a |
| 26 | + * single numerical value accumulated over a time interval. The value can only |
| 27 | + * increase or be reset to zero on restart or reset the event. |
| 28 | + */ |
| 29 | +export class Cumulative implements Meter { |
| 30 | + private readonly metricDescriptor: MetricDescriptor; |
| 31 | + private labelKeysLength: number; |
| 32 | + private defaultLabelValues: LabelValue[]; |
| 33 | + private registeredPoints: Map<string, CumulativePoint> = new Map(); |
| 34 | + private readonly constantLabelValues: LabelValue[]; |
| 35 | + |
| 36 | + /** |
| 37 | + * Constructs a new Cumulative instance. |
| 38 | + * |
| 39 | + * @param {string} name The name of the metric. |
| 40 | + * @param {string} description The description of the metric. |
| 41 | + * @param {string} unit The unit of the metric. |
| 42 | + * @param {MetricDescriptorType} type The type of metric. |
| 43 | + * @param {LabelKey[]} labelKeys The list of the label keys. |
| 44 | + * @param {Map<LabelKey, LabelValue>} constantLabels The map of constant |
| 45 | + * labels for the Metric. |
| 46 | + */ |
| 47 | + constructor( |
| 48 | + name: string, description: string, unit: string, |
| 49 | + type: MetricDescriptorType, readonly labelKeys: LabelKey[], |
| 50 | + readonly constantLabels: Map<LabelKey, LabelValue>) { |
| 51 | + this.labelKeysLength = labelKeys.length; |
| 52 | + const keysAndConstantKeys = [...labelKeys, ...constantLabels.keys()]; |
| 53 | + this.constantLabelValues = [...constantLabels.values()]; |
| 54 | + |
| 55 | + this.metricDescriptor = |
| 56 | + {name, description, unit, type, labelKeys: keysAndConstantKeys}; |
| 57 | + this.defaultLabelValues = initializeDefaultLabels(this.labelKeysLength); |
| 58 | + } |
| 59 | + |
| 60 | + /** |
| 61 | + * Creates a TimeSeries and returns a Point if the specified |
| 62 | + * labelValues is not already associated with this cumulative, else returns an |
| 63 | + * existing Point. |
| 64 | + * |
| 65 | + * It is recommended to keep a reference to the Point instead of always |
| 66 | + * calling this method for manual operations. |
| 67 | + * |
| 68 | + * @param {LabelValue[]} labelValues The list of the label values. |
| 69 | + * @returns {CumulativePoint} The value of single cumulative. |
| 70 | + */ |
| 71 | + getOrCreateTimeSeries(labelValues: LabelValue[]): CumulativePoint { |
| 72 | + validateArrayElementsNotNull( |
| 73 | + validateNotNull(labelValues, 'labelValues'), 'labelValue'); |
| 74 | + return this.registerTimeSeries(labelValues); |
| 75 | + } |
| 76 | + |
| 77 | + /** |
| 78 | + * Returns a Point for a cumulative with all labels not set, or default |
| 79 | + * labels. |
| 80 | + * |
| 81 | + * @returns {CumulativePoint} The value of single cumulative. |
| 82 | + */ |
| 83 | + getDefaultTimeSeries(): CumulativePoint { |
| 84 | + return this.registerTimeSeries(this.defaultLabelValues); |
| 85 | + } |
| 86 | + |
| 87 | + /** |
| 88 | + * Removes the TimeSeries from the cumulative metric, if it is present. i.e. |
| 89 | + * references to previous Point objects are invalid (not part of the |
| 90 | + * metric). |
| 91 | + * |
| 92 | + * @param {LabelValue[]} labelValues The list of label values. |
| 93 | + */ |
| 94 | + removeTimeSeries(labelValues: LabelValue[]): void { |
| 95 | + validateNotNull(labelValues, 'labelValues'); |
| 96 | + this.registeredPoints.delete(hashLabelValues(labelValues)); |
| 97 | + } |
| 98 | + |
| 99 | + /** |
| 100 | + * Removes all TimeSeries from the cumulative metric. i.e. references to all |
| 101 | + * previous Point objects are invalid (not part of the metric). |
| 102 | + */ |
| 103 | + clear(): void { |
| 104 | + this.registeredPoints.clear(); |
| 105 | + } |
| 106 | + |
| 107 | + /** |
| 108 | + * Registers a TimeSeries and returns a Point if the specified |
| 109 | + * labelValues is not already associated with this cumulative, else returns an |
| 110 | + * existing Point. |
| 111 | + * |
| 112 | + * @param {LabelValue[]} labelValues The list of the label values. |
| 113 | + * @returns {CumulativePoint} The value of single cumulative. |
| 114 | + */ |
| 115 | + private registerTimeSeries(labelValues: LabelValue[]): CumulativePoint { |
| 116 | + const hash = hashLabelValues(labelValues); |
| 117 | + // return if the specified labelValues is already associated with the point. |
| 118 | + if (this.registeredPoints.has(hash)) { |
| 119 | + return this.registeredPoints.get(hash)!; |
| 120 | + } |
| 121 | + if (this.labelKeysLength !== labelValues.length) { |
| 122 | + throw new Error('Label Keys and Label Values don\'t have same size'); |
| 123 | + } |
| 124 | + |
| 125 | + const point = |
| 126 | + new CumulativePointEntry([...labelValues, ...this.constantLabelValues]); |
| 127 | + this.registeredPoints.set(hash, point); |
| 128 | + return point; |
| 129 | + } |
| 130 | + |
| 131 | + /** |
| 132 | + * Provides a Metric with one or more TimeSeries. |
| 133 | + * |
| 134 | + * @returns {Metric} The Metric, or null if TimeSeries is not present in |
| 135 | + * Metric. |
| 136 | + */ |
| 137 | + getMetric(): Metric|null { |
| 138 | + if (this.registeredPoints.size === 0) { |
| 139 | + return null; |
| 140 | + } |
| 141 | + const now: Timestamp = getTimestampWithProcessHRTime(); |
| 142 | + return { |
| 143 | + descriptor: this.metricDescriptor, |
| 144 | + timeseries: Array.from( |
| 145 | + this.registeredPoints, ([_, point]) => point.getTimeSeries(now)) |
| 146 | + }; |
| 147 | + } |
| 148 | +} |
| 149 | + |
| 150 | +/** |
| 151 | + * The value of a single point in the Cumulative.TimeSeries. |
| 152 | + */ |
| 153 | +export class CumulativePointEntry implements CumulativePoint { |
| 154 | + private readonly labelValues: LabelValue[]; |
| 155 | + private startTimestamp: Timestamp; |
| 156 | + private value = 0; |
| 157 | + |
| 158 | + constructor(labelValues: LabelValue[]) { |
| 159 | + this.labelValues = labelValues; |
| 160 | + this.startTimestamp = getTimestampWithProcessHRTime(); |
| 161 | + } |
| 162 | + |
| 163 | + /** Reset cumulative metric. */ |
| 164 | + reset(): void { |
| 165 | + this.value = 0; |
| 166 | + this.startTimestamp = getTimestampWithProcessHRTime(); |
| 167 | + } |
| 168 | + |
| 169 | + /** |
| 170 | + * Increment the cumulative metric. |
| 171 | + * @param {number} val The new value. |
| 172 | + */ |
| 173 | + inc(val?: number): void { |
| 174 | + if ((val && !Number.isFinite(val)) || (val !== undefined && isNaN(val))) { |
| 175 | + throw new TypeError(`Value is not a valid number: ${val}`); |
| 176 | + } |
| 177 | + if (val && val < 0) { |
| 178 | + throw new Error('It is not possible to decrease a cumulative metric'); |
| 179 | + } |
| 180 | + const incValue = (val === null || val === undefined) ? 1 : val; |
| 181 | + this.value += incValue; |
| 182 | + } |
| 183 | + |
| 184 | + /** |
| 185 | + * Returns the TimeSeries with one or more Point. |
| 186 | + * |
| 187 | + * @param {Timestamp} now The time at which the cumulative is recorded. |
| 188 | + * @returns {TimeSeries} The TimeSeries. |
| 189 | + */ |
| 190 | + getTimeSeries(now: Timestamp): TimeSeries { |
| 191 | + return { |
| 192 | + labelValues: this.labelValues, |
| 193 | + points: [{value: this.value, timestamp: now}], |
| 194 | + startTimestamp: this.startTimestamp |
| 195 | + }; |
| 196 | + } |
| 197 | +} |
0 commit comments