@opencensus/core
- Version 0.1.0
- Published
- 385 kB
- 5 dependencies
- Apache-2.0 license
Install
npm i @opencensus/core
yarn add @opencensus/core
pnpm add @opencensus/core
Overview
OpenCensus is a toolkit for collecting application performance and behavior data.
Index
Variables
Functions
Classes
Interfaces
Span
- activeTraceParams
- addAnnotation()
- addAttribute()
- addLink()
- addMessageEvent()
- allDescendants()
- annotations
- attributes
- droppedAnnotationsCount
- droppedAttributesCount
- droppedLinksCount
- droppedMessageEventsCount
- duration
- end()
- ended
- endTime
- id
- isRootSpan()
- kind
- links
- logger
- messageEvents
- name
- numberOfChildren
- parentSpanId
- remoteParent
- setStatus()
- spanContext
- spans
- start()
- startChildSpan()
- started
- startTime
- status
- traceId
- tracer
- traceState
- truncate()
Enums
Type Aliases
Namespaces
Variables
variable DEFAULT_SAMPLING_RATE
const DEFAULT_SAMPLING_RATE: number;
The default sampler is a Probability sampler with the probability set to 1/10000.
variable DEFAULT_SPAN_MAX_NUM_ANNOTATIONS
const DEFAULT_SPAN_MAX_NUM_ANNOTATIONS: number;
Default Limit for Annotations per span
variable DEFAULT_SPAN_MAX_NUM_ATTRIBUTES
const DEFAULT_SPAN_MAX_NUM_ATTRIBUTES: number;
Default limit for Attributes per span
variable DEFAULT_SPAN_MAX_NUM_LINKS
const DEFAULT_SPAN_MAX_NUM_LINKS: number;
Default limit for Links per span
variable DEFAULT_SPAN_MAX_NUM_MESSAGE_EVENTS
const DEFAULT_SPAN_MAX_NUM_MESSAGE_EVENTS: number;
Default limit for Message events per span
variable EMPTY_TAG_MAP
const EMPTY_TAG_MAP: TagMap;
variable globalStats
const globalStats: Stats;
variable MAX_NUMBER_OF_TAGS
const MAX_NUMBER_OF_TAGS: number;
variable TAG_MAP_SERIALIZED_SIZE_LIMIT
const TAG_MAP_SERIALIZED_SIZE_LIMIT: number;
variable version
const version: string;
Copyright 2018, 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.
Functions
function clear
clear: (contextManager: CLS.Namespace) => void;
Clear the current tag context.
function deserializeBinary
deserializeBinary: (buffer: Buffer) => TagMap;
Deserializes input to TagMap based on the binary format standard.
Parameter buffer
The TagMap to deserialize.
function deserializeTextFormat
deserializeTextFormat: (str: string) => TagMap;
Deserializes input to TagMap based on the W3C HTTP text format standard.
Parameter str
The TagMap to deserialize.
function getCurrentTagContext
getCurrentTagContext: (contextManager: CLS.Namespace) => TagMap;
Gets the current tag context.
function serializeBinary
serializeBinary: (tagMap: TagMap) => Buffer;
Serializes a given TagMap to the on-the-wire format.
Parameter tagMap
The TagMap to serialize.
function serializeTextFormat
serializeTextFormat: (tagMap: TagMap) => string;
Serializes a given TagMap to the on-the-wire format based on the W3C HTTP text format standard.
Parameter tagMap
The TagMap to serialize.
function setCurrentTagContext
setCurrentTagContext: (contextManager: CLS.Namespace, tags: TagMap) => void;
Sets the current tag context.
Parameter tags
The TagMap.
function withTagContext
withTagContext: <T>( contextManager: CLS.Namespace, tags: TagMap, fn: CLS.Func<T>) => T;
Enters the scope of code where the given
TagMap
is in the current context (replacing the previousTagMap
).Parameter tags
The TagMap to be set to the current context.
Parameter fn
Callback function.
Returns
The callback return.
Classes
class AlwaysSampler
class AlwaysSampler implements Sampler {}
Sampler that samples every trace.
property description
readonly description: string;
method shouldSample
shouldSample: (traceId: string) => boolean;
class BasePlugin
abstract class BasePlugin implements types.Plugin {}
This class represent the base to patch plugin.
constructor
constructor(moduleName: string);
Constructs a new BasePlugin instance.
Parameter moduleName
The module name.
property basedir
protected basedir: string;
module directory - used to load internal files
property internalFileList
protected readonly internalFileList: types.PluginInternalFiles;
list of internal files that need patch and are not exported by default
property internalFilesExports
protected internalFilesExports: ModuleExportsMapping;
internal files loaded
property logger
protected logger: Logger;
a logger
property moduleExports
protected moduleExports: any;
Exports from the nodejs module to be instrumented
property moduleName
protected moduleName: string;
The module name
property options
protected options: types.PluginConfig;
plugin options
property stats
protected stats?: Stats;
A stats object.
property tracer
protected tracer: modelTypes.Tracer;
A tracer object.
property version
protected version: string;
The module version.
method applyPatch
protected abstract applyPatch: () => any;
This method implements the GoF Template Method Pattern, 'applyPatch' is the variant part, each instrumentation should implement its own version, 'enable' method is the invariant. It will be called when enable is called.
method applyUnpatch
protected abstract applyUnpatch: () => void;
method disable
disable: () => void;
Method to disable the instrumentation
method enable
enable: <T>( moduleExports: T, tracer: modelTypes.Tracer, version: string, options: types.PluginConfig, basedir?: string, stats?: Stats) => any;
Method that enables the instrumentation patch.
This method implements the GoF Template Method Pattern 'enable' is the invariant part of the pattern and 'applyPatch' the variant.
Parameter moduleExports
nodejs module exports from the module to patch
Parameter tracer
a tracer instance
Parameter version
version of the current instaled module to patch
Parameter options
plugin options
Parameter basedir
an optional module absolute path
Parameter stats
an optional stats instance
class BaseView
class BaseView implements View {}
A View specifies an aggregation and a set of tag keys. The aggregation will be broken down by the unique set of matching tag values for each measure.
constructor
constructor( name: string, measure: Measure, aggregation: AggregationType, tagsKeys: TagKey[], description: string, bucketBoundaries?: number[], logger?: typeof defaultLogger);
Creates a new View instance. This constructor is used by Stats. User should prefer using Stats.createView() instead.
Parameter name
The view name
Parameter measure
The view measure
Parameter aggregation
The view aggregation type
Parameter tagsKeys
The Tags' keys that view will have
Parameter description
The view description
Parameter bucketBoundaries
The view bucket boundaries for a distribution aggregation type
Parameter logger
property aggregation
readonly aggregation: AggregationType;
An Aggregation describes how data collected is aggregated. There are four aggregation types: count, sum, lastValue and distirbution.
property description
readonly description: string;
Describes the view, e.g. "RPC latency distribution"
property endTime
endTime?: number;
The end time for this view - represents the last time a value was recorded
property logger
logger: loggerTypes.Logger;
An object to log information to
property measure
readonly measure: Measure;
The Measure to which this view is applied.
property name
readonly name: string;
A string by which the View will be referred to, e.g. "rpc_latency". Names MUST be unique within the library.
property registered
registered: boolean;
true if the view was registered
property startTime
readonly startTime: number;
The start time for this view
method getColumns
getColumns: () => TagKey[];
Gets the view's tag keys
method getMetric
getMetric: (start: number) => Metric;
Gets view`s metric
Parameter start
The start timestamp in epoch milliseconds
Returns
The Metric.
method getSnapshot
getSnapshot: (tagValues: Array<TagValue | null>) => AggregationData;
Returns a snapshot of an AggregationData for that tags/labels values.
Parameter tags
The desired data's tags
Returns
The AggregationData.
method recordMeasurement
recordMeasurement: ( measurement: Measurement, tags: TagMap, attachments?: { [key: string]: string }) => void;
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.
Parameter measurement
The measurement to record
Parameter tags
The tags to which the value is applied
Parameter attachments
optional The contextual information associated with an example value. The contextual information is represented as key - value string pairs.
class BucketBoundaries
class BucketBoundaries {}
constructor
constructor(boundaries: number[], logger?: typeof defaultLogger);
property bucketCounts
readonly bucketCounts: number[];
property buckets
readonly buckets: number[];
method getBoundaries
getBoundaries: () => Bucket[];
Gets bucket boundaries
method getCounts
getCounts: () => number[];
Gets initial bucket counts
class ConsoleExporter
class ConsoleExporter implements Exporter {}
Format and sends span data to the console.
constructor
constructor(config: BufferConfig);
Constructs a new ConsoleExporter instance.
Parameter config
Exporter configuration object to create a console log exporter.
property logger
logger: loggerTypes.Logger;
Buffer object to store the spans.
method onEndSpan
onEndSpan: (span: modelTypes.Span) => void;
Event called when a span is ended.
Parameter span
Ended span.
method onStartSpan
onStartSpan: (span: modelTypes.Span) => void;
method publish
publish: (spans: modelTypes.Span[]) => Promise<void>;
Sends the spans information to the console.
Parameter spans
A list of spans to publish.
class ConsoleStatsExporter
class ConsoleStatsExporter implements StatsEventListener {}
Exporter that receives stats data and shows in the log console.
method onRecord
onRecord: ( views: View[], measurement: Measurement, tags: Map<TagKey, TagValue>) => void;
Event called when a measurement is recorded
Parameter view
recorded view from measurement
Parameter measurement
recorded measurement
Parameter tags
The tags to which the value is applied
method onRegisterView
onRegisterView: (view: View) => void;
Event called when a view is registered
Parameter view
registered view
method start
start: () => void;
Starts the Console exporter that polls Metric from Metrics library and shows in the log console..
method stop
stop: () => void;
Stops the exporter.
class CoreResource
class CoreResource {}
Resource represents a resource, which capture identifying information about the entities for which signals (stats or traces) are reported. It further provides a framework for detection of resource information from the environment and progressive population as signals propagate from the core instrumentation library to a backend's exporter.
method createFromEnvironmentVariables
static createFromEnvironmentVariables: () => Resource;
Returns a Resource. This resource information is loaded from the OC_RESOURCE_TYPE and OC_RESOURCE_LABELS environment variables.
Returns
The resource.
method mergeResources
static mergeResources: (resources: Resource[]) => Resource;
Returns a Resource that runs all input resources sequentially and merges their results. In case a type of label key is already set, the first set value takes precedence.
Parameter resources
The list of the resources.
Returns
The resource.
method setup
static setup: () => void;
TEST_ONLY
class CoreTracer
class CoreTracer extends CoreTracerBase implements types.Tracer {}
This class represents a tracer with Continuation Local Storage (CLS).
CLS helps keep tracking the root span over function calls automatically. It is capable of storing, propagating and retrieving arbitrary continuation-local data (also called "context"). CLS comes with some performance overhead, you can read more about it here: https://github.com/othiym23/node-continuation-local-storage/issues/59
constructor
constructor();
Constructs a new TraceImpl instance.
property currentRootSpan
currentRootSpan: types.Span;
Gets the current root span.
method clearCurrentTrace
clearCurrentTrace: () => void;
Clears the current root span.
method onEndSpan
onEndSpan: (span: types.Span) => void;
Notifies listeners of the span end.
method onStartSpan
onStartSpan: (span: types.Span) => void;
Notifies listeners of the span start.
method setCurrentRootSpan
setCurrentRootSpan: (root: types.Span) => void;
Sets the current root span.
method startChildSpan
startChildSpan: (options?: types.SpanOptions) => types.Span;
Starts a span.
Parameter options
A SpanOptions object to start a child span.
method startRootSpan
startRootSpan: <T>( options: types.TraceOptions, fn: (root: types.Span) => T) => T;
Starts a root span.
Parameter options
A TraceOptions object to start a root span.
Parameter fn
A callback function to run after starting a root span.
method wrap
wrap: <T>(fn: types.Func<T>) => types.Func<T>;
Binds the trace context to the given function. This is necessary in order to create child spans correctly in functions that are called asynchronously (for example, in a network response handler).
Parameter fn
A function to which to bind the trace context.
method wrapEmitter
wrapEmitter: (emitter: NodeJS.EventEmitter) => void;
Binds the trace context to the given event emitter. This is necessary in order to create child spans correctly in event handlers.
Parameter emitter
An event emitter whose handlers should have the trace context binded to them.
class CoreTracerBase
class CoreTracerBase implements types.TracerBase {}
This class represents a tracer.
constructor
constructor();
Constructs a new TraceImpl instance.
property active
readonly active: boolean;
Indicates if the tracer is active or not.
property activeTraceParams
activeTraceParams: configTypes.TraceParams;
A configuration object for trace parameters
property eventListeners
readonly eventListeners: types.SpanEventListener[];
Gets the list of event listeners.
property logger
logger: loggerTypes.Logger;
An object to log information
property propagation
readonly propagation: Propagation;
A propagation instance
property sampler
sampler: samplerTypes.Sampler;
A sampler used to make sample decisions
method onEndSpan
onEndSpan: (span: types.Span) => void;
Notifies listeners of the span end.
method onStartSpan
onStartSpan: (span: types.Span) => void;
Notifies listeners of the span start.
method registerSpanEventListener
registerSpanEventListener: (listener: types.SpanEventListener) => void;
Registers an end span event listener.
Parameter listener
The listener to register.
method setCurrentRootSpan
setCurrentRootSpan: (root: types.Span) => void;
Sets the current root span.
method start
start: (config: configTypes.TracerConfig) => this;
Starts a tracer.
Parameter config
A tracer configuration object to start a tracer.
method startChildSpan
startChildSpan: (options?: types.SpanOptions) => types.Span;
Starts a span.
Parameter options
A SpanOptions object to start a child span.
method startRootSpan
startRootSpan: <T>( options: types.TraceOptions, fn: (root: types.Span) => T) => T;
Starts a root span.
Parameter options
A TraceOptions object to start a root span.
Parameter fn
A callback function to run after starting a root span.
method stop
stop: () => this;
Stops the tracer.
method unregisterSpanEventListener
unregisterSpanEventListener: (listener: types.SpanEventListener) => void;
Unregisters an end span event listener.
Parameter listener
The listener to unregister.
class Cumulative
class Cumulative implements Meter {}
Cumulative metric is used to record aggregated metrics that represents a single numerical value accumulated over a time interval. The value can only increase or be reset to zero on restart or reset the event.
constructor
constructor( name: string, description: string, unit: string, type: MetricDescriptorType, labelKeys: LabelKey[], constantLabels: Map<LabelKey, LabelValue>);
Constructs a new Cumulative instance.
Parameter name
The name of the metric.
Parameter description
The description of the metric.
Parameter unit
The unit of the metric.
Parameter type
The type of metric.
Parameter labelKeys
The list of the label keys.
Parameter constantLabels
The map of constant labels for the Metric.
property constantLabels
readonly constantLabels: Map<LabelKey, LabelValue>;
property labelKeys
readonly labelKeys: LabelKey[];
method clear
clear: () => void;
Removes all TimeSeries from the cumulative metric. i.e. references to all previous Point objects are invalid (not part of the metric).
method getDefaultTimeSeries
getDefaultTimeSeries: () => CumulativePoint;
Returns a Point for a cumulative with all labels not set, or default labels.
Returns
The value of single cumulative.
method getMetric
getMetric: () => Metric | null;
Provides a Metric with one or more TimeSeries.
Returns
The Metric, or null if TimeSeries is not present in Metric.
method getOrCreateTimeSeries
getOrCreateTimeSeries: (labelValues: LabelValue[]) => CumulativePoint;
Creates a TimeSeries and returns a Point if the specified labelValues is not already associated with this cumulative, else returns an existing Point.
It is recommended to keep a reference to the Point instead of always calling this method for manual operations.
Parameter labelValues
The list of the label values.
Returns
The value of single cumulative.
method removeTimeSeries
removeTimeSeries: (labelValues: LabelValue[]) => void;
Removes the TimeSeries from the cumulative metric, if it is present. i.e. references to previous Point objects are invalid (not part of the metric).
Parameter labelValues
The list of label values.
class CumulativePointEntry
class CumulativePointEntry implements CumulativePoint {}
The value of a single point in the Cumulative.TimeSeries.
constructor
constructor(labelValues: LabelValue[]);
method getTimeSeries
getTimeSeries: (now: Timestamp) => TimeSeries;
Returns the TimeSeries with one or more Point.
Parameter now
The time at which the cumulative is recorded.
Returns
The TimeSeries.
method inc
inc: (val?: number) => void;
Increment the cumulative metric.
Parameter val
The new value.
method reset
reset: () => void;
Reset cumulative metric.
class DerivedCumulative
class DerivedCumulative implements Meter {}
DerivedCumulative metric is used to record aggregated metrics that represents a single numerical value accumulated over a time interval.
constructor
constructor( name: string, description: string, unit: string, type: MetricDescriptorType, labelKeys: LabelKey[], constantLabels: Map<LabelKey, LabelValue>, startTime: Timestamp);
Constructs a new DerivedCumulative instance.
Parameter name
The name of the metric.
Parameter description
The description of the metric.
Parameter unit
The unit of the metric.
Parameter type
The type of metric.
Parameter labelKeys
The list of the label keys.
Parameter constantLabels
The map of constant labels for the Metric.
Parameter startTime
The time when the cumulative metric start measuring the value.
property constantLabels
readonly constantLabels: Map<LabelKey, LabelValue>;
method clear
clear: () => void;
Removes all TimeSeries from the cumulative metric. i.e. references to all previous Point objects are invalid (not part of the metric).
method createTimeSeries
createTimeSeries: ( labelValues: LabelValue[], objOrFn: AccessorInterface) => void;
Creates a TimeSeries. The value of a single point in the TimeSeries is observed from an object or function. The ValueExtractor is invoked whenever metrics are collected, meaning the reported value is up-to-date.
Parameter labelValues
The list of the label values.
Parameter objOrFn
obj The obj to get the size or length or value from. If multiple options are available, the value (ToValueInterface) takes precedence first, followed by length and size. e.g value -> length -> size. fn is the function that will be called to get the current value of the cumulative.
method getMetric
getMetric: () => Metric | null;
Provides a Metric with one or more TimeSeries.
Returns
The Metric, or null if TimeSeries is not present in Metric.
method removeTimeSeries
removeTimeSeries: (labelValues: LabelValue[]) => void;
Removes the TimeSeries from the cumulative metric, if it is present. i.e. references to previous Point objects are invalid (not part of the metric).
Parameter labelValues
The list of label values.
class DerivedGauge
class DerivedGauge implements types.Meter {}
DerivedGauge metric
constructor
constructor( name: string, description: string, unit: string, type: MetricDescriptorType, labelKeys: LabelKey[], constantLabels: Map<LabelKey, LabelValue>);
Constructs a new DerivedGauge instance.
Parameter name
The name of the metric.
Parameter description
The description of the metric.
Parameter unit
The unit of the metric.
Parameter type
The type of metric.
Parameter labelKeys
The list of the label keys.
Parameter constantLabels
The map of constant labels for the Metric.
property constantLabels
readonly constantLabels: Map<LabelKey, LabelValue>;
method clear
clear: () => void;
Removes all TimeSeries from the gauge metric. i.e. references to all previous Point objects are invalid (not part of the metric).
method createTimeSeries
createTimeSeries: ( labelValues: LabelValue[], objOrFn: AccessorInterface) => void;
Creates a TimeSeries. The value of a single point in the TimeSeries is observed from a obj or a function. The ValueExtractor is invoked whenever metrics are collected, meaning the reported value is up-to-date.
Parameter labelValues
The list of the label values.
Parameter objOrFn
obj The obj to get the size or length or value from. If multiple options are available, the value (ToValueInterface) takes precedence first, followed by length and size. e.g value -> length -> size. fn is the function that will be called to get the current value of the gauge.
method getMetric
getMetric: () => Metric | null;
Provides a Metric with one or more TimeSeries.
Returns
The Metric, or null if TimeSeries is not present in Metric.
method removeTimeSeries
removeTimeSeries: (labelValues: LabelValue[]) => void;
Removes the TimeSeries from the gauge metric, if it is present. i.e. references to previous Point objects are invalid (not part of the metric).
Parameter labelValues
The list of label values.
class ExporterBuffer
class ExporterBuffer {}
Controls the sending of traces to exporters.
constructor
constructor(exporter: types.Exporter, config: configTypes.BufferConfig);
Constructs a new Buffer instance.
Parameter exporter
The service to send the collected spans.
Parameter config
A buffer configuration object to create a buffer.
method addToBuffer
addToBuffer: (span: modelTypes.Span) => this;
Add a span in the buffer.
Parameter span
Span to be added in the buffer.
method getBufferSize
getBufferSize: () => number;
method getQueue
getQueue: () => modelTypes.Span[];
method setBufferSize
setBufferSize: (bufferSize: number) => this;
Set the buffer size value.
Parameter bufferSize
The new buffer size.
class Gauge
class Gauge implements Meter {}
Gauge metric
constructor
constructor( name: string, description: string, unit: string, type: MetricDescriptorType, labelKeys: LabelKey[], constantLabels: Map<LabelKey, LabelValue>);
Constructs a new Gauge instance.
Parameter name
The name of the metric.
Parameter description
The description of the metric.
Parameter unit
The unit of the metric.
Parameter type
The type of metric.
Parameter labelKeys
The list of the label keys.
Parameter constantLabels
The map of constant labels for the Metric.
property constantLabels
readonly constantLabels: Map<LabelKey, LabelValue>;
property labelKeys
readonly labelKeys: LabelKey[];
method clear
clear: () => void;
Removes all TimeSeries from the gauge metric. i.e. references to all previous Point objects are invalid (not part of the metric).
method getDefaultTimeSeries
getDefaultTimeSeries: () => types.Point;
Returns a Point for a gauge with all labels not set, or default labels.
Returns
The value of single gauge.
method getMetric
getMetric: () => Metric | null;
Provides a Metric with one or more TimeSeries.
Returns
The Metric, or null if TimeSeries is not present in Metric.
method getOrCreateTimeSeries
getOrCreateTimeSeries: (labelValues: LabelValue[]) => types.Point;
Creates a TimeSeries and returns a Point if the specified labelValues is not already associated with this gauge, else returns an existing Point.
It is recommended to keep a reference to the Point instead of always calling this method for manual operations.
Parameter labelValues
The list of the label values.
Returns
The value of single gauge.
method removeTimeSeries
removeTimeSeries: (labelValues: LabelValue[]) => void;
Removes the TimeSeries from the gauge metric, if it is present. i.e. references to previous Point objects are invalid (not part of the metric).
Parameter labelValues
The list of label values.
class MetricRegistry
class MetricRegistry {}
Creates and manages application's set of metrics.
constructor
constructor();
method addDerivedDoubleCumulative
addDerivedDoubleCumulative: ( name: string, options?: MetricOptions) => DerivedCumulative;
Builds a new derived Double Cumulative to be added to the registry.
Parameter name
The name of the metric.
Parameter options
The options for the metric.
Returns
A Double DerivedCumulative metric.
method addDerivedDoubleGauge
addDerivedDoubleGauge: (name: string, options?: MetricOptions) => DerivedGauge;
Builds a new derived double gauge to be added to the registry. This is more convenient form when you want to manually increase and decrease values as per your service requirements.
Parameter name
The name of the metric.
Parameter options
The options for the metric.
Returns
A Double DerivedGauge metric.
method addDerivedInt64Cumulative
addDerivedInt64Cumulative: ( name: string, options?: MetricOptions) => DerivedCumulative;
Builds a new derived Int64 Cumulative to be added to the registry.
Parameter name
The name of the metric.
Parameter options
The options for the metric.
Returns
A Int64 DerivedCumulative metric.
method addDerivedInt64Gauge
addDerivedInt64Gauge: (name: string, options?: MetricOptions) => DerivedGauge;
Builds a new derived Int64 gauge to be added to the registry. This is more convenient form when you want to manually increase and decrease values as per your service requirements.
Parameter name
The name of the metric.
Parameter options
The options for the metric.
Returns
A Int64 DerivedGauge metric.
method addDoubleCumulative
addDoubleCumulative: (name: string, options?: MetricOptions) => Cumulative;
Builds a new double cumulative to be added to the registry. This API is useful when you want to manually increase and reset values as per service requirements.
Parameter name
The name of the metric.
Parameter options
The options for the metric.
Returns
A Double Cumulative metric.
method addDoubleGauge
addDoubleGauge: (name: string, options?: MetricOptions) => Gauge;
Builds a new double gauge to be added to the registry. This is more convenient form when you want to manually increase and decrease values as per your service requirements.
Parameter name
The name of the metric.
Parameter options
The options for the metric.
Returns
A Double Gauge metric.
method addInt64Cumulative
addInt64Cumulative: (name: string, options?: MetricOptions) => Cumulative;
Builds a new Int64 cumulative to be added to the registry. This API is useful when you want to manually increase and reset values as per service requirements.
Parameter name
The name of the metric.
Parameter options
The options for the metric.
Returns
A Int64 Cumulative metric.
method addInt64Gauge
addInt64Gauge: (name: string, options?: MetricOptions) => Gauge;
Builds a new Int64 gauge to be added to the registry. This is more convenient form when you want to manually increase and decrease values as per your service requirements.
Parameter name
The name of the metric.
Parameter options
The options for the metric.
Returns
A Int64 Gauge metric.
method getMetricProducer
getMetricProducer: () => MetricProducer;
Gets a metric producer for registry.
Returns
The metric producer.
class Metrics
class Metrics {}
Class for accessing the default MetricsComponent.
method getMetricProducerManager
static getMetricProducerManager: () => MetricProducerManager;
{MetricProducerManager} The global MetricProducerManager.
method getMetricRegistry
static getMetricRegistry: () => MetricRegistry;
{MetricRegistry} The global MetricRegistry.
class MetricUtils
class MetricUtils {}
Utils to convert Stats data models to Metric data models
method tagValuesToLabelValues
static tagValuesToLabelValues: ( tagValues: Array<TagValue | null>) => LabelValue[];
Converts tag values to label values.
Parameter tagValues
the list of tag values
Returns
The List of label values
method viewToMetricDescriptor
static viewToMetricDescriptor: (view: View) => MetricDescriptor;
Gets a MetricDescriptor for given view.
Parameter view
The view for which to build a metric descriptor
Returns
The MetricDescriptor.
class NeverSampler
class NeverSampler implements Sampler {}
Sampler that samples no traces.
property description
readonly description: string;
method shouldSample
shouldSample: (traceId: string) => boolean;
class NoopExporter
class NoopExporter implements Exporter {}
Do not send span data
property logger
logger?: loggerTypes.Logger;
method onEndSpan
onEndSpan: (span: modelTypes.Span) => void;
method onStartSpan
onStartSpan: (span: modelTypes.Span) => void;
method publish
publish: (spans: modelTypes.Span[]) => Promise<void>;
class PointEntry
class PointEntry implements types.Point {}
The value of a single point in the Gauge.TimeSeries.
constructor
constructor(labelValues: LabelValue[]);
method add
add: (amt: number) => void;
Adds the given value to the current value. The values can be negative.
Parameter amt
The value to add.
method getTimeSeries
getTimeSeries: (timestamp: Timestamp) => TimeSeries;
Returns the TimeSeries with one or more Point.
Parameter timestamp
The time at which the gauge is recorded.
Returns
The TimeSeries.
method set
set: (val: number) => void;
Sets the given value.
Parameter val
The new value.
class ProbabilitySampler
class ProbabilitySampler implements Sampler {}
Sampler that samples a given fraction of traces.
constructor
constructor(probability: number);
Constructs a new Probability Sampler instance.
property description
readonly description: string;
method shouldSample
shouldSample: (traceId: string) => boolean;
Checks if trace belong the sample.
Parameter traceId
Used to check the probability
Returns
a boolean. True if the traceId is in probability False if the traceId is not in probability.
class Recorder
class Recorder {}
method addMeasurement
static addMeasurement: ( aggregationData: AggregationData, measurement: Measurement, attachments?: { [key: string]: string }) => AggregationData;
method getTagValues
static getTagValues: ( tags: Map<TagKey, TagValue>, columns: TagKey[]) => Array<TagValue | null>;
Gets the tag values from tags and columns
class SamplerBuilder
class SamplerBuilder {}
Builder class of Samplers
method getSampler
static getSampler: (probability: number) => Sampler;
If probability parameter is bigger then 1 return AlwaysSampler instance. If probability parameter is less than 0 returns NeverSampler instance. Else returns a Probability Sampler
Parameter probability
probability between 0 and 1
Returns
a Sampler object
class TagMap
class TagMap {}
TagMap is maps of TagKey -> TagValueWithMetadata
property tags
readonly tags: Map<TagKey, TagValue>;
Gets the tags map without metadata.
property tagsWithMetadata
readonly tagsWithMetadata: Map<TagKey, TagValueWithMetadata>;
Gets the tags map with metadata.
method delete
delete: (tagKey: TagKey) => void;
Deletes a tag from the map if the key is in the map.
Parameter tagKey
The TagKey which will be removed.
method set
set: (tagKey: TagKey, tagValue: TagValue, tagMetadata?: TagMetadata) => void;
Adds the key/value pair regardless of whether the key is present.
Parameter tagKey
The TagKey which will be set.
Parameter tagValue
The TagValue to set for the given key.
Parameter tagMetadata
The TagMetadata associated with this Tag.
class TraceParamsBuilder
class TraceParamsBuilder {}
Builder Class of TraceParams
method getNumberOfAnnotationEventsPerSpan
static getNumberOfAnnotationEventsPerSpan: ( traceParameters: TraceParams) => number;
method getNumberOfAttributesPerSpan
static getNumberOfAttributesPerSpan: (traceParameters: TraceParams) => number;
method getNumberOfLinksPerSpan
static getNumberOfLinksPerSpan: (traceParameters: TraceParams) => number;
method getNumberOfMessageEventsPerSpan
static getNumberOfMessageEventsPerSpan: (traceParameters: TraceParams) => number;
Interfaces
interface AccessorFunction
interface AccessorFunction {}
call signature
(): number;
interface AggregationMetadata
interface AggregationMetadata {}
Defines how data is collected and aggregated
interface Annotation
interface Annotation {}
A text annotation with a set of attributes.
property attributes
attributes: Attributes;
A set of attributes on the annotation.
property description
description: string;
A user-supplied message describing the event.
property timestamp
timestamp: number;
A timestamp for the event event.
interface Attributes
interface Attributes {}
Maps a label to a string, number or boolean.
index signature
[attributeKey: string]: string | number | boolean;
interface BucketOptions
interface BucketOptions {}
Properties of a BucketOptions. A Distribution may optionally contain a histogram of the values in the population. The bucket boundaries for that histogram are described by BucketOptions.
If bucket_options has no type, then there is no histogram associated with the Distribution.
property explicit
readonly explicit: Explicit;
Bucket with explicit bounds.
interface BufferConfig
interface BufferConfig {}
Interface configuration for a buffer.
property bufferSize
bufferSize?: number;
Maximum size of a buffer.
property bufferTimeout
bufferTimeout?: number;
Max time for a buffer can wait before being sent
property logger
logger?: Logger;
A logger object
interface CountData
interface CountData extends AggregationMetadata {}
This AggregationData counts the number of measurements recorded.
interface CumulativePoint
interface CumulativePoint {}
method getTimeSeries
getTimeSeries: (now: Timestamp) => TimeSeries;
Returns the TimeSeries with one or more Point.
Parameter now
The time at which the cumulative is recorded.
Returns
The TimeSeries.
method inc
inc: (val?: number) => void;
Increment the cumulative metric.
Parameter val
The new value.
method reset
reset: () => void;
Reset cumulative metric.
interface CustomAttributeFunction
interface CustomAttributeFunction {}
Function that can be provided to plugin in order to add custom attributes to spans
call signature
(span: Span, ...rest: any[]): void;
interface DistributionBucket
interface Bucket {}
Properties of a Bucket.
interface DistributionData
interface DistributionData extends AggregationMetadata {}
This AggregationData contains a histogram of the collected values.
property bucketCounts
bucketCounts?: number[];
Buckets count
property buckets
buckets: Bucket[];
Bucket distribution of the histogram
property count
count: number;
Get the total count of all recorded values in the histogram
property exemplars
exemplars?: StatsExemplar[];
If the distribution does not have a histogram, then omit this field.
property mean
mean: number;
Get the computed mean value of all recorded values in the histogram
property startTime
readonly startTime: number;
The first timestamp a datapoint was added
property stdDeviation
stdDeviation: number;
Get the computed standard deviation of all recorded values in the histogram
property sum
sum: number;
Sum of all recorded values in the histogram
property sumOfSquaredDeviation
sumOfSquaredDeviation: number;
Get the computed sum of squared deviations of all recorded values in the histogram.
property type
type: AggregationType.DISTRIBUTION;
interface DistributionValue
interface DistributionValue {}
Distribution contains summary statistics for a population of values. It optionally contains a histogram representing the distribution of those values across a set of buckets.
property bucketOptions
readonly bucketOptions: BucketOptions;
Don't change bucket boundaries within a TimeSeries if your backend doesn't support this. To save network bandwidth this field can be sent only the first time a metric is sent when using a streaming RPC.
property buckets
readonly buckets: Bucket[];
DistributionValue buckets
property count
readonly count: number;
The number of values in the population. Must be non-negative. This value must equal the sum of the values in bucket_counts if a histogram is provided.
property sum
readonly sum: number;
The sum of the values in the population. If count is zero then this field must be zero.
property sumOfSquaredDeviation
readonly sumOfSquaredDeviation: number;
The sum of squared deviations from the mean of the values in the population. For values x_i this is:
Sum[i=1..n]((x_i - mean)^2)
Knuth, "The Art of Computer Programming", Vol. 2, page 323, 3rd edition describes Welford's method for accumulating this sum in one pass.
If count is zero then this field must be zero.
interface Exemplar
interface Exemplar {}
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.
property attachments
readonly attachments: { [key: string]: string;};
Contextual information about the example value.
property timestamp
readonly timestamp: Timestamp;
The observation (sampling) time of the above value.
property value
readonly value: number;
Value of the exemplar point. It determines which bucket the exemplar belongs to.
interface Explicit
interface Explicit {}
Properties of an Explicit. Specifies a set of buckets with arbitrary upper-bounds. This defines size(bounds) + 1 (= N) buckets. The boundaries for bucket index i are:
[0, bucket_bounds[i]) for i == 0 [bucket_bounds[i-1], bucket_bounds[i]) for 0 < i < N-1 [bucket_bounds[i-1], +infinity) for i == N-1
property bounds
readonly bounds: number[];
The values must be strictly increasing and > 0.
interface Exporter
interface Exporter extends modelTypes.SpanEventListener {}
Defines a trace exporter interface.
method publish
publish: (spans: modelTypes.Span[]) => Promise<number | string | void>;
Sends a list of spans to the service.
Parameter spans
A list of spans to publish.
interface HeaderGetter
interface HeaderGetter {}
An transport and environment neutral API for getting request headers.
method getHeader
getHeader: (name: string) => string | string[] | undefined;
interface HeaderSetter
interface HeaderSetter {}
A transport and environment neutral API for setting headers.
method setHeader
setHeader: (name: string, value: string) => void;
interface LabelKey
interface LabelKey {}
Properties of a LabelKey associated with a MetricDescriptor.
property description
readonly description: string;
A human-readable description of what this label key represents.
property key
readonly key: string;
The key for the label.
interface Labels
interface Labels {}
Labels are maps of keys -> values
index signature
[key: string]: string;
interface LabelValue
interface LabelValue {}
The LabelValue type. null value indicates an unset.
property value
readonly value: string | null;
The value for the label.
interface LastValueData
interface LastValueData extends AggregationMetadata {}
This AggregationData represents the last recorded value. This is useful when giving support to Gauges.
interface LengthAttributeInterface
interface LengthAttributeInterface {}
Interface for objects with "length" attribute (e.g. Array).
property length
length: number;
interface LengthMethodInterface
interface LengthMethodInterface {}
Interface for objects with "length()" method.
method length
length: () => number;
interface Link
interface Link {}
A pointer from the current span to another span in the same trace or in a different trace.
property attributes
attributes: Attributes;
A set of attributes on the link.
property spanId
spanId: string;
The span ID for a span within a trace.
property traceId
traceId: string;
The trace ID for a trace within a project.
property type
type: LinkType;
The relationship of the current span relative to the linked.
interface Logger
interface Logger {}
Defines a logger interface.
interface LoggerOptions
interface LoggerOptions {}
Defines a logger options interface.
property level
level?: string;
interface Measure
interface Measure {}
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.
property description
readonly description?: string;
Describes the measure, e.g. "RPC latency in seconds".
property name
readonly name: string;
A string by which the measure will be referred to, e.g. "rpc_server_latency". Names MUST be unique within the library.
property type
readonly type: MeasureType;
The type used for this Measure.
property unit
readonly unit: MeasureUnit;
Describes the unit used for the Measure. Follows the format described by http://unitsofmeasure.org/ucum.html.
interface Measurement
interface Measurement {}
Describes a data point to be collected for a Measure.
interface MessageEvent
interface MessageEvent {}
An event describing a message sent/received between Spans.
property compressedSize
compressedSize?: number;
The number of compressed bytes sent or received. If zero or undefined, assumed to be the same size as uncompressed.
property id
id: number;
An identifier for the MessageEvent's message that can be used to match SENT and RECEIVED MessageEvents. Message event ids should start with 1 for both sent and received messages and increment by 1 for each message sent/received.
property timestamp
timestamp: number;
A timestamp for the event.
property type
type: MessageEventType;
Indicates whether the message was sent or received.
property uncompressedSize
uncompressedSize?: number;
The number of uncompressed bytes sent or received.
interface Meter
interface Meter {}
Provides a Metric with one or more TimeSeries
method getMetric
getMetric: () => Metric | null;
Provides a Metric with one or more TimeSeries.
Returns
The Metric, or null if TimeSeries is not present in Metric.
interface Metric
interface Metric {}
Properties of a Metric which has one or more timeseries
property descriptor
readonly descriptor: MetricDescriptor;
The descriptor of the Metric. This is an optimization for network wire size, from data-model perspective a Metric contains always a MetricDescriptor. In case of a streaming RPC can be sent only the first time a metric is reported to save network traffic.
property timeseries
readonly timeseries: TimeSeries[];
One or more timeseries for a single metric, where each timeseries has one or more points.
interface MetricDescriptor
interface MetricDescriptor {}
Properties of a Metric type and its schema
property description
readonly description: string;
A detailed description of the metric, which can be used in documentation.
property labelKeys
readonly labelKeys: LabelKey[];
The label keys associated with the metric descriptor.
property name
readonly name: string;
The metric type, including its DNS name prefix. It must be unique.
property type
readonly type: MetricDescriptorType;
MetricDescriptor type
property unit
readonly unit: string;
The unit in which the metric value is reported. Follows the format described by http://unitsofmeasure.org/ucum.html.
interface MetricOptions
interface MetricOptions {}
Options for every metric added to the MetricRegistry.
property constantLabels
readonly constantLabels?: Map<LabelKey, LabelValue>;
The map of constant labels for the Metric.
property description
readonly description?: string;
The description of the metric.
property labelKeys
readonly labelKeys?: LabelKey[];
The list of the label keys.
property unit
readonly unit?: MeasureUnit;
The unit of the metric.
interface MetricProducer
interface MetricProducer {}
A MetricProducer producer that can be registered for exporting using MetricProducerManager.
method getMetrics
getMetrics: () => Metric[];
Gets a collection of produced Metric`s to be exported
interface MetricProducerManager
interface MetricProducerManager {}
Keeps a set of MetricProducer that is used by exporters to determine the metrics that need to be exported.
method add
add: (metricProducer: MetricProducer) => void;
Adds the MetricProducer to the manager
method getAllMetricProducer
getAllMetricProducer: () => Set<MetricProducer>;
Gets all registered MetricProducers that should be exported
method remove
remove: (metricProducer: MetricProducer) => void;
Removes the MetricProducer to the manager
method removeAll
removeAll: () => void;
Clears all MetricProducers
interface ModuleExportsMapping
interface ModuleExportsMapping {}
Maps a name (key) representing a internal file module and its exports
index signature
[key: string]: any;
interface NamedPluginConfig
interface NamedPluginConfig {}
interface Plugin
interface Plugin {}
Interface Plugin to apply patch.
method disable
disable: () => void;
Method to disable the instrumentation
method enable
enable: <T>( moduleExports: T, tracer: TracerBase, version: string, options: PluginConfig, basedir?: string, stats?: Stats) => T;
Method that enables the instrumentation patch.
Parameter moduleExports
nodejs module exports from the module to patch
Parameter tracer
a tracer instance
Parameter version
version of the current instaled module to patch
Parameter options
plugin options
Parameter basedir
an optional module absolute path
Parameter stats
an optional stats instance
interface PluginConfig
interface PluginConfig {}
property applyCustomAttributesOnSpan
applyCustomAttributesOnSpan?: CustomAttributeFunction;
index signature
[key: string]: any;
interface PluginInternalFiles
interface PluginInternalFiles {}
Each key should be the name of the module to trace, and its value a mapping of a property name to a internal plugin file name.
index signature
[versions: string]: PluginInternalFilesVersion;
interface PluginInternalFilesVersion
interface PluginInternalFilesVersion {}
index signature
[pluginName: string]: string;
interface PluginNames
interface PluginNames {}
Type PluginNames: each key should be the name of the module to trace, and its value should be the name of the package which has the plugin implementation.
index signature
[pluginName: string]: string | NamedPluginConfig;
interface Point
interface Point {}
method add
add: (amt: number) => void;
Adds the given value to the current value. The values can be negative.
Parameter amt
The value to add.
method getTimeSeries
getTimeSeries: (timestamp: Timestamp) => TimeSeries;
Returns the TimeSeries with one or more Point.
Parameter timestamp
The time at which the gauge is recorded.
Returns
The TimeSeries.
method set
set: (val: number) => void;
Sets the given value.
Parameter val
The new value.
interface Propagation
interface Propagation {}
Propagation interface
interface Resource
interface Resource {}
A Resource describes the entity for which a signal was collected.
interface Sampler
interface Sampler {}
This interface represent a sampler .
property description
readonly description: string;
A string that uniquely describes the sampling behavior of this instance.
method shouldSample
shouldSample: (traceId: string) => boolean;
Checks if trace belong the sample.
Parameter traceId
Used to check the probability.
Returns
a boolean. True if the traceId is in probability False if the traceId is not in probability.
interface SizeAttributeInterface
interface SizeAttributeInterface {}
Interface for objects with "size" attribute (e.g. Map, Set).
property size
size: number;
interface SizeMethodInterface
interface SizeMethodInterface {}
Interface for objects with "size" method.
method size
size: () => number;
interface Snapshot
interface Snapshot {}
The values in this message can be reset at arbitrary unknown times, with the requirement that all of them are reset at the same time.
property count
readonly count: number;
The number of values in the snapshot. Optional since some systems don't expose this.
property percentileValues
readonly percentileValues: ValueAtPercentile[];
A list of values at different percentiles of the distribution calculated from the current snapshot. The percentiles must be strictly increasing.
property sum
readonly sum: number;
The sum of values in the snapshot. Optional since some systems don't expose this. If count is zero then this field must be zero or not set (if not supported).
interface Span
interface Span {}
Interface for Span
property activeTraceParams
activeTraceParams: configTypes.TraceParams;
Trace Parameters
property annotations
annotations: Annotation[];
A text annotation with a set of attributes.
property attributes
attributes: Attributes;
A set of attributes, each in the format [KEY]:[VALUE]
property droppedAnnotationsCount
droppedAnnotationsCount: number;
The number of dropped annotations.
property droppedAttributesCount
droppedAttributesCount: number;
The number of dropped attributes.
property droppedLinksCount
droppedLinksCount: number;
The number of dropped links.
property droppedMessageEventsCount
droppedMessageEventsCount: number;
The number of dropped message events.
property duration
readonly duration: number;
Gives a timestap that indicates the span's duration in RFC3339 UTC "Zulu" format.
property ended
readonly ended: boolean;
Indicates if span was ended.
property endTime
readonly endTime: Date;
Gives a timestap that indicates the span's end time in RFC3339 UTC "Zulu" format.
property id
readonly id: string;
The Span ID of this span
property kind
kind: SpanKind;
Kind of span.
property links
links: Link[];
Pointers from the current span to another span
property logger
logger: loggerTypes.Logger;
An object to log information to
property messageEvents
messageEvents: MessageEvent[];
An event describing a message sent/received between Spans.
property name
name: string;
The resource name of the span
property numberOfChildren
numberOfChildren: number;
The number of direct children
property parentSpanId
parentSpanId: string;
The span ID of this span's parent. If it's a root span, must be empty
property remoteParent
remoteParent: boolean;
If the parent span is in another process.
property spanContext
readonly spanContext: SpanContext;
Gives the TraceContext of the span.
property spans
spans: Span[];
The list of immediate child spans.
property started
readonly started: boolean;
Indicates if span was started.
property startTime
readonly startTime: Date;
Gives a timestap that indicates the span's start time in RFC3339 UTC "Zulu" format.
property status
status: Status;
A final status for this span
property traceId
readonly traceId: string;
Trace id asscoiated with span.
property tracer
tracer: TracerBase;
A tracer object, exposong the tracer makes it possible to create child spans from the span instance like. span.tracer.startChildSpan()
property traceState
readonly traceState?: TraceState;
Trace state associated with span
method addAnnotation
addAnnotation: ( description: string, attributes?: Attributes, timestamp?: number) => void;
Adds an annotation to the span.
Parameter description
Describes the event.
Parameter attributes
A set of attributes on the annotation.
Parameter timestamp
A timestamp for this event.
method addAttribute
addAttribute: (key: string, value: string | number | boolean | object) => void;
Adds an atribute to the span.
Parameter key
Describes the value added.
Parameter value
The result of an operation.
method addLink
addLink: ( traceId: string, spanId: string, type: LinkType, attributes?: Attributes) => void;
Adds a link to the span.
Parameter traceId
The trace ID for a trace within a project.
Parameter spanId
The span ID for a span within a trace.
Parameter type
The relationship of the current span relative to the linked.
Parameter attributes
A set of attributes on the link.
method addMessageEvent
addMessageEvent: ( type: MessageEventType, id: number, timestamp?: number, uncompressedSize?: number, compressedSize?: number) => void;
Adds a message event to the span.
Parameter type
The type of message event.
Parameter id
An identifier for the message event.
Parameter timestamp
A timestamp for this event.
Parameter uncompressedSize
The number of uncompressed bytes sent or received.
Parameter compressedSize
The number of compressed bytes sent or received. If zero or undefined, assumed to be the same size as uncompressed.
method allDescendants
allDescendants: () => Span[];
Recursively gets the descendant spans.
method end
end: () => void;
Ends a span and all of its children, recursively.
method isRootSpan
isRootSpan: () => boolean;
Returns whether a span is root or not.
method setStatus
setStatus: (code: CanonicalCode, message?: string) => void;
Sets a status to the span.
Parameter code
The canonical status code.
Parameter message
optional A developer-facing error message.
method start
start: () => void;
Starts a span.
method startChildSpan
startChildSpan: (options?: SpanOptions) => Span;
Starts a new Span instance as a child of this instance
method truncate
truncate: () => void;
Forces to end a span.
interface SpanContext
interface SpanContext {}
Defines the span context
property options
options?: number;
Options
property spanId
spanId: string;
Span ID
property traceId
traceId: string;
Trace ID
property traceState
traceState?: TraceState;
TraceState
interface SpanEventListener
interface SpanEventListener {}
Defines an end span event listener
method onEndSpan
onEndSpan: (span: Span) => void;
Happens when a span is ended
method onStartSpan
onStartSpan: (span: Span) => void;
Happens when a span is started
interface SpanOptions
interface SpanOptions {}
Defines the span options
interface Stats
interface Stats {}
Main interface for stats.
method clear
clear: () => void;
Remove all registered Views and exporters from the stats.
method createMeasureDouble
createMeasureDouble: ( name: string, unit: MeasureUnit, description?: string) => Measure;
Creates a measure of type Double.
Parameter name
The measure name
Parameter unit
The measure unit
Parameter description
The measure description
method createMeasureInt64
createMeasureInt64: ( name: string, unit: MeasureUnit, description?: string) => Measure;
Creates a measure of type Int64. Values must be integers up to Number.MAX_SAFE_INTERGER.
Parameter name
The measure name
Parameter unit
The measure unit
Parameter description
The measure description
method createView
createView: ( name: string, measure: Measure, aggregation: AggregationType, tagKeys: TagKey[], description: string, bucketBoundaries?: number[]) => View;
Creates a view.
Parameter name
The view name
Parameter measure
The view measure
Parameter aggregation
The view aggregation type
Parameter tagKeys
The view columns (tag keys)
Parameter description
The view description
Parameter bucketBoundaries
The view bucket boundaries for a distribution aggregation type
method getCurrentTagContext
getCurrentTagContext: () => TagMap;
Gets the current tag context.
method getMetrics
getMetrics: () => Metric[];
Gets a collection of produced Metric`s to be exported.
Returns
The List of metrics.
method record
record: ( measurements: Measurement[], tags?: TagMap, attachments?: { [key: string]: string }) => void;
Updates all views with the new measurements.
Parameter measurements
A list of measurements to record
Parameter 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.
Parameter attachments
optional The contextual information associated with an example value. The contextual information is represented as key - value string pairs.
method registerExporter
registerExporter: (exporter: StatsEventListener) => void;
Registers an exporter to send stats data to a service.
Parameter exporter
An stats exporter
method registerView
registerView: (view: View) => void;
Registers a view to listen to new measurements in its measure.
Parameter view
The view to be registered
method unregisterExporter
unregisterExporter: (exporter: StatsEventListener) => void;
Unregisters an exporter. It should be called whenever the exporter is not needed anymore.
Parameter exporter
An stats exporter
method withTagContext
withTagContext: <T>(tags: TagMap, fn: Func<T>) => T;
Enters the scope of code where the given
TagMap
is in the current context (replacing the previousTagMap
).Parameter tags
The TagMap to be set to the current context.
Parameter fn
Callback function.
Returns
The callback return.
interface StatsEventListener
interface StatsEventListener {}
An interface that describes the possible events that will be emitted from a Stats instance. Stats exporters should implement this interface.
method onRecord
onRecord: ( views: View[], measurement: Measurement, tags: Map<TagKey, TagValue>) => void;
Is called whenever a new measurement is recorded.
Parameter views
The views related to the measurement
Parameter measurement
The recorded measurement
Parameter tags
The tags to which the value is applied
Deprecated
since version 0.0.9 - use start instead
method onRegisterView
onRegisterView: (view: View) => void;
Is called whenever a new view is registered
Parameter view
The registered view
Deprecated
since version 0.0.9 - use start instead
method start
start: () => void;
Starts the exporter that polls Metric from Metrics library and send batched data to backend.
method stop
stop: () => void;
Stops the exporter.
interface StatsExemplar
interface 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.
property attachments
readonly attachments: { [key: string]: string;};
Contextual information about the example value.
property timestamp
readonly timestamp: number;
The observation (sampling) time of the above value.
property value
readonly value: number;
Value of the exemplar point. It determines which bucket the exemplar belongs to.
interface Status
interface Status {}
The status of a Span by providing a standard CanonicalCode in conjunction with an optional descriptive message.
interface SumData
interface SumData extends AggregationMetadata {}
Data collected and aggregated with this AggregationData will be summed up.
interface SummaryValue
interface SummaryValue {}
The start_timestamp only applies to the count and sum in the SummaryValue.
property count
readonly count: number;
The total number of recorded values since start_time. Optional since some systems don't expose this.
property snapshot
readonly snapshot?: Snapshot;
Values calculated over an arbitrary time window.
property sum
readonly sum: number;
The total sum of recorded values since start_time. Optional since some systems don't expose this. If count is zero then this field must be zero. This field must be unset if the sum is not available.
interface TagKey
interface TagKey {}
TagKey represents a tag key
property name
readonly name: string;
The name of the key.
interface TagMetadata
interface TagMetadata {}
TagMetadata contains properties associated with a Tag. Anytime a sender serializes a tag, sends it over the wire and receiver deserializes the tag then the tag is considered to have travelled one hop. There could be one or more proxy(ies) between sender and receiver. Proxies are treated as transparent entities and they do not create additional hops.
property tagTtl
readonly tagTtl: number;
For now, only special values of TagTtl are supported. In future, additional properties may be added to address specific situations.
interface TagValue
interface TagValue {}
TagValue represents a tag value
property value
readonly value: string;
The value of a tag.
interface TimeSeries
interface TimeSeries {}
A collection of data points that describes the time-varying values of a metric.
property labelValues
readonly labelValues: LabelValue[];
The set of label values that uniquely identify this timeseries. Applies to all points. The order of label values must match that of label keys in the metric descriptor.
property points
readonly points: Point[];
The data points of this timeseries. Point.value type MUST match the MetricDescriptor.type.
property startTimestamp
readonly startTimestamp?: Timestamp;
Must be present for cumulative metrics. The time when the cumulative value was reset to zero. Exclusive. The cumulative value is over the time interval (start_timestamp, timestamp]. If not specified, the backend can use the previous recorded value.
interface TimeSeriesPoint
interface Point {}
A timestamped measurement.
property timestamp
readonly timestamp: Timestamp;
The moment when this point was recorded. Inclusive. If not specified, the timestamp will be decided by the backend.
property value
readonly value: number | DistributionValue | SummaryValue;
The actual point value. 64-bit integer or 64-bit double-precision floating-point number or distribution value or summary value. This is not recommended, since it cannot be aggregated.
interface Timestamp
interface Timestamp {}
property nanos
nanos: number | null;
Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.
property seconds
seconds: number | null;
Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.
interface ToValueInterface
interface ToValueInterface {}
Interface for objects with "getValue" method.
method getValue
getValue: () => number;
interface TraceOptions
interface TraceOptions {}
Defines the trace options
property kind
kind?: SpanKind;
Span kind
property name
name: string;
Root span name
property samplingRate
samplingRate?: number;
Determines the sampling rate. Ranges from 0.0 to 1.0
property spanContext
spanContext?: SpanContext;
Trace context
interface TraceParams
interface TraceParams {}
Global configuration of trace service
property numberOfAnnontationEventsPerSpan
numberOfAnnontationEventsPerSpan?: number;
numberOfAnnontationEventsPerSpan is number of annotation events per span
property numberOfAttributesPerSpan
numberOfAttributesPerSpan?: number;
numberOfAttributesPerSpan is number of attributes per span
property numberOfLinksPerSpan
numberOfLinksPerSpan?: number;
numberOfLinksPerSpan is number of links per span
property numberOfMessageEventsPerSpan
numberOfMessageEventsPerSpan?: number;
numberOfMessageEventsPerSpan is number of message events per span
interface Tracer
interface Tracer extends TracerBase {}
Interface for Tracer
property currentRootSpan
currentRootSpan: Span;
Get and set the currentRootSpan to tracer instance
method clearCurrentTrace
clearCurrentTrace: () => void;
Clear the currentRootSpan from tracer instance
method wrap
wrap: <T>(fn: Func<T>) => Func<T>;
Binds the trace context to the given function. This is necessary in order to create child spans correctly in functions that are called asynchronously (for example, in a network response handler).
Parameter fn
A function to which to bind the trace context.
method wrapEmitter
wrapEmitter: (emitter: NodeJS.EventEmitter) => void;
Binds the trace context to the given event emitter. This is necessary in order to create child spans correctly in event handlers.
Parameter emitter
An event emitter whose handlers should have the trace context binded to them.
interface TracerBase
interface TracerBase extends SpanEventListener {}
Interface for TracerBase
property active
readonly active: boolean;
Get the active status from tracer instance
property activeTraceParams
activeTraceParams: configTypes.TraceParams;
A configuration object for trace parameters
property eventListeners
readonly eventListeners: SpanEventListener[];
Get the eventListeners from tracer instance
property logger
logger: loggerTypes.Logger;
A configuration for starting the tracer
property propagation
readonly propagation: Propagation;
A propagation instance
property sampler
sampler: samplerTypes.Sampler;
A sampler that will decide if the span will be sampled or not
method registerSpanEventListener
registerSpanEventListener: (listener: SpanEventListener) => void;
Register a OnEndSpanEventListener on the tracer instance
Parameter listener
An OnEndSpanEventListener instance
method setCurrentRootSpan
setCurrentRootSpan: (root: Span) => void;
Sets the current root span.
method start
start: (config: configTypes.TracerConfig) => this;
Start a tracer instance
Parameter config
Configuration for tracer instace
Returns
A tracer instance started
method startChildSpan
startChildSpan: (options?: SpanOptions) => Span;
Start a new Span instance to the currentRootSpan
Parameter options
A TraceOptions object to start a root span.
Returns
The new Span instance started
method startRootSpan
startRootSpan: <T>(options: TraceOptions, fn: (root: Span) => T) => T;
Start a new RootSpan to currentRootSpan
Parameter options
Options for tracer instance
Parameter fn
Callback function
Returns
The callback return
method stop
stop: () => this;
Stop the tracer instance
method unregisterSpanEventListener
unregisterSpanEventListener: (listener: SpanEventListener) => void;
Unregisters an end span event listener.
Parameter listener
The listener to unregister.
interface TracerConfig
interface TracerConfig {}
Defines tracer configuration parameters
property defaultAttributes
defaultAttributes?: Attributes;
A set of default attributes each in the format [KEY]:[VALUE]
property logger
logger?: Logger;
A logger object
property propagation
propagation?: Propagation;
A propagation instance
property samplingRate
samplingRate?: number;
Determines the sampling rate. Ranges from 0.0 to 1.0
property traceParams
traceParams?: TraceParams;
Trace Parameters
interface Tracing
interface Tracing {}
Main interface for tracing.
property active
active: boolean;
Gets active status
property exporter
readonly exporter: exportersTypes.Exporter;
Service to send collected traces to.
property tracer
readonly tracer: modelTypes.TracerBase;
Object responsible for managing a trace.
method registerExporter
registerExporter: (exporter: exportersTypes.Exporter) => Tracing;
Registers an exporter to send the collected traces to.
Parameter exporter
The exporter to send the traces to.
Returns
The tracing object.
method start
start: (userConfig?: configTypes.Config) => Tracing;
Starts tracing.
Parameter userConfig
A configuration object to start tracing.
Returns
The started Tracing instance.
method stop
stop: () => void;
Stops tracing.
method unregisterExporter
unregisterExporter: (exporter: exportersTypes.Exporter) => Tracing;
Unregisters an exporter.
Parameter exporter
The exporter to stop sending traces to.
interface TracingConfig
interface TracingConfig {}
Available configuration options.
property exporter
exporter?: Exporter;
An exporter object
property logger
logger?: Logger;
An instance of a logger
property logLevel
logLevel?: number;
level of logger - 0:disable, 1: error, 2: warn, 3: info, 4: debug
property maximumLabelValueSize
maximumLabelValueSize?: number;
The maximum number of characters reported on a label value.
property plugins
plugins?: PluginNames;
A list of trace instrumentations plugins to load. Each key is the name of the module to trace, and its value is the name of the package which has the plugin implementation. Ex.: plugins: { 'http': '@opencensus/opencensus-instrumentation-http', 'mongodb-core': '@opencensus/opencensus-instrumentation-mongodb-core', ... } Any user-provided value will be added to the default list. It will override any default plugin for the same key.
property stats
stats?: Stats;
An instance of a stats
interface ValueAtPercentile
interface ValueAtPercentile {}
Represents the value at a given percentile of a distribution.
property percentile
readonly percentile: number;
The percentile of a distribution. Must be in the interval (0.0, 100.0].
property value
readonly value: number;
The value at the given percentile of a distribution.
interface View
interface View {}
Defines how individual measurements are broken down by tags and aggregated.
property aggregation
readonly aggregation: AggregationType;
An Aggregation describes how data collected is aggregated. There are four aggregation types: count, sum, lastValue and distirbution.
property description
readonly description: string;
Describes the view, e.g. "RPC latency distribution"
property endTime
endTime?: number;
The end time for this view - represents the last time a value was recorded
property measure
readonly measure: Measure;
The Measure to which this view is applied.
property name
readonly name: string;
A string by which the View will be referred to, e.g. "rpc_latency". Names MUST be unique within the library.
property registered
registered: boolean;
true if the view was registered
property startTime
readonly startTime: number;
The start time for this view
method getColumns
getColumns: () => TagKey[];
Gets the view's tag keys
method getMetric
getMetric: (start: number) => Metric;
Gets view`s metric
method getSnapshot
getSnapshot: (tagValues: Array<TagValue | null>) => AggregationData;
Returns a snapshot of an AggregationData for that tags/labels values.
Parameter tagValues
The desired data's tag values.
method recordMeasurement
recordMeasurement: ( measurement: Measurement, tags: TagMap, attachments?: { [key: string]: string }) => void;
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.
Parameter measurement
The measurement to record
Parameter tags
The tags to which the value is applied
Parameter attachments
optional The contextual information associated with an example value. THe contextual information is represented as key - value string pairs.
Enums
enum AggregationType
enum AggregationType { COUNT = 0, SUM = 1, LAST_VALUE = 2, DISTRIBUTION = 3,}
Informs the type of the aggregation. It can be: count, sum, lastValue or distribution.
member COUNT
COUNT = 0
member DISTRIBUTION
DISTRIBUTION = 3
member LAST_VALUE
LAST_VALUE = 2
member SUM
SUM = 1
enum CanonicalCode
enum CanonicalCode { OK = 0, CANCELLED = 1, UNKNOWN = 2, INVALID_ARGUMENT = 3, DEADLINE_EXCEEDED = 4, NOT_FOUND = 5, ALREADY_EXISTS = 6, PERMISSION_DENIED = 7, RESOURCE_EXHAUSTED = 8, FAILED_PRECONDITION = 9, ABORTED = 10, OUT_OF_RANGE = 11, UNIMPLEMENTED = 12, INTERNAL = 13, UNAVAILABLE = 14, DATA_LOSS = 15, UNAUTHENTICATED = 16,}
An enumeration of canonical status codes.
member ABORTED
ABORTED = 10
The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.
See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
member ALREADY_EXISTS
ALREADY_EXISTS = 6
Some entity that we attempted to create (e.g., file or directory) already exists.
member CANCELLED
CANCELLED = 1
The operation was cancelled (typically by the caller).
member DATA_LOSS
DATA_LOSS = 15
Unrecoverable data loss or corruption.
member DEADLINE_EXCEEDED
DEADLINE_EXCEEDED = 4
Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.
member FAILED_PRECONDITION
FAILED_PRECONDITION = 9
Operation was rejected because the system is not in a state required for the operation's execution. For example, directory to be deleted may be non-empty, an rmdir operation is applied to a non-directory, etc.
A litmus test that may help a service implementor in deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE:
- Use UNAVAILABLE if the client can retry just the failing call. - Use ABORTED if the client should retry at a higher-level (e.g., restarting a read-modify-write sequence). - Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless they have first fixed up the directory by deleting files from it. - Use FAILED_PRECONDITION if the client performs conditional REST Get/Update/Delete on a resource and the resource on the server does not match the condition. E.g., conflicting read-modify-write on the same resource.
member INTERNAL
INTERNAL = 13
Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken.
member INVALID_ARGUMENT
INVALID_ARGUMENT = 3
Client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
member NOT_FOUND
NOT_FOUND = 5
Some requested entity (e.g., file or directory) was not found.
member OK
OK = 0
Not an error; returned on success
member OUT_OF_RANGE
OUT_OF_RANGE = 11
Operation was attempted past the valid range. E.g., seeking or reading past end of file.
Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size.
There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
member PERMISSION_DENIED
PERMISSION_DENIED = 7
The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors).
member RESOURCE_EXHAUSTED
RESOURCE_EXHAUSTED = 8
Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
member UNAUTHENTICATED
UNAUTHENTICATED = 16
The request does not have valid authentication credentials for the operation.
member UNAVAILABLE
UNAVAILABLE = 14
The service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff.
See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
member UNIMPLEMENTED
UNIMPLEMENTED = 12
Operation is not implemented or not supported/enabled in this service.
member UNKNOWN
UNKNOWN = 2
Unknown error. An example of where this error may be returned is if a status value received from another address space belongs to an error-space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
enum LinkType
enum LinkType { UNSPECIFIED = 0, CHILD_LINKED_SPAN = 1, PARENT_LINKED_SPAN = 2,}
Type of link. The relationship of the current span relative to the linked span.
member CHILD_LINKED_SPAN
CHILD_LINKED_SPAN = 1
The linked span is a child of the current span.
member PARENT_LINKED_SPAN
PARENT_LINKED_SPAN = 2
The linked span is a parent of the current span.
member UNSPECIFIED
UNSPECIFIED = 0
The relationship of the two spans is unknown, or known but other than parent-child.
enum MeasureType
enum MeasureType { INT64 = 'INT64', DOUBLE = 'DOUBLE',}
Describes the types of a Measure. It can be Int64 or a Double type.
enum MeasureUnit
enum MeasureUnit { UNIT = '1', BYTE = 'by', KBYTE = 'kb', SEC = 's', MS = 'ms', NS = 'ns',}
Describes the unit used for the Measure. Should follows the format described by http://unitsofmeasure.org/ucum.html.
enum MessageEventType
enum MessageEventType { UNSPECIFIED = 0, SENT = 1, RECEIVED = 2,}
An event describing a message sent/received between Spans.
member RECEIVED
RECEIVED = 2
Indicates a received message.
member SENT
SENT = 1
Indicates a sent message.
member UNSPECIFIED
UNSPECIFIED = 0
Unknown event type.
enum MetricDescriptorType
enum MetricDescriptorType { UNSPECIFIED = 0, GAUGE_INT64 = 1, GAUGE_DOUBLE = 2, GAUGE_DISTRIBUTION = 3, CUMULATIVE_INT64 = 4, CUMULATIVE_DOUBLE = 5, CUMULATIVE_DISTRIBUTION = 6, SUMMARY = 7,}
The kind of metric. It describes how the data is reported.
A gauge is an instantaneous measurement of a value.
A cumulative measurement is a value accumulated over a time interval. In a time series, cumulative measurements should have the same start time, increasing values and increasing end times, until an event resets the cumulative value to zero and sets a new start time for the following points.
member CUMULATIVE_DISTRIBUTION
CUMULATIVE_DISTRIBUTION = 6
Distribution cumulative measurement. The count and sum cannot decrease, if resets then the start_time should also be reset.
member CUMULATIVE_DOUBLE
CUMULATIVE_DOUBLE = 5
Floating point cumulative measurement. The value cannot decrease, if resets then the start_time should also be reset. Recorded values are always >= 0.
member CUMULATIVE_INT64
CUMULATIVE_INT64 = 4
Integer cumulative measurement. The value cannot decrease, if resets then the start_time should also be reset.
member GAUGE_DISTRIBUTION
GAUGE_DISTRIBUTION = 3
Distribution gauge measurement. The count and sum can go both up and down. Recorded values are always >= 0. Used in scenarios like a snapshot of time the current items in a queue have spent there.
member GAUGE_DOUBLE
GAUGE_DOUBLE = 2
Floating point gauge. The value can go both up and down.
member GAUGE_INT64
GAUGE_INT64 = 1
Integer gauge. The value can go both up and down.
member SUMMARY
SUMMARY = 7
Some frameworks implemented Histograms as a summary of observations (usually things like request durations and response sizes). While it also provides a total count of observations and a sum of all observed values, it calculates configurable percentiles over a sliding time window. This is not recommended, since it cannot be aggregated.
member UNSPECIFIED
UNSPECIFIED = 0
Do not use this default value.