opentracing
Version:
[![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov] [![NPM Published Version][npm-img]][npm] ![Node Version][node-img] [![Join the chat at https://gitter.im/opentracing/opentracing-javascript](https://badges.gitter.im/opentracing/opentracing-
207 lines • 7.76 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
var noop = require("./noop");
/**
* Span represents a logical unit of work as part of a broader Trace. Examples
* of span might include remote procedure calls or a in-process function calls
* to sub-components. A Trace has a single, top-level "root" Span that in turn
* may have zero or more child Spans, which in turn may have children.
*/
var Span = /** @class */ (function () {
function Span() {
}
// ---------------------------------------------------------------------- //
// OpenTracing API methods
// ---------------------------------------------------------------------- //
/**
* Returns the SpanContext object associated with this Span.
*
* @return {SpanContext}
*/
Span.prototype.context = function () {
return this._context();
};
/**
* Returns the Tracer object used to create this Span.
*
* @return {Tracer}
*/
Span.prototype.tracer = function () {
return this._tracer();
};
/**
* Sets the string name for the logical operation this span represents.
*
* @param {string} name
*/
Span.prototype.setOperationName = function (name) {
this._setOperationName(name);
return this;
};
/**
* Sets a key:value pair on this Span that also propagates to future
* children of the associated Span.
*
* setBaggageItem() enables powerful functionality given a full-stack
* opentracing integration (e.g., arbitrary application data from a web
* client can make it, transparently, all the way into the depths of a
* storage system), and with it some powerful costs: use this feature with
* care.
*
* IMPORTANT NOTE #1: setBaggageItem() will only propagate baggage items to
* *future* causal descendants of the associated Span.
*
* IMPORTANT NOTE #2: Use this thoughtfully and with care. Every key and
* value is copied into every local *and remote* child of the associated
* Span, and that can add up to a lot of network and cpu overhead.
*
* @param {string} key
* @param {string} value
*/
Span.prototype.setBaggageItem = function (key, value) {
this._setBaggageItem(key, value);
return this;
};
/**
* Returns the value for a baggage item given its key.
*
* @param {string} key
* The key for the given trace attribute.
* @return {string}
* String value for the given key, or undefined if the key does not
* correspond to a set trace attribute.
*/
Span.prototype.getBaggageItem = function (key) {
return this._getBaggageItem(key);
};
/**
* Adds a single tag to the span. See `addTags()` for details.
*
* @param {string} key
* @param {any} value
*/
Span.prototype.setTag = function (key, value) {
var _a;
// NOTE: the call is normalized to a call to _addTags()
this._addTags((_a = {}, _a[key] = value, _a));
return this;
};
/**
* Adds the given key value pairs to the set of span tags.
*
* Multiple calls to addTags() results in the tags being the superset of
* all calls.
*
* The behavior of setting the same key multiple times on the same span
* is undefined.
*
* The supported type of the values is implementation-dependent.
* Implementations are expected to safely handle all types of values but
* may choose to ignore unrecognized / unhandle-able values (e.g. objects
* with cyclic references, function objects).
*
* @return {[type]} [description]
*/
Span.prototype.addTags = function (keyValueMap) {
this._addTags(keyValueMap);
return this;
};
/**
* Add a log record to this Span, optionally at a user-provided timestamp.
*
* For example:
*
* span.log({
* size: rpc.size(), // numeric value
* URI: rpc.URI(), // string value
* payload: rpc.payload(), // Object value
* "keys can be arbitrary strings": rpc.foo(),
* });
*
* span.log({
* "error.description": someError.description(),
* }, someError.timestampMillis());
*
* @param {object} keyValuePairs
* An object mapping string keys to arbitrary value types. All
* Tracer implementations should support bool, string, and numeric
* value types, and some may also support Object values.
* @param {number} timestamp
* An optional parameter specifying the timestamp in milliseconds
* since the Unix epoch. Fractional values are allowed so that
* timestamps with sub-millisecond accuracy can be represented. If
* not specified, the implementation is expected to use its notion
* of the current time of the call.
*/
Span.prototype.log = function (keyValuePairs, timestamp) {
this._log(keyValuePairs, timestamp);
return this;
};
/**
* DEPRECATED
*/
Span.prototype.logEvent = function (eventName, payload) {
return this._log({ event: eventName, payload: payload });
};
/**
* Sets the end timestamp and finalizes Span state.
*
* With the exception of calls to Span.context() (which are always allowed),
* finish() must be the last call made to any span instance, and to do
* otherwise leads to undefined behavior.
*
* @param {number} finishTime
* Optional finish time in milliseconds as a Unix timestamp. Decimal
* values are supported for timestamps with sub-millisecond accuracy.
* If not specified, the current time (as defined by the
* implementation) will be used.
*/
Span.prototype.finish = function (finishTime) {
this._finish(finishTime);
// Do not return `this`. The Span generally should not be used after it
// is finished so chaining is not desired in this context.
};
// ---------------------------------------------------------------------- //
// Derived classes can choose to implement the below
// ---------------------------------------------------------------------- //
// By default returns a no-op SpanContext.
Span.prototype._context = function () {
return noop.spanContext;
};
// By default returns a no-op tracer.
//
// The base class could store the tracer that created it, but it does not
// in order to ensure the no-op span implementation has zero members,
// which allows V8 to aggressively optimize calls to such objects.
Span.prototype._tracer = function () {
return noop.tracer;
};
// By default does nothing
Span.prototype._setOperationName = function (name) {
};
// By default does nothing
Span.prototype._setBaggageItem = function (key, value) {
};
// By default does nothing
Span.prototype._getBaggageItem = function (key) {
return undefined;
};
// By default does nothing
//
// NOTE: both setTag() and addTags() map to this function. keyValuePairs
// will always be an associative array.
Span.prototype._addTags = function (keyValuePairs) {
};
// By default does nothing
Span.prototype._log = function (keyValuePairs, timestamp) {
};
// By default does nothing
//
// finishTime is expected to be either a number or undefined.
Span.prototype._finish = function (finishTime) {
};
return Span;
}());
exports.Span = Span;
exports.default = Span;
//# sourceMappingURL=span.js.map