|
| 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 {AccessorInterface} from '../types'; |
| 22 | +import * as util from '../utils'; |
| 23 | + |
| 24 | +type ValueExtractor = () => number; |
| 25 | + |
| 26 | +/** |
| 27 | + * An interface that describes the entry for every TimeSeries (Point) added to |
| 28 | + * the Cumulative metric. |
| 29 | + */ |
| 30 | +interface CumulativeEntry { |
| 31 | + /** The list of the label values. */ |
| 32 | + readonly labelValues: LabelValue[]; |
| 33 | + /** The function to get the actual value of point. */ |
| 34 | + readonly extractor: ValueExtractor; |
| 35 | + /** The previous value of the point. */ |
| 36 | + prevValue: number; |
| 37 | +} |
| 38 | + |
| 39 | +/** |
| 40 | + * DerivedCumulative metric is used to record aggregated metrics that |
| 41 | + * represents a single numerical value accumulated over a time interval. |
| 42 | + */ |
| 43 | +export class DerivedCumulative implements Meter { |
| 44 | + private metricDescriptor: MetricDescriptor; |
| 45 | + private labelKeysLength: number; |
| 46 | + private registeredPoints: Map<string, CumulativeEntry> = new Map(); |
| 47 | + private extractor?: ValueExtractor; |
| 48 | + private readonly constantLabelValues: LabelValue[]; |
| 49 | + private startTime: Timestamp; |
| 50 | + |
| 51 | + /** |
| 52 | + * Constructs a new DerivedCumulative instance. |
| 53 | + * |
| 54 | + * @param name The name of the metric. |
| 55 | + * @param description The description of the metric. |
| 56 | + * @param unit The unit of the metric. |
| 57 | + * @param type The type of metric. |
| 58 | + * @param labelKeys The list of the label keys. |
| 59 | + * @param constantLabels The map of constant labels for the Metric. |
| 60 | + * @param startTime The time when the cumulative metric start measuring the |
| 61 | + * value. |
| 62 | + */ |
| 63 | + constructor( |
| 64 | + name: string, description: string, unit: string, |
| 65 | + type: MetricDescriptorType, labelKeys: LabelKey[], |
| 66 | + readonly constantLabels: Map<LabelKey, LabelValue>, |
| 67 | + startTime: Timestamp) { |
| 68 | + this.labelKeysLength = labelKeys.length; |
| 69 | + const keysAndConstantKeys = [...labelKeys, ...constantLabels.keys()]; |
| 70 | + this.constantLabelValues = [...constantLabels.values()]; |
| 71 | + |
| 72 | + this.metricDescriptor = |
| 73 | + {name, description, unit, type, labelKeys: keysAndConstantKeys}; |
| 74 | + this.startTime = startTime; |
| 75 | + } |
| 76 | + |
| 77 | + /** |
| 78 | + * Creates a TimeSeries. The value of a single point in the TimeSeries is |
| 79 | + * observed from an object or function. The ValueExtractor is invoked whenever |
| 80 | + * metrics are collected, meaning the reported value is up-to-date. |
| 81 | + * |
| 82 | + * @param labelValues The list of the label values. |
| 83 | + * @param objOrFn obj The obj to get the size or length or value from. If |
| 84 | + * multiple options are available, the value (ToValueInterface) takes |
| 85 | + * precedence first, followed by length and size. e.g value -> length -> |
| 86 | + * size. |
| 87 | + * fn is the function that will be called to get the current value |
| 88 | + * of the cumulative. |
| 89 | + */ |
| 90 | + createTimeSeries(labelValues: LabelValue[], objOrFn: AccessorInterface): |
| 91 | + void { |
| 92 | + validateArrayElementsNotNull( |
| 93 | + validateNotNull(labelValues, 'labelValues'), 'labelValue'); |
| 94 | + validateNotNull(objOrFn, 'obj'); |
| 95 | + |
| 96 | + const hash = util.hashLabelValues(labelValues); |
| 97 | + if (this.registeredPoints.has(hash)) { |
| 98 | + throw new Error( |
| 99 | + 'A different time series with the same labels already exists.'); |
| 100 | + } |
| 101 | + if (this.labelKeysLength !== labelValues.length) { |
| 102 | + throw new Error('Label Keys and Label Values don\'t have same size'); |
| 103 | + } |
| 104 | + |
| 105 | + if (objOrFn instanceof Function) { |
| 106 | + this.extractor = objOrFn; |
| 107 | + } else if (util.isToValueInterface(objOrFn)) { |
| 108 | + this.extractor = () => objOrFn.getValue(); |
| 109 | + } else if (util.isLengthAttributeInterface(objOrFn)) { |
| 110 | + this.extractor = () => objOrFn.length; |
| 111 | + } else if (util.isLengthMethodInterface(objOrFn)) { |
| 112 | + this.extractor = () => objOrFn.length(); |
| 113 | + } else if (util.isSizeAttributeInterface(objOrFn)) { |
| 114 | + this.extractor = () => objOrFn.size; |
| 115 | + } else if (util.isSizeMethodInterface(objOrFn)) { |
| 116 | + this.extractor = () => objOrFn.size(); |
| 117 | + } else { |
| 118 | + throw new Error('Unknown interface/object type'); |
| 119 | + } |
| 120 | + |
| 121 | + this.registeredPoints.set( |
| 122 | + hash, {labelValues, extractor: this.extractor, prevValue: 0}); |
| 123 | + } |
| 124 | + |
| 125 | + /** |
| 126 | + * Removes the TimeSeries from the cumulative metric, if it is present. i.e. |
| 127 | + * references to previous Point objects are invalid (not part of the |
| 128 | + * metric). |
| 129 | + * |
| 130 | + * @param labelValues The list of label values. |
| 131 | + */ |
| 132 | + removeTimeSeries(labelValues: LabelValue[]): void { |
| 133 | + validateNotNull(labelValues, 'labelValues'); |
| 134 | + this.registeredPoints.delete(util.hashLabelValues(labelValues)); |
| 135 | + } |
| 136 | + |
| 137 | + /** |
| 138 | + * Removes all TimeSeries from the cumulative metric. i.e. references to all |
| 139 | + * previous Point objects are invalid (not part of the metric). |
| 140 | + */ |
| 141 | + clear(): void { |
| 142 | + this.registeredPoints.clear(); |
| 143 | + } |
| 144 | + |
| 145 | + /** |
| 146 | + * Provides a Metric with one or more TimeSeries. |
| 147 | + * |
| 148 | + * @returns The Metric, or null if TimeSeries is not present in Metric. |
| 149 | + */ |
| 150 | + getMetric(): Metric|null { |
| 151 | + if (this.registeredPoints.size === 0) { |
| 152 | + return null; |
| 153 | + } |
| 154 | + const timestamp: Timestamp = getTimestampWithProcessHRTime(); |
| 155 | + return { |
| 156 | + descriptor: this.metricDescriptor, |
| 157 | + timeseries: Array.from( |
| 158 | + this.registeredPoints, |
| 159 | + ([_, cumulativeEntry]): |
| 160 | + TimeSeries => { |
| 161 | + const newValue = cumulativeEntry.extractor(); |
| 162 | + const value = newValue > cumulativeEntry.prevValue ? |
| 163 | + newValue : |
| 164 | + cumulativeEntry.prevValue; |
| 165 | + cumulativeEntry.prevValue = value; |
| 166 | + |
| 167 | + return { |
| 168 | + labelValues: [ |
| 169 | + ...cumulativeEntry.labelValues, ...this.constantLabelValues |
| 170 | + ], |
| 171 | + points: [{value, timestamp}], |
| 172 | + startTimestamp: this.startTime |
| 173 | + }; |
| 174 | + }) |
| 175 | + }; |
| 176 | + } |
| 177 | +} |
0 commit comments