opentracing

  • Version 0.14.5
  • Published
  • 195 kB
  • No dependencies
  • Apache-2.0 license

Install

npm i opentracing
yarn add opentracing
pnpm add opentracing

Overview

[![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-

Index

Variables

variable FORMAT_BINARY

const FORMAT_BINARY: string;
  • The FORMAT_BINARY format represents SpanContexts in an opaque binary carrier.

    Tracer.inject() will set the buffer field to an Array-like (Array, ArrayBuffer, or TypedBuffer) object containing the injected binary data. Any valid Object can be used as long as the buffer field of the object can be set.

    Tracer.extract() will look for carrier.buffer, and that field is expected to be an Array-like object (Array, ArrayBuffer, or TypedBuffer).

variable FORMAT_HTTP_HEADERS

const FORMAT_HTTP_HEADERS: string;
  • The FORMAT_HTTP_HEADERS format represents SpanContexts using a character-restricted string->string map (backed by a Javascript Object) as a carrier.

    Keys and values in the FORMAT_HTTP_HEADERS carrier must be suitable for use as HTTP headers (without modification or further escaping). That is, the keys have a greatly restricted character set, casing for the keys may not be preserved by various intermediaries, and the values should be URL-escaped.

    The FORMAT_HTTP_HEADERS carrier map may contain unrelated data (e.g., arbitrary HTTP headers); as such, the Tracer implementation should use a prefix or other convention to distinguish Tracer-specific key:value pairs.

variable FORMAT_TEXT_MAP

const FORMAT_TEXT_MAP: string;
  • The FORMAT_TEXT_MAP format represents SpanContexts using a string->string map (backed by a Javascript Object) as a carrier.

    NOTE: Unlike FORMAT_HTTP_HEADERS, FORMAT_TEXT_MAP places no restrictions on the characters used in either the keys or the values of the map entries.

    The FORMAT_TEXT_MAP carrier map may contain unrelated data (e.g., arbitrary gRPC metadata); as such, the Tracer implementation should use a prefix or other convention to distinguish Tracer-specific key:value pairs.

variable REFERENCE_CHILD_OF

const REFERENCE_CHILD_OF: string;
  • A Span may be the "child of" a parent Span. In a “child of” reference, the parent Span depends on the child Span in some capacity.

    See more about reference types at https://github.com/opentracing/specification

variable REFERENCE_FOLLOWS_FROM

const REFERENCE_FOLLOWS_FROM: string;
  • Some parent Spans do not depend in any way on the result of their child Spans. In these cases, we say merely that the child Span “follows from” the parent Span in a causal sense.

    See more about reference types at https://github.com/opentracing/specification

Functions

function childOf

childOf: (spanContext: SpanContext | Span) => Reference;
  • Return a new REFERENCE_CHILD_OF reference.

    Parameter spanContext

    the parent SpanContext instance to reference. a REFERENCE_CHILD_OF reference pointing to spanContext

function followsFrom

followsFrom: (spanContext: SpanContext | Span) => Reference;
  • Return a new REFERENCE_FOLLOWS_FROM reference.

    Parameter spanContext

    the parent SpanContext instance to reference. a REFERENCE_FOLLOWS_FROM reference pointing to spanContext

function globalTracer

globalTracer: () => Tracer;
  • Returns the global tracer.

function initGlobalTracer

initGlobalTracer: (tracer: Tracer) => void;
  • Set the global Tracer.

    The behavior is undefined if this function is called more than once.

    Parameter tracer

    the Tracer implementation

Classes

class BinaryCarrier

class BinaryCarrier {}
  • Convenience class to use as a binary carrier.

    Any valid Object with a field named buffer may be used as a binary carrier; this class is only one such type of object that can be used.

constructor

constructor(buffer: ArrayLike<number>);

    property buffer

    buffer: ArrayLike<number>;

      class MockTracer

      class MockTracer extends opentracing.Tracer {}
      • OpenTracing Tracer implementation designed for use in unit tests.

      constructor

      constructor();

        method clear

        clear: () => void;
        • Discard any buffered data.

        method report

        report: () => MockReport;
        • Return the buffered data in a format convenient for making unit test assertions.

        class Reference

        class Reference {}
        • Reference pairs a reference type constant (e.g., REFERENCE_CHILD_OF or REFERENCE_FOLLOWS_FROM) with the SpanContext it points to.

          See the exported childOf() and followsFrom() functions at the package level.

        constructor

        constructor(type: string, referencedContext: SpanContext | Span);
        • Initialize a new Reference instance.

          Parameter type

          the Reference type constant (e.g., REFERENCE_CHILD_OF or REFERENCE_FOLLOWS_FROM).

          Parameter referencedContext

          the SpanContext being referred to. As a convenience, a Span instance may be passed in instead (in which case its .context() is used here).

        method referencedContext

        referencedContext: () => SpanContext;
        • {SpanContext} The SpanContext being referred to (e.g., the parent in a REFERENCE_CHILD_OF Reference).

        method type

        type: () => string;
        • {string} The Reference type (e.g., REFERENCE_CHILD_OF or REFERENCE_FOLLOWS_FROM).

        class Span

        class Span {}
        • 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.

        method addTags

        addTags: (keyValueMap: { [key: string]: any }) => 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).

          {[type]} [description]

        method context

        context: () => SpanContext;
        • Returns the SpanContext object associated with this Span.

          {SpanContext}

        method finish

        finish: (finishTime?: number) => void;
        • 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.

          Parameter 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.

        method getBaggageItem

        getBaggageItem: (key: string) => string | undefined;
        • Returns the value for a baggage item given its key.

          Parameter key

          The key for the given trace attribute. {string} String value for the given key, or undefined if the key does not correspond to a set trace attribute.

        method log

        log: (keyValuePairs: { [key: string]: any }, timestamp?: number) => 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());

          Parameter 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.

          Parameter 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.

        method logEvent

        logEvent: (eventName: string, payload: any) => void;
        • DEPRECATED

        method setBaggageItem

        setBaggageItem: (key: string, value: string) => 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.

          Parameter key

          Parameter value

        method setOperationName

        setOperationName: (name: string) => this;
        • Sets the string name for the logical operation this span represents.

          Parameter name

        method setTag

        setTag: (key: string, value: any) => this;
        • Adds a single tag to the span. See addTags() for details.

          Parameter key

          Parameter value

        method tracer

        tracer: () => Tracer;
        • Returns the Tracer object used to create this Span.

          {Tracer}

        class SpanContext

        class SpanContext {}
        • SpanContext represents Span state that must propagate to descendant Spans and across process boundaries.

          SpanContext is logically divided into two pieces: the user-level "Baggage" (see setBaggageItem and getBaggageItem) that propagates across Span boundaries and any Tracer-implementation-specific fields that are needed to identify or otherwise contextualize the associated Span instance (e.g., a <trace_id, span_id, sampled> tuple).

        method toSpanId

        toSpanId: () => string;
        • Returns a string representation of the implementation internal span ID.

          Returns

          {string}

        method toTraceId

        toTraceId: () => string;
        • Returns a string representation of the implementation internal trace ID.

          Returns

          {string}

        class Tracer

        class Tracer {}
        • Tracer is the entry-point between the instrumentation API and the tracing implementation.

          The default object acts as a no-op implementation.

          Note to implementators: derived classes can choose to directly implement the methods in the "OpenTracing API methods" section, or optionally the subset of underscore-prefixed methods to pick up the argument checking and handling automatically from the base class.

        method extract

        extract: (format: string, carrier: any) => SpanContext | null;
        • Returns a SpanContext instance extracted from carrier in the given format.

          OpenTracing defines a common set of format values (see FORMAT_TEXT_MAP, FORMAT_HTTP_HEADERS, and FORMAT_BINARY), and each has an expected carrier type.

          Consider this pseudocode example:

          // Use the inbound HTTP request's headers as a text map carrier. var headersCarrier = inboundHTTPReq.headers; var wireCtx = Tracer.extract(Tracer.FORMAT_HTTP_HEADERS, headersCarrier); var serverSpan = Tracer.startSpan('...', { childOf : wireCtx });

          Parameter format

          the format of the carrier.

          Parameter carrier

          the type of the carrier object is determined by the format. {SpanContext} The extracted SpanContext, or null if no such SpanContext could be found in carrier

        method inject

        inject: (spanContext: SpanContext | Span, format: string, carrier: any) => void;
        • Injects the given SpanContext instance for cross-process propagation within carrier. The expected type of carrier depends on the value of `format.

          OpenTracing defines a common set of format values (see FORMAT_TEXT_MAP, FORMAT_HTTP_HEADERS, and FORMAT_BINARY), and each has an expected carrier type.

          Consider this pseudocode example:

          var clientSpan = ...; ... // Inject clientSpan into a text carrier. var headersCarrier = {}; Tracer.inject(clientSpan.context(), Tracer.FORMAT_HTTP_HEADERS, headersCarrier); // Incorporate the textCarrier into the outbound HTTP request header // map. Object.assign(outboundHTTPReq.headers, headersCarrier); // ... send the httpReq

          Parameter spanContext

          the SpanContext to inject into the carrier object. As a convenience, a Span instance may be passed in instead (in which case its .context() is used for the inject()).

          Parameter format

          the format of the carrier.

          Parameter carrier

          see the documentation for the chosen format for a description of the carrier object.

        method startSpan

        startSpan: (name: string, options?: SpanOptions) => Span;
        • Starts and returns a new Span representing a logical unit of work.

          For example:

          // Start a new (parentless) root Span: var parent = Tracer.startSpan('DoWork');

          // Start a new (child) Span: var child = Tracer.startSpan('load-from-db', { childOf: parent.context(), });

          // Start a new async (FollowsFrom) Span: var child = Tracer.startSpan('async-cache-write', { references: [ opentracing.followsFrom(parent.context()) ], });

          Parameter name

          the name of the operation (REQUIRED).

          Parameter options

          options for the newly created span. {Span} - a new Span object.

        Interfaces

        interface SpanOptions

        interface SpanOptions {}

          property childOf

          childOf?: Span | SpanContext;
          • a parent SpanContext (or Span, for convenience) that the newly-started span will be the child of (per REFERENCE_CHILD_OF). If specified, references must be unspecified.

          property references

          references?: Reference[];
          • an array of Reference instances, each pointing to a causal parent SpanContext. If specified, fields.childOf must be unspecified.

          property startTime

          startTime?: number;
          • a manually specified start time for the created Span object. The time should be specified in milliseconds as Unix timestamp. Decimal value are supported to represent time values with sub-millisecond accuracy.

          property tags

          tags?: {
          [key: string]: any;
          };
          • set of key-value pairs which will be set as tags on the newly created Span. Ownership of the object is passed to the created span for efficiency reasons (the caller should not modify this object after calling startSpan).

          Namespaces

          namespace Tags

          module 'lib/ext/tags.d.ts' {}
          • SPAN_KIND hints at relationship between spans, e.g. client/server

          variable COMPONENT

          const COMPONENT: string;
          • COMPONENT (string) ia s low-cardinality identifier of the module, library, or package that is generating a span.

          variable DB_INSTANCE

          const DB_INSTANCE: string;
          • DB_INSTANCE (string) Database instance name. E.g., In java, if the jdbc.url="jdbc:mysql://127.0.0.1:3306/customers", the instance name is "customers".

          variable DB_STATEMENT

          const DB_STATEMENT: string;
          • DB_STATEMENT (string) A database statement for the given database type. E.g., for db.type="SQL", "SELECT * FROM wuser_table"; for db.type="redis", "SET mykey 'WuValue'".

          variable DB_TYPE

          const DB_TYPE: string;
          • DB_TYPE (string) Database type. For any SQL database, "sql". For others, the lower-case database category, e.g. "cassandra", "hbase", or "redis".

          variable DB_USER

          const DB_USER: string;
          • DB_USER (string) Username for accessing database. E.g., "readonly_user" or "reporting_user"

          variable ERROR

          const ERROR: string;
          • ERROR (boolean) true if and only if the application considers the operation represented by the Span to have failed

          variable HTTP_METHOD

          const HTTP_METHOD: string;
          • HTTP_METHOD (string) HTTP method of the request for the associated Span. E.g., "GET", "POST"

          variable HTTP_STATUS_CODE

          const HTTP_STATUS_CODE: string;
          • HTTP_STATUS_CODE (number) HTTP response status code for the associated Span. E.g., 200, 503, 404

          variable HTTP_URL

          const HTTP_URL: string;
          • HTTP_URL (string) URL of the request being handled in this segment of the trace, in standard URI format. E.g., "https://domain.net/path/to?resource=here"

          variable MESSAGE_BUS_DESTINATION

          const MESSAGE_BUS_DESTINATION: string;
          • MESSAGE_BUS_DESTINATION (string) An address at which messages can be exchanged. E.g. A Kafka record has an associated "topic name" that can be extracted by the instrumented producer or consumer and stored using this tag.

          variable PEER_ADDRESS

          const PEER_ADDRESS: string;
          • PEER_ADDRESS (string) Remote "address", suitable for use in a networking client library. This may be a "ip:port", a bare "hostname", a FQDN, or even a JDBC substring like "mysql://prod-db:3306"

          variable PEER_HOST_IPV4

          const PEER_HOST_IPV4: string;
          • PEER_HOST_IPV4 (number) Remote IPv4 address as a .-separated tuple. E.g., "127.0.0.1"

          variable PEER_HOST_IPV6

          const PEER_HOST_IPV6: string;

            variable PEER_HOSTNAME

            const PEER_HOSTNAME: string;
            • PEER_HOSTNAME (string) Remote hostname. E.g., "opentracing.io", "internal.dns.name"

            variable PEER_PORT

            const PEER_PORT: string;

              variable PEER_SERVICE

              const PEER_SERVICE: string;
              • PEER_SERVICE (string) Remote service name (for some unspecified definition of "service"). E.g., "elasticsearch", "a_custom_microservice", "memcache"

              variable SAMPLING_PRIORITY

              const SAMPLING_PRIORITY: string;
              • SAMPLING_PRIORITY (number) determines the priority of sampling this Span. If greater than 0, a hint to the Tracer to do its best to capture the trace. If 0, a hint to the trace to not-capture the trace. If absent, the Tracer should use its default sampling mechanism.

              variable SPAN_KIND

              const SPAN_KIND: string;
              • SPAN_KIND hints at relationship between spans, e.g. client/server

              variable SPAN_KIND_MESSAGING_CONSUMER

              const SPAN_KIND_MESSAGING_CONSUMER: string;
              • Marks a span representing the consuming-side within a messaging system or other remote call

              variable SPAN_KIND_MESSAGING_PRODUCER

              const SPAN_KIND_MESSAGING_PRODUCER: string;
              • Marks a span representing the producing-side within a messaging system or other remote call

              variable SPAN_KIND_RPC_CLIENT

              const SPAN_KIND_RPC_CLIENT: string;
              • Marks a span representing the client-side of an RPC or other remote call

              variable SPAN_KIND_RPC_SERVER

              const SPAN_KIND_RPC_SERVER: string;
              • Marks a span representing the server-side of an RPC or other remote call

              Package Files (11)

              Dependencies (0)

              No dependencies.

              Dev Dependencies (20)

              Peer Dependencies (0)

              No peer dependencies.

              Badge

              To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

              You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/opentracing.

              • Markdown
                [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/opentracing)
              • HTML
                <a href="https://www.jsdocs.io/package/opentracing"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>