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 | ```
/** Properties of a Metric which has one or more timeseries */
``` |

17 | ```
export interface Metric {
``` |

18 | ```
/**
``` |

19 | ```
* The descriptor of the Metric. This is an optimization for network wire
``` |

20 | ```
* size, from data-model perspective a Metric contains always
``` |

21 | ```
* a MetricDescriptor.
``` |

22 | ```
* In case of a streaming RPC can be sent only
``` |

23 | ```
* the first time a metric is reported to save network traffic.
``` |

24 | ```
*/
``` |

25 | ```
readonly descriptor: MetricDescriptor;
``` |

26 | ```
/**
``` |

27 | ```
* One or more timeseries for a single metric, where each timeseries has
``` |

28 | ```
* one or more points.
``` |

29 | ```
*/
``` |

30 | ```
readonly timeseries: TimeSeries[];
``` |

31 | ```
}
``` |

32 | ```
/** Properties of a Metric type and its schema */
``` |

33 | ```
export interface MetricDescriptor {
``` |

34 | ```
/** The metric type, including its DNS name prefix. It must be unique. */
``` |

35 | ```
readonly name: string;
``` |

36 | ```
/**
``` |

37 | ```
* A detailed description of the metric, which can be used in documentation.
``` |

38 | ```
*/
``` |

39 | ```
readonly description: string;
``` |

40 | ```
/**
``` |

41 | ```
* The unit in which the metric value is reported. Follows the format
``` |

42 | ```
* described by http://unitsofmeasure.org/ucum.html.
``` |

43 | ```
*/
``` |

44 | ```
readonly unit: string;
``` |

45 | ```
/** MetricDescriptor type */
``` |

46 | ```
readonly type: MetricDescriptorType;
``` |

47 | ```
/** The label keys associated with the metric descriptor. */
``` |

48 | ```
readonly labelKeys: LabelKey[];
``` |

49 | ```
}
``` |

50 | ```
/**
``` |

51 | ```
* The kind of metric. It describes how the data is reported.
``` |

52 | ```
*
``` |

53 | ```
* A gauge is an instantaneous measurement of a value.
``` |

54 | ```
*
``` |

55 | ```
* A cumulative measurement is a value accumulated over a time interval. In
``` |

56 | ```
* a time series, cumulative measurements should have the same start time,
``` |

57 | ```
* increasing values and increasing end times, until an event resets the
``` |

58 | ```
* cumulative value to zero and sets a new start time for the following
``` |

59 | ```
* points.
``` |

60 | ```
*/
``` |

61 | ```
export declare enum MetricDescriptorType {
``` |

62 | ```
/** Do not use this default value. */
``` |

63 | ```
UNSPECIFIED = 0,
``` |

64 | ```
/** Integer gauge. The value can go both up and down. */
``` |

65 | ```
GAUGE_INT64 = 1,
``` |

66 | ```
/** Floating point gauge. The value can go both up and down. */
``` |

67 | ```
GAUGE_DOUBLE = 2,
``` |

68 | ```
/**
``` |

69 | ```
* Distribution gauge measurement. The count and sum can go both up and
``` |

70 | ```
* down. Recorded values are always >= 0.
``` |

71 | ```
* Used in scenarios like a snapshot of time the current items in a queue
``` |

72 | ```
* have spent there.
``` |

73 | ```
*/
``` |

74 | ```
GAUGE_DISTRIBUTION = 3,
``` |

75 | ```
/**
``` |

76 | ```
* Integer cumulative measurement. The value cannot decrease, if resets
``` |

77 | ```
* then the start_time should also be reset.
``` |

78 | ```
*/
``` |

79 | ```
CUMULATIVE_INT64 = 4,
``` |

80 | ```
/**
``` |

81 | ```
* Floating point cumulative measurement. The value cannot decrease, if
``` |

82 | ```
* resets then the start_time should also be reset. Recorded values are
``` |

83 | ```
* always >= 0.
``` |

84 | ```
*/
``` |

85 | ```
CUMULATIVE_DOUBLE = 5,
``` |

86 | ```
/**
``` |

87 | ```
* Distribution cumulative measurement. The count and sum cannot decrease,
``` |

88 | ```
* if resets then the start_time should also be reset.
``` |

89 | ```
*/
``` |

90 | ```
CUMULATIVE_DISTRIBUTION = 6,
``` |

91 | ```
/**
``` |

92 | ```
* Some frameworks implemented Histograms as a summary of observations
``` |

93 | ```
* (usually things like request durations and response sizes). While it
``` |

94 | ```
* also provides a total count of observations and a sum of all observed
``` |

95 | ```
* values, it calculates configurable percentiles over a sliding time
``` |

96 | ```
* window. This is not recommended, since it cannot be aggregated.
``` |

97 | ```
*/
``` |

98 | ```
SUMMARY = 7
``` |

99 | ```
}
``` |

100 | ```
/** Properties of a LabelKey associated with a MetricDescriptor. */
``` |

101 | ```
export interface LabelKey {
``` |

102 | ```
/** The key for the label. */
``` |

103 | ```
readonly key: string;
``` |

104 | ```
/** A human-readable description of what this label key represents. */
``` |

105 | ```
readonly description: string;
``` |

106 | ```
}
``` |

107 | ```
/**
``` |

108 | ```
* A collection of data points that describes the time-varying values
``` |

109 | ```
* of a metric.
``` |

110 | ```
*/
``` |

111 | ```
export interface TimeSeries {
``` |

112 | ```
/**
``` |

113 | ```
* Must be present for cumulative metrics. The time when the cumulative value
``` |

114 | ```
* was reset to zero. Exclusive. The cumulative value is over the time
``` |

115 | ```
* interval (start_timestamp, timestamp]. If not specified, the backend can
``` |

116 | ```
* use the previous recorded value.
``` |

117 | ```
*/
``` |

118 | ```
readonly startTimestamp?: Timestamp;
``` |

119 | ```
/**
``` |

120 | ```
* The set of label values that uniquely identify this timeseries. Applies to
``` |

121 | ```
* all points. The order of label values must match that of label keys in the
``` |

122 | ```
* metric descriptor.
``` |

123 | ```
*/
``` |

124 | ```
readonly labelValues: LabelValue[];
``` |

125 | ```
/**
``` |

126 | ```
* The data points of this timeseries. Point.value type MUST match the
``` |

127 | ```
* MetricDescriptor.type.
``` |

128 | ```
*/
``` |

129 | ```
readonly points: Point[];
``` |

130 | ```
}
``` |

131 | ```
/** The LabelValue type. null value indicates an unset. */
``` |

132 | ```
export interface LabelValue {
``` |

133 | ```
/** The value for the label. */
``` |

134 | ```
readonly value: string | null;
``` |

135 | ```
}
``` |

136 | ```
/** A timestamped measurement. */
``` |

137 | ```
export interface Point {
``` |

138 | ```
/**
``` |

139 | ```
* The moment when this point was recorded. Inclusive.
``` |

140 | ```
* If not specified, the timestamp will be decided by the backend.
``` |

141 | ```
*/
``` |

142 | ```
readonly timestamp: Timestamp;
``` |

143 | ```
/**
``` |

144 | ```
* The actual point value.
``` |

145 | ```
* 64-bit integer or 64-bit double-precision floating-point number
``` |

146 | ```
* or distribution value
``` |

147 | ```
* or summary value. This is not recommended, since it cannot be aggregated.
``` |

148 | ```
*/
``` |

149 | ```
readonly value: number | DistributionValue | SummaryValue;
``` |

150 | ```
}
``` |

151 | ```
/**
``` |

152 | ```
* Distribution contains summary statistics for a population of values. It
``` |

153 | ```
* optionally contains a histogram representing the distribution of those
``` |

154 | ```
* values across a set of buckets.
``` |

155 | ```
*/
``` |

156 | ```
export interface DistributionValue {
``` |

157 | ```
/**
``` |

158 | ```
* The number of values in the population. Must be non-negative. This value
``` |

159 | ```
* must equal the sum of the values in bucket_counts if a histogram is
``` |

160 | ```
* provided.
``` |

161 | ```
*/
``` |

162 | ```
readonly count: number;
``` |

163 | ```
/**
``` |

164 | ```
* The sum of the values in the population. If count is zero then this field
``` |

165 | ```
* must be zero.
``` |

166 | ```
*/
``` |

167 | ```
readonly sum: number;
``` |

168 | ```
/**
``` |

169 | ```
* The sum of squared deviations from the mean of the values in the
``` |

170 | ```
* population. For values x_i this is:
``` |

171 | ```
*
``` |

172 | ```
* Sum[i=1..n]((x_i - mean)^2)
``` |

173 | ```
*
``` |

174 | ```
* Knuth, "The Art of Computer Programming", Vol. 2, page 323, 3rd edition
``` |

175 | ```
* describes Welford's method for accumulating this sum in one pass.
``` |

176 | ```
*
``` |

177 | ```
* If count is zero then this field must be zero.
``` |

178 | ```
*/
``` |

179 | ```
readonly sumOfSquaredDeviation: number;
``` |

180 | ```
/**
``` |

181 | ```
* Don't change bucket boundaries within a TimeSeries if your backend doesn't
``` |

182 | ```
* support this. To save network bandwidth this field can be sent only the
``` |

183 | ```
* first time a metric is sent when using a streaming RPC.
``` |

184 | ```
*/
``` |

185 | ```
readonly bucketOptions: BucketOptions;
``` |

186 | ```
/** DistributionValue buckets */
``` |

187 | ```
readonly buckets: Bucket[];
``` |

188 | ```
}
``` |

189 | ```
/**
``` |

190 | ```
* Properties of a BucketOptions.
``` |

191 | ```
* A Distribution may optionally contain a histogram of the values in the
``` |

192 | ```
* population. The bucket boundaries for that histogram are described by
``` |

193 | ```
* BucketOptions.
``` |

194 | ```
*
``` |

195 | ```
* If bucket_options has no type, then there is no histogram associated with
``` |

196 | ```
* the Distribution.
``` |

197 | ```
*/
``` |

198 | ```
export interface BucketOptions {
``` |

199 | ```
/** Bucket with explicit bounds. */
``` |

200 | ```
readonly explicit: Explicit;
``` |

201 | ```
}
``` |

202 | ```
/**
``` |

203 | ```
* Properties of an Explicit.
``` |

204 | ```
* Specifies a set of buckets with arbitrary upper-bounds.
``` |

205 | ```
* This defines size(bounds) + 1 (= N) buckets. The boundaries for bucket
``` |

206 | ```
* index i are:
``` |

207 | ```
*
``` |

208 | ```
* [0, bucket_bounds[i]) for i == 0
``` |

209 | ```
* [bucket_bounds[i-1], bucket_bounds[i]) for 0 < i < N-1
``` |

210 | ```
* [bucket_bounds[i-1], +infinity) for i == N-1
``` |

211 | ```
*/
``` |

212 | ```
export interface Explicit {
``` |

213 | ```
/** The values must be strictly increasing and > 0. */
``` |

214 | ```
readonly bounds: number[];
``` |

215 | ```
}
``` |

216 | ```
/** Properties of a Bucket. */
``` |

217 | ```
export interface Bucket {
``` |

218 | ```
/**
``` |

219 | ```
* The number of values in each bucket of the histogram, as described in
``` |

220 | ```
* bucket_bounds.
``` |

221 | ```
*/
``` |

222 | ```
readonly count: number;
``` |

223 | ```
/**
``` |

224 | ```
* If the distribution does not have a histogram, then omit this field.
``` |

225 | ```
*/
``` |

226 | ```
readonly exemplar?: Exemplar;
``` |

227 | ```
}
``` |

228 | ```
/**
``` |

229 | ```
* Exemplars are example points that may be used to annotate aggregated
``` |

230 | ```
* Distribution values. They are metadata that gives information about a
``` |

231 | ```
* particular value added to a Distribution bucket.
``` |

232 | ```
*/
``` |

233 | ```
export interface Exemplar {
``` |

234 | ```
/**
``` |

235 | ```
* Value of the exemplar point. It determines which bucket the exemplar
``` |

236 | ```
* belongs to.
``` |

237 | ```
*/
``` |

238 | ```
readonly value: number;
``` |

239 | ```
/** The observation (sampling) time of the above value. */
``` |

240 | ```
readonly timestamp: Timestamp;
``` |

241 | ```
/** Contextual information about the example value. */
``` |

242 | ```
readonly attachments: {
``` |

243 | ```
[key: string]: string;
``` |

244 | ```
};
``` |

245 | ```
}
``` |

246 | ```
/**
``` |

247 | ```
* The start_timestamp only applies to the count and sum in the SummaryValue.
``` |

248 | ```
*/
``` |

249 | ```
export interface SummaryValue {
``` |

250 | ```
/**
``` |

251 | ```
* The total number of recorded values since start_time. Optional since
``` |

252 | ```
* some systems don't expose this.
``` |

253 | ```
*/
``` |

254 | ```
readonly count: number;
``` |

255 | ```
/**
``` |

256 | ```
* The total sum of recorded values since start_time. Optional since some
``` |

257 | ```
* systems don't expose this. If count is zero then this field must be zero.
``` |

258 | ```
* This field must be unset if the sum is not available.
``` |

259 | ```
*/
``` |

260 | ```
readonly sum: number;
``` |

261 | ```
/** Values calculated over an arbitrary time window. */
``` |

262 | ```
readonly snapshot?: Snapshot;
``` |

263 | ```
}
``` |

264 | ```
/**
``` |

265 | ```
* The values in this message can be reset at arbitrary unknown times, with
``` |

266 | ```
* the requirement that all of them are reset at the same time.
``` |

267 | ```
*/
``` |

268 | ```
export interface Snapshot {
``` |

269 | ```
/**
``` |

270 | ```
* The number of values in the snapshot. Optional since some systems don't
``` |

271 | ```
* expose this.
``` |

272 | ```
*/
``` |

273 | ```
readonly count: number;
``` |

274 | ```
/**
``` |

275 | ```
* The sum of values in the snapshot. Optional since some systems don't
``` |

276 | ```
* expose this. If count is zero then this field must be zero or not set
``` |

277 | ```
* (if not supported).
``` |

278 | ```
*/
``` |

279 | ```
readonly sum: number;
``` |

280 | ```
/**
``` |

281 | ```
* A list of values at different percentiles of the distribution calculated
``` |

282 | ```
* from the current snapshot. The percentiles must be strictly increasing.
``` |

283 | ```
*/
``` |

284 | ```
readonly percentileValues: ValueAtPercentile[];
``` |

285 | ```
}
``` |

286 | ```
/**
``` |

287 | ```
* Represents the value at a given percentile of a distribution.
``` |

288 | ```
*/
``` |

289 | ```
export interface ValueAtPercentile {
``` |

290 | ```
/** The percentile of a distribution. Must be in the interval (0.0, 100.0]. */
``` |

291 | ```
readonly percentile: number;
``` |

292 | ```
/** The value at the given percentile of a distribution. */
``` |

293 | ```
readonly value: number;
``` |

294 | ```
}
``` |

295 | ```
export interface Timestamp {
``` |

296 | ```
/**
``` |

297 | ```
* Represents seconds of UTC time since Unix epoch
``` |

298 | ```
* 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
``` |

299 | ```
* 9999-12-31T23:59:59Z inclusive.
``` |

300 | ```
*/
``` |

301 | ```
seconds: number | null;
``` |

302 | ```
/**
``` |

303 | ```
* Non-negative fractions of a second at nanosecond resolution. Negative
``` |

304 | ```
* second values with fractions must still have non-negative nanos values
``` |

305 | ```
* that count forward in time. Must be from 0 to 999,999,999
``` |

306 | ```
* inclusive.
``` |

307 | ```
*/
``` |

308 | ```
nanos: number | null;
``` |

309 | ```
}
``` |

310 | ```
/**
``` |

311 | ```
* Keeps a set of MetricProducer that is used by exporters to determine the
``` |

312 | ```
* metrics that need to be exported.
``` |

313 | ```
*/
``` |

314 | ```
export interface MetricProducerManager {
``` |

315 | ```
/** Adds the MetricProducer to the manager */
``` |

316 | ```
add(metricProducer: MetricProducer): void;
``` |

317 | ```
/** Removes the MetricProducer to the manager */
``` |

318 | ```
remove(metricProducer: MetricProducer): void;
``` |

319 | ```
/** Clears all MetricProducers */
``` |

320 | ```
removeAll(): void;
``` |

321 | ```
/** Gets all registered MetricProducers that should be exported */
``` |

322 | ```
getAllMetricProducer(): Set<MetricProducer>;
``` |

323 | ```
}
``` |

324 | ```
/**
``` |

325 | ```
* A MetricProducer producer that can be registered for exporting using
``` |

326 | ```
* MetricProducerManager.
``` |

327 | ```
*/
``` |

328 | ```
export interface MetricProducer {
``` |

329 | ```
/** Gets a collection of produced Metric`s to be exported */
``` |

330 | ```
getMetrics(): Metric[];
``` |

331 | ```
}
``` |