@opencensus/web-types
Version:
OpenCensus Web types is a slightly-patched copy of the `types.ts` files from `@opencensus/core` so that they can be easily imported in web-specific packages.
292 lines (291 loc) • 10.6 kB
TypeScript
/**
* Copyright 2019, OpenCensus Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { StatsEventListener } from '../exporters/types';
import { Metric } from '../metrics/export/types';
import { TagMap } from '../tags/tag-map';
import { TagKey, TagValue } from '../tags/types';
/** Default type for functions */
declare type Func<T> = (...args: any[]) => T;
/** Main interface for stats. */
export interface Stats {
/**
* Creates a view.
* @param name The view name
* @param measure The view measure
* @param aggregation The view aggregation type
* @param tagKeys The view columns (tag keys)
* @param description The view description
* @param bucketBoundaries The view bucket boundaries for a distribution
* aggregation type
*/
createView(name: string, measure: Measure, aggregation: AggregationType, tagKeys: TagKey[], description: string, bucketBoundaries?: number[]): View;
/**
* Registers a view to listen to new measurements in its measure.
* @param view The view to be registered
*/
registerView(view: View): void;
/**
* Creates a measure of type Double.
* @param name The measure name
* @param unit The measure unit
* @param description The measure description
*/
createMeasureDouble(name: string, unit: MeasureUnit, description?: string): Measure;
/**
* Creates a measure of type Int64. Values must be integers up to
* Number.MAX_SAFE_INTERGER.
* @param name The measure name
* @param unit The measure unit
* @param description The measure description
*/
createMeasureInt64(name: string, unit: MeasureUnit, description?: string): Measure;
/**
* Updates all views with the new measurements.
* @param measurements A list of measurements to record
* @param tags optional The tags to which the value is applied.
* tags could either be explicitly passed to the method, or implicitly
* read from current execution context.
* @param attachments optional The contextual information associated with an
* example value. The contextual information is represented as key - value
* string pairs.
*/
record(measurements: Measurement[], tags?: TagMap, attachments?: {
[key: string]: string;
}): void;
/**
* Remove all registered Views and exporters from the stats.
*/
clear(): void;
/**
* Gets a collection of produced Metric`s to be exported.
* @returns The List of metrics.
*/
getMetrics(): Metric[];
/**
* Registers an exporter to send stats data to a service.
* @param exporter An stats exporter
*/
registerExporter(exporter: StatsEventListener): void;
/**
* Unregisters an exporter. It should be called whenever the exporter is not
* needed anymore.
* @param exporter An stats exporter
*/
unregisterExporter(exporter: StatsEventListener): void;
/**
* Enters the scope of code where the given `TagMap` is in the current context
* (replacing the previous `TagMap`).
* @param tags The TagMap to be set to the current context.
* @param fn Callback function.
* @returns The callback return.
*/
withTagContext<T>(tags: TagMap, fn: Func<T>): T;
/** Gets the current tag context. */
getCurrentTagContext(): TagMap;
}
/**
* Describes the type of the individual values/measurements recorded by an
* application. It includes information such as the type of measurement, the
* units of measurement and descriptive names for the data. This provides the
* fundamental type used for recording data.
*/
export interface Measure {
/**
* A string by which the measure will be referred to, e.g.
* "rpc_server_latency". Names MUST be unique within the library.
*/
readonly name: string;
/** Describes the measure, e.g. "RPC latency in seconds". */
readonly description?: string;
/**
* Describes the unit used for the Measure. Follows the format described by
* http://unitsofmeasure.org/ucum.html.
*/
readonly unit: MeasureUnit;
/** The type used for this Measure. */
readonly type: MeasureType;
}
/**
* Describes the unit used for the Measure. Should follows the format described
* by http://unitsofmeasure.org/ucum.html.
*/
export declare enum MeasureUnit {
UNIT = "1",
BYTE = "by",
KBYTE = "kb",
SEC = "s",
MS = "ms",
NS = "ns"
}
/** Describes the types of a Measure. It can be Int64 or a Double type. */
export declare enum MeasureType {
INT64 = "INT64",
DOUBLE = "DOUBLE"
}
/** Describes a data point to be collected for a Measure. */
export interface Measurement {
/** The measure to which the value is applied */
readonly measure: Measure;
/**
* The recorded value. If the measure has type INT64, value must be an integer
* up to Number.MAX_SAFE_INTERGER.
*/
readonly value: number;
}
/**
* Defines how individual measurements are broken down by tags and aggregated.
*/
export interface View {
/**
* A string by which the View will be referred to, e.g. "rpc_latency". Names
* MUST be unique within the library.
*/
readonly name: string;
/** Describes the view, e.g. "RPC latency distribution" */
readonly description: string;
/** The Measure to which this view is applied. */
readonly measure: Measure;
/**
* An Aggregation describes how data collected is aggregated.
* There are four aggregation types: count, sum, lastValue and distirbution.
*/
readonly aggregation: AggregationType;
/** The start time for this view */
readonly startTime: number;
/**
* The end time for this view - represents the last time a value was recorded
*/
endTime?: number;
/** true if the view was registered */
registered: boolean;
/**
* Records a measurement in the proper view's row. This method is used by
* Stats. User should prefer using Stats.record() instead.
*
* Measurements with measurement type INT64 will have its value truncated.
* @param measurement The measurement to record
* @param tags The tags to which the value is applied
* @param attachments optional The contextual information associated with an
* example value. THe contextual information is represented as key - value
* string pairs.
*/
recordMeasurement(measurement: Measurement, tags: TagMap, attachments?: {
[key: string]: string;
}): void;
/**
* Returns a snapshot of an AggregationData for that tags/labels values.
* @param tagValues The desired data's tag values.
*/
getSnapshot(tagValues: Array<TagValue | null>): AggregationData;
/** Gets the view's tag keys */
getColumns(): TagKey[];
/** Gets view`s metric */
getMetric(start: number): Metric;
}
/**
* Informs the type of the aggregation. It can be: count, sum, lastValue or
* distribution.
*/
export declare enum AggregationType {
COUNT = 0,
SUM = 1,
LAST_VALUE = 2,
DISTRIBUTION = 3
}
/** Defines how data is collected and aggregated */
export interface AggregationMetadata {
/** The aggregation type of the aggregation data */
readonly type: AggregationType;
/** The tagValues that this AggregationData collects and aggregates */
readonly tagValues: Array<TagValue | null>;
/** The latest timestamp a new data point was recorded */
timestamp: number;
}
/**
* Data collected and aggregated with this AggregationData will be summed
* up.
*/
export interface SumData extends AggregationMetadata {
type: AggregationType.SUM;
/** The current accumulated value */
value: number;
}
/**
* This AggregationData counts the number of measurements recorded.
*/
export interface CountData extends AggregationMetadata {
type: AggregationType.COUNT;
/** The current counted value */
value: number;
}
/**
* This AggregationData represents the last recorded value. This is useful
* when giving support to Gauges.
*/
export interface LastValueData extends AggregationMetadata {
type: AggregationType.LAST_VALUE;
/** The last recorded value */
value: number;
}
/** This AggregationData contains a histogram of the collected values. */
export interface DistributionData extends AggregationMetadata {
type: AggregationType.DISTRIBUTION;
/** The first timestamp a datapoint was added */
readonly startTime: number;
/** Get the total count of all recorded values in the histogram */
count: number;
/** Sum of all recorded values in the histogram */
sum: number;
/** Get the computed mean value of all recorded values in the histogram */
mean: number;
/**
* Get the computed standard deviation of all recorded values in the
* histogram
*/
stdDeviation: number;
/**
* Get the computed sum of squared deviations of all recorded values in the
* histogram.
*/
sumOfSquaredDeviation: number;
/** Bucket distribution of the histogram */
buckets: Bucket[];
/** Buckets count */
bucketCounts?: number[];
/** If the distribution does not have a histogram, then omit this field. */
exemplars?: StatsExemplar[];
}
/**
* Exemplars are example points that may be used to annotate aggregated
* Distribution values. They are metadata that gives information about a
* particular value added to a Distribution bucket.
*/
export interface StatsExemplar {
/**
* Value of the exemplar point. It determines which bucket the exemplar
* belongs to.
*/
readonly value: number;
/** The observation (sampling) time of the above value. */
readonly timestamp: number;
/** Contextual information about the example value. */
readonly attachments: {
[key: string]: string;
};
}
export declare type Bucket = number;
export declare type AggregationData = SumData | CountData | LastValueData | DistributionData;
export {};