1 | /**
|
2 | * Copyright 2018, 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 | import { StatsEventListener } from '../exporters/types';
|
17 | import { Metric } from '../metrics/export/types';
|
18 | import { TagMap } from '../tags/tag-map';
|
19 | import { TagKey, TagValue } from '../tags/types';
|
20 | /** Default type for functions */
|
21 | declare type Func<T> = (...args: any[]) => T;
|
22 | /** Main interface for stats. */
|
23 | export interface Stats {
|
24 | /**
|
25 | * Creates a view.
|
26 | * @param name The view name
|
27 | * @param measure The view measure
|
28 | * @param aggregation The view aggregation type
|
29 | * @param tagKeys The view columns (tag keys)
|
30 | * @param description The view description
|
31 | * @param bucketBoundaries The view bucket boundaries for a distribution
|
32 | * aggregation type
|
33 | */
|
34 | createView(name: string, measure: Measure, aggregation: AggregationType, tagKeys: TagKey[], description: string, bucketBoundaries?: number[]): View;
|
35 | /**
|
36 | * Registers a view to listen to new measurements in its measure.
|
37 | * @param view The view to be registered
|
38 | */
|
39 | registerView(view: View): void;
|
40 | /**
|
41 | * Creates a measure of type Double.
|
42 | * @param name The measure name
|
43 | * @param unit The measure unit
|
44 | * @param description The measure description
|
45 | */
|
46 | createMeasureDouble(name: string, unit: MeasureUnit, description?: string): Measure;
|
47 | /**
|
48 | * Creates a measure of type Int64. Values must be integers up to
|
49 | * Number.MAX_SAFE_INTERGER.
|
50 | * @param name The measure name
|
51 | * @param unit The measure unit
|
52 | * @param description The measure description
|
53 | */
|
54 | createMeasureInt64(name: string, unit: MeasureUnit, description?: string): Measure;
|
55 | /**
|
56 | * Updates all views with the new measurements.
|
57 | * @param measurements A list of measurements to record
|
58 | * @param tags optional The tags to which the value is applied.
|
59 | * tags could either be explicitly passed to the method, or implicitly
|
60 | * read from current execution context.
|
61 | * @param attachments optional The contextual information associated with an
|
62 | * example value. The contextual information is represented as key - value
|
63 | * string pairs.
|
64 | */
|
65 | record(measurements: Measurement[], tags?: TagMap, attachments?: {
|
66 | [key: string]: string;
|
67 | }): void;
|
68 | /**
|
69 | * Remove all registered Views and exporters from the stats.
|
70 | */
|
71 | clear(): void;
|
72 | /**
|
73 | * Gets a collection of produced Metric`s to be exported.
|
74 | * @returns The List of metrics.
|
75 | */
|
76 | getMetrics(): Metric[];
|
77 | /**
|
78 | * Registers an exporter to send stats data to a service.
|
79 | * @param exporter An stats exporter
|
80 | */
|
81 | registerExporter(exporter: StatsEventListener): void;
|
82 | /**
|
83 | * Unregisters an exporter. It should be called whenever the exporter is not
|
84 | * needed anymore.
|
85 | * @param exporter An stats exporter
|
86 | */
|
87 | unregisterExporter(exporter: StatsEventListener): void;
|
88 | /**
|
89 | * Enters the scope of code where the given `TagMap` is in the current context
|
90 | * (replacing the previous `TagMap`).
|
91 | * @param tags The TagMap to be set to the current context.
|
92 | * @param fn Callback function.
|
93 | * @returns The callback return.
|
94 | */
|
95 | withTagContext<T>(tags: TagMap, fn: Func<T>): T;
|
96 | /** Gets the current tag context. */
|
97 | getCurrentTagContext(): TagMap;
|
98 | }
|
99 | /**
|
100 | * Describes the type of the individual values/measurements recorded by an
|
101 | * application. It includes information such as the type of measurement, the
|
102 | * units of measurement and descriptive names for the data. This provides the
|
103 | * fundamental type used for recording data.
|
104 | */
|
105 | export interface Measure {
|
106 | /**
|
107 | * A string by which the measure will be referred to, e.g.
|
108 | * "rpc_server_latency". Names MUST be unique within the library.
|
109 | */
|
110 | readonly name: string;
|
111 | /** Describes the measure, e.g. "RPC latency in seconds". */
|
112 | readonly description?: string;
|
113 | /**
|
114 | * Describes the unit used for the Measure. Follows the format described by
|
115 | * http://unitsofmeasure.org/ucum.html.
|
116 | */
|
117 | readonly unit: MeasureUnit;
|
118 | /** The type used for this Measure. */
|
119 | readonly type: MeasureType;
|
120 | }
|
121 | /**
|
122 | * Describes the unit used for the Measure. Should follows the format described
|
123 | * by http://unitsofmeasure.org/ucum.html.
|
124 | */
|
125 | export declare enum MeasureUnit {
|
126 | UNIT = "1",
|
127 | BYTE = "by",
|
128 | KBYTE = "kb",
|
129 | SEC = "s",
|
130 | MS = "ms",
|
131 | NS = "ns"
|
132 | }
|
133 | /** Describes the types of a Measure. It can be Int64 or a Double type. */
|
134 | export declare enum MeasureType {
|
135 | INT64 = "INT64",
|
136 | DOUBLE = "DOUBLE"
|
137 | }
|
138 | /** Describes a data point to be collected for a Measure. */
|
139 | export interface Measurement {
|
140 | /** The measure to which the value is applied */
|
141 | readonly measure: Measure;
|
142 | /**
|
143 | * The recorded value. If the measure has type INT64, value must be an integer
|
144 | * up to Number.MAX_SAFE_INTERGER.
|
145 | */
|
146 | readonly value: number;
|
147 | }
|
148 | /**
|
149 | * Defines how individual measurements are broken down by tags and aggregated.
|
150 | */
|
151 | export interface View {
|
152 | /**
|
153 | * A string by which the View will be referred to, e.g. "rpc_latency". Names
|
154 | * MUST be unique within the library.
|
155 | */
|
156 | readonly name: string;
|
157 | /** Describes the view, e.g. "RPC latency distribution" */
|
158 | readonly description: string;
|
159 | /** The Measure to which this view is applied. */
|
160 | readonly measure: Measure;
|
161 | /**
|
162 | * An Aggregation describes how data collected is aggregated.
|
163 | * There are four aggregation types: count, sum, lastValue and distirbution.
|
164 | */
|
165 | readonly aggregation: AggregationType;
|
166 | /** The start time for this view */
|
167 | readonly startTime: number;
|
168 | /**
|
169 | * The end time for this view - represents the last time a value was recorded
|
170 | */
|
171 | endTime?: number;
|
172 | /** true if the view was registered */
|
173 | registered: boolean;
|
174 | /**
|
175 | * Records a measurement in the proper view's row. This method is used by
|
176 | * Stats. User should prefer using Stats.record() instead.
|
177 | *
|
178 | * Measurements with measurement type INT64 will have its value truncated.
|
179 | * @param measurement The measurement to record
|
180 | * @param tags The tags to which the value is applied
|
181 | * @param attachments optional The contextual information associated with an
|
182 | * example value. THe contextual information is represented as key - value
|
183 | * string pairs.
|
184 | */
|
185 | recordMeasurement(measurement: Measurement, tags: TagMap, attachments?: {
|
186 | [key: string]: string;
|
187 | }): void;
|
188 | /**
|
189 | * Returns a snapshot of an AggregationData for that tags/labels values.
|
190 | * @param tagValues The desired data's tag values.
|
191 | */
|
192 | getSnapshot(tagValues: Array<TagValue | null>): AggregationData;
|
193 | /** Gets the view's tag keys */
|
194 | getColumns(): TagKey[];
|
195 | /** Gets view`s metric */
|
196 | getMetric(start: number): Metric;
|
197 | }
|
198 | /**
|
199 | * Informs the type of the aggregation. It can be: count, sum, lastValue or
|
200 | * distribution.
|
201 | */
|
202 | export declare enum AggregationType {
|
203 | COUNT = 0,
|
204 | SUM = 1,
|
205 | LAST_VALUE = 2,
|
206 | DISTRIBUTION = 3
|
207 | }
|
208 | /** Defines how data is collected and aggregated */
|
209 | export interface AggregationMetadata {
|
210 | /** The aggregation type of the aggregation data */
|
211 | readonly type: AggregationType;
|
212 | /** The tagValues that this AggregationData collects and aggregates */
|
213 | readonly tagValues: Array<TagValue | null>;
|
214 | /** The latest timestamp a new data point was recorded */
|
215 | timestamp: number;
|
216 | }
|
217 | /**
|
218 | * Data collected and aggregated with this AggregationData will be summed
|
219 | * up.
|
220 | */
|
221 | export interface SumData extends AggregationMetadata {
|
222 | type: AggregationType.SUM;
|
223 | /** The current accumulated value */
|
224 | value: number;
|
225 | }
|
226 | /**
|
227 | * This AggregationData counts the number of measurements recorded.
|
228 | */
|
229 | export interface CountData extends AggregationMetadata {
|
230 | type: AggregationType.COUNT;
|
231 | /** The current counted value */
|
232 | value: number;
|
233 | }
|
234 | /**
|
235 | * This AggregationData represents the last recorded value. This is useful
|
236 | * when giving support to Gauges.
|
237 | */
|
238 | export interface LastValueData extends AggregationMetadata {
|
239 | type: AggregationType.LAST_VALUE;
|
240 | /** The last recorded value */
|
241 | value: number;
|
242 | }
|
243 | /** This AggregationData contains a histogram of the collected values. */
|
244 | export interface DistributionData extends AggregationMetadata {
|
245 | type: AggregationType.DISTRIBUTION;
|
246 | /** The first timestamp a datapoint was added */
|
247 | readonly startTime: number;
|
248 | /** Get the total count of all recorded values in the histogram */
|
249 | count: number;
|
250 | /** Sum of all recorded values in the histogram */
|
251 | sum: number;
|
252 | /** Get the computed mean value of all recorded values in the histogram */
|
253 | mean: number;
|
254 | /**
|
255 | * Get the computed standard deviation of all recorded values in the
|
256 | * histogram
|
257 | */
|
258 | stdDeviation: number;
|
259 | /**
|
260 | * Get the computed sum of squared deviations of all recorded values in the
|
261 | * histogram.
|
262 | */
|
263 | sumOfSquaredDeviation: number;
|
264 | /** Bucket distribution of the histogram */
|
265 | buckets: Bucket[];
|
266 | /** Buckets count */
|
267 | bucketCounts?: number[];
|
268 | /** If the distribution does not have a histogram, then omit this field. */
|
269 | exemplars?: StatsExemplar[];
|
270 | }
|
271 | /**
|
272 | * Exemplars are example points that may be used to annotate aggregated
|
273 | * Distribution values. They are metadata that gives information about a
|
274 | * particular value added to a Distribution bucket.
|
275 | */
|
276 | export interface StatsExemplar {
|
277 | /**
|
278 | * Value of the exemplar point. It determines which bucket the exemplar
|
279 | * belongs to.
|
280 | */
|
281 | readonly value: number;
|
282 | /** The observation (sampling) time of the above value. */
|
283 | readonly timestamp: number;
|
284 | /** Contextual information about the example value. */
|
285 | readonly attachments: {
|
286 | [key: string]: string;
|
287 | };
|
288 | }
|
289 | export declare type Bucket = number;
|
290 | export declare type AggregationData = SumData | CountData | LastValueData | DistributionData;
|
291 | export {};
|