@opentelemetry/api - npm Package Compare versions

Comparing version 0.4.0 to 0.5.0

build/src/api/metrics.d.ts

@@ -31,3 +31,3 @@ /*!
      */
-    initGlobalMeterProvider(provider: MeterProvider): MeterProvider;
+    setGlobalMeterProvider(provider: MeterProvider): MeterProvider;
     /**
@@ -34,0 +34,0 @@ * Returns the global meter provider.

build/src/api/metrics.js

@@ -37,3 +37,3 @@ "use strict";
      */
-    initGlobalMeterProvider(provider) {
+    setGlobalMeterProvider(provider) {
         this._meterProvider = provider;
@@ -40,0 +40,0 @@ return provider;

build/src/api/trace.d.ts

@@ -31,3 +31,3 @@ /*!
      */
-    initGlobalTracerProvider(provider: TracerProvider): TracerProvider;
+    setGlobalTracerProvider(provider: TracerProvider): TracerProvider;
     /**
@@ -34,0 +34,0 @@ * Returns the global tracer provider.

build/src/api/trace.js

@@ -37,3 +37,3 @@ "use strict";
      */
-    initGlobalTracerProvider(provider) {
+    setGlobalTracerProvider(provider) {
         this._tracerProvider = provider;
@@ -40,0 +40,0 @@ return provider;

build/src/context/propagation/HttpTextFormat.d.ts

@@ -16,35 +16,42 @@ /*!
  */
-import { SpanContext } from '../../trace/span_context';
+import { Context } from '@opentelemetry/scope-base';
+import { SetterFunction } from './setter';
+import { GetterFunction } from './getter';
 /**
- * Injects and extracts a value as text into carriers that travel in-band
- * across process boundaries. Encoding is expected to conform to the HTTP
- * Header Field semantics. Values are often encoded as RPC/HTTP request headers.
+ * Injects {@link Context} into and extracts it from carriers that travel
+ * in-band across process boundaries. Encoding is expected to conform to the
+ * HTTP Header Field semantics. Values are often encoded as RPC/HTTP request
+ * headers.
  *
  * The carrier of propagated data on both the client (injector) and server
- * (extractor) side is usually an http request. Propagation is usually
- * implemented via library- specific request interceptors, where the
- * client-side injects values and the server-side extracts them.
+ * (extractor) side is usually an object such as http headers.
  */
 export interface HttpTextFormat {
     /**
-     * Injects the given {@link SpanContext} instance to transmit over the wire.
+     * Injects values from a given {@link Context} into a carrier.
      *
-     * OpenTelemetry defines a common set of format values (BinaryFormat and
-     * HTTPTextFormat), and each has an expected `carrier` type.
+     * OpenTelemetry defines a common set of format values (HTTPTextFormat), and
+     * each has an expected `carrier` type.
      *
-     * @param spanContext the SpanContext to transmit over the wire.
-     * @param format the format of the carrier.
-     * @param carrier the carrier of propagation fields, such as an http request.
+     * @param context the Context from which to extract values to transmit over
+     *     the wire.
+     * @param carrier the carrier of propagation fields, such as http request
+     *     headers.
+     * @param setter a function which accepts a carrier, key, and value, which
+     *     sets the key on the carrier to the value.
      */
-    inject(spanContext: SpanContext, format: string, carrier: unknown): void;
+    inject(context: Context, carrier: unknown, setter: SetterFunction): void;
     /**
-     * Returns a {@link SpanContext} instance extracted from `carrier` in the
-     * given format from upstream.
+     * Given a {@link Context} and a carrier, extract context values from a
+     * carrier and return a new context, created from the old context, with the
+     * extracted values.
      *
-     * @param format the format of the carrier.
-     * @param carrier the carrier of propagation fields, such as an http request.
-     * @returns SpanContext The extracted SpanContext, or null if no such
-     *     SpanContext could be found in carrier.
+     * @param context the Context from which to extract values to transmit over
+     *     the wire.
+     * @param carrier the carrier of propagation fields, such as http request
+     *     headers.
+     * @param getter a function which accepts a carrier and a key, and returns
+     *     the value from the carrier identified by the key.
      */
-    extract(format: string, carrier: unknown): SpanContext | null;
+    extract(context: Context, carrier: unknown, getter: GetterFunction): Context;
 }

build/src/context/propagation/NoopHttpTextFormat.d.ts

@@ -16,3 +16,3 @@ /*!
  */
-import { SpanContext } from '../../trace/span_context';
+import { Context } from '@opentelemetry/scope-base';
 import { HttpTextFormat } from './HttpTextFormat';
@@ -23,5 +23,7 @@ /**
 export declare class NoopHttpTextFormat implements HttpTextFormat {
-    inject(spanContext: SpanContext, format: string, carrier: unknown): void;
-    extract(format: string, carrier: unknown): SpanContext | null;
+    /** Noop inject function does nothing */
+    inject(context: Context, carrier: unknown, setter: Function): void;
+    /** Noop extract function does nothing and returns the input context */
+    extract(context: Context, carrier: unknown, getter: Function): Context;
 }
 export declare const NOOP_HTTP_TEXT_FORMAT: NoopHttpTextFormat;

build/src/context/propagation/NoopHttpTextFormat.js

@@ -22,7 +22,7 @@ "use strict";
 class NoopHttpTextFormat {
-    // By default does nothing
-    inject(spanContext, format, carrier) { }
-    // By default does nothing
-    extract(format, carrier) {
-        return null;
+    /** Noop inject function does nothing */
+    inject(context, carrier, setter) { }
+    /** Noop extract function does nothing and returns the input context */
+    extract(context, carrier, getter) {
+        return context;
     }
@@ -29,0 +29,0 @@ }

build/src/index.d.ts

@@ -18,6 +18,8 @@ /*!
 export * from './common/Time';
-export * from './context/propagation/BinaryFormat';
-export * from './context/propagation/HttpTextFormat';
-export * from './distributed_context/DistributedContext';
-export * from './distributed_context/EntryValue';
+export * from './context/propagation/getter';
+export * from './context/propagation/HttpTextPropagator';
+export * from './context/propagation/NoopHttpTextPropagator';
+export * from './context/propagation/setter';
+export * from './correlation_context/CorrelationContext';
+export * from './correlation_context/EntryValue';
 export * from './metrics/BoundInstrument';
@@ -27,22 +29,28 @@ export * from './metrics/Meter';
 export * from './metrics/Metric';
+export * from './metrics/NoopMeter';
+export * from './metrics/NoopMeterProvider';
+export * from './metrics/ObserverResult';
 export * from './trace/attributes';
 export * from './trace/Event';
 export * from './trace/instrumentation/Plugin';
+export * from './trace/link_context';
 export * from './trace/link';
+export * from './trace/NoopSpan';
+export * from './trace/NoopTracer';
+export * from './trace/NoopTracerProvider';
 export * from './trace/Sampler';
+export * from './trace/span_context';
+export * from './trace/span_kind';
 export * from './trace/span';
 export * from './trace/SpanOptions';
-export * from './trace/span_context';
-export * from './trace/span_kind';
 export * from './trace/status';
 export * from './trace/TimedEvent';
-export * from './trace/tracer';
-export * from './trace/tracer_provider';
 export * from './trace/trace_flags';
 export * from './trace/trace_state';
-export * from './trace/NoopSpan';
-export * from './trace/NoopTracer';
-export * from './trace/NoopTracerProvider';
-export * from './metrics/NoopMeterProvider';
-export * from './metrics/NoopMeter';
+export * from './trace/tracer_provider';
+export * from './trace/tracer';
+export { Context } from '@opentelemetry/context-base';
+import { ContextAPI } from './api/context';
+/** Entrypoint for context API */
+export declare const context: ContextAPI;
 import { TraceAPI } from './api/trace';
@@ -54,6 +62,11 @@ /** Entrypoint for trace API */
 export declare const metrics: MetricsAPI;
+import { PropagationAPI } from './api/propagation';
+/** Entrypoint for propagation API */
+export declare const propagation: PropagationAPI;
 declare const _default: {
     trace: TraceAPI;
     metrics: MetricsAPI;
+    context: ContextAPI;
+    propagation: PropagationAPI;
 };
 export default _default;

build/src/index.js

@@ -21,12 +21,20 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-__export(require("./distributed_context/EntryValue"));
+__export(require("./context/propagation/getter"));
+__export(require("./context/propagation/NoopHttpTextPropagator"));
+__export(require("./context/propagation/setter"));
+__export(require("./correlation_context/EntryValue"));
 __export(require("./metrics/Metric"));
+__export(require("./metrics/NoopMeter"));
+__export(require("./metrics/NoopMeterProvider"));
+__export(require("./trace/NoopSpan"));
+__export(require("./trace/NoopTracer"));
+__export(require("./trace/NoopTracerProvider"));
 __export(require("./trace/span_kind"));
 __export(require("./trace/status"));
 __export(require("./trace/trace_flags"));
-__export(require("./trace/NoopSpan"));
-__export(require("./trace/NoopTracer"));
-__export(require("./trace/NoopTracerProvider"));
-__export(require("./metrics/NoopMeterProvider"));
-__export(require("./metrics/NoopMeter"));
+var context_base_1 = require("@opentelemetry/context-base");
+exports.Context = context_base_1.Context;
+const context_1 = require("./api/context");
+/** Entrypoint for context API */
+exports.context = context_1.ContextAPI.getInstance();
 const trace_1 = require("./api/trace");
@@ -38,6 +46,11 @@ /** Entrypoint for trace API */
 exports.metrics = metrics_1.MetricsAPI.getInstance();
+const propagation_1 = require("./api/propagation");
+/** Entrypoint for propagation API */
+exports.propagation = propagation_1.PropagationAPI.getInstance();
 exports.default = {
     trace: exports.trace,
     metrics: exports.metrics,
+    context: exports.context,
+    propagation: exports.propagation,
 };
 //# sourceMappingURL=index.js.map

build/src/metrics/BoundInstrument.d.ts

@@ -16,4 +16,5 @@ /*!
  */
-import { DistributedContext } from '../distributed_context/DistributedContext';
+import { CorrelationContext } from '../correlation_context/CorrelationContext';
 import { SpanContext } from '../trace/span_context';
+import { ObserverResult } from './ObserverResult';
 /** An Instrument for Counter Metric. */
@@ -27,10 +28,2 @@ export interface BoundCounter {
 }
-/** An Instrument for Gauge Metric. */
-export interface BoundGauge {
-    /**
-     * Sets the given value. Values can be negative.
-     * @param value the new value.
-     */
-    set(value: number): void;
-}
 /** Measure to report instantaneous measurement of a value. */
@@ -41,3 +34,4 @@ export interface BoundMeasure {
      * @param value the measurement to record.
-     * @param distContext the distContext associated with the measurements.
+     * @param correlationContext the correlationContext associated with the
+     *     measurements.
      * @param spanContext the {@link SpanContext} that identifies the {@link Span}
@@ -47,4 +41,14 @@ *     for which the measurements are associated with.
     record(value: number): void;
-    record(value: number, distContext: DistributedContext): void;
-    record(value: number, distContext: DistributedContext, spanContext: SpanContext): void;
+    record(value: number, correlationContext: CorrelationContext): void;
+    record(value: number, correlationContext: CorrelationContext, spanContext: SpanContext): void;
 }
+/** Base interface for the Observer metrics. */
+export interface BoundObserver {
+    /**
+     * Sets callback for the observer. The callback is called once and then it
+     * sets observers for values. The observers are called periodically to
+     * retrieve the value.
+     * @param callback
+     */
+    setCallback(callback: (observerResult: ObserverResult) => {}): void;
+}

build/src/metrics/Meter.d.ts

@@ -17,8 +17,8 @@ /*!
 import { Metric, MetricOptions, Labels, LabelSet } from './Metric';
-import { BoundCounter, BoundGauge, BoundMeasure } from './BoundInstrument';
+import { BoundCounter, BoundMeasure, BoundObserver } from './BoundInstrument';
 /**
  * An interface to allow the recording metrics.
  *
- * {@link Metric}s are used for recording pre-defined aggregation (Gauge and
- * Counter), or raw values ({@link Measure}) in which the aggregation and labels
+ * {@link Metric}s are used for recording pre-defined aggregation (`Counter`),
+ * or raw values (`Measure`) in which the aggregation and labels
  * for the exported metric are deferred.
@@ -28,3 +28,3 @@ */
     /**
-     * Creates and returns a new {@link Measure}.
+     * Creates and returns a new `Measure`.
      * @param name the name of the metric.
@@ -35,3 +35,3 @@ * @param [options] the metric options.
     /**
-     * Creates a new counter metric. Generally, this kind of metric when the
+     * Creates a new `Counter` metric. Generally, this kind of metric when the
      * value is a quantity, the sum is of primary interest, and the event count
@@ -44,10 +44,7 @@ * and value distribution are not of primary interest.
     /**
-     * Creates a new gauge metric. Generally, this kind of metric should be used
-     * when the metric cannot be expressed as a sum or because the measurement
-     * interval is arbitrary. Use this kind of metric when the measurement is not
-     * a quantity, and the sum and event count are not of interest.
+     * Creates a new `Observer` metric.
      * @param name the name of the metric.
      * @param [options] the metric options.
      */
-    createGauge(name: string, options?: MetricOptions): Metric<BoundGauge>;
+    createObserver(name: string, options?: MetricOptions): Metric<BoundObserver>;
     /**
@@ -54,0 +51,0 @@ * Provide a pre-computed re-useable LabelSet by

build/src/metrics/MeterProvider.d.ts

@@ -22,4 +22,7 @@ /*!
     /**
-     * Returns a Meter, creating one if one with the given name and version is not already created
+     * Returns a Meter, creating one if one with the given name and version is
+     * not already created.
      *
+     * @param name The name of the meter or instrumentation library.
+     * @param version The version of the meter or instrumentation library.
      * @returns Meter A Meter with the given name and version
@@ -26,0 +29,0 @@ */

build/src/metrics/Metric.d.ts

@@ -16,4 +16,5 @@ /*!
  */
-import { DistributedContext } from '../distributed_context/DistributedContext';
+import { CorrelationContext } from '../correlation_context/CorrelationContext';
 import { SpanContext } from '../trace/span_context';
+import { ObserverResult } from './ObserverResult';
 /**
@@ -73,12 +74,10 @@ * Options needed for metric creation
      * calling this method for every operations.
-     * @param labels the canonicalized LabelSet used to associate with this metric instrument.
+     * @param labels the canonicalized LabelSet used to associate with this
+     *     metric instrument.
      */
     bind(labels: LabelSet): T;
     /**
-     * Returns a Instrument for a metric with all labels not set.
-     */
-    getDefaultBound(): T;
-    /**
      * Removes the Instrument from the metric, if it is present.
-     * @param labels the canonicalized LabelSet used to associate with this metric instrument.
+     * @param labels the canonicalized LabelSet used to associate with this
+     *     metric instrument.
      */
@@ -90,6 +89,2 @@ unbind(labels: LabelSet): void;
     clear(): void;
-    /**
-     * what should the callback signature be?
-     */
-    setCallback(fn: () => void): void;
 }
@@ -102,2 +97,8 @@ export interface MetricUtils {
     /**
+     * Sets a callback where user can observe value for certain labels
+     * @param callback a function that will be called once to set observers
+     *     for values
+     */
+    setCallback(callback: (observerResult: ObserverResult) => void): void;
+    /**
      * Sets the given value. Values can be negative.
@@ -110,4 +111,4 @@ */
     record(value: number, labelSet: LabelSet): void;
-    record(value: number, labelSet: LabelSet, distContext: DistributedContext): void;
-    record(value: number, labelSet: LabelSet, distContext: DistributedContext, spanContext: SpanContext): void;
+    record(value: number, labelSet: LabelSet, correlationContext: CorrelationContext): void;
+    record(value: number, labelSet: LabelSet, correlationContext: CorrelationContext, spanContext: SpanContext): void;
 }
@@ -114,0 +115,0 @@ /**

build/src/metrics/NoopMeter.d.ts

@@ -18,8 +18,9 @@ /*!
 import { MetricOptions, Metric, Labels, LabelSet, MetricUtils } from './Metric';
-import { BoundMeasure, BoundCounter, BoundGauge } from './BoundInstrument';
-import { DistributedContext } from '../distributed_context/DistributedContext';
+import { BoundMeasure, BoundCounter, BoundObserver } from './BoundInstrument';
+import { CorrelationContext } from '../correlation_context/CorrelationContext';
 import { SpanContext } from '../trace/span_context';
+import { ObserverResult } from './ObserverResult';
 /**
- * NoopMeter is a noop implementation of the {@link Meter} interface. It reuses constant
- * NoopMetrics for all of its methods.
+ * NoopMeter is a noop implementation of the {@link Meter} interface. It reuses
+ * constant NoopMetrics for all of its methods.
  */
@@ -41,7 +42,7 @@ export declare class NoopMeter implements Meter {
     /**
-     * Returns a constant gauge metric.
+     * Returns constant noop observer.
      * @param name the name of the metric.
      * @param [options] the metric options.
      */
-    createGauge(name: string, options?: MetricOptions): Metric<BoundGauge>;
+    createObserver(name: string, options?: MetricOptions): Metric<BoundObserver>;
     labels(labels: Labels): LabelSet;
@@ -54,5 +55,6 @@ }
      * Returns a Bound Instrument associated with specified LabelSet.
-     * It is recommended to keep a reference to the Bound Instrument instead of always
-     * calling this method for every operations.
-     * @param labels the canonicalized LabelSet used to associate with this metric instrument.
+     * It is recommended to keep a reference to the Bound Instrument instead of
+     * always calling this method for every operations.
+     * @param labels the canonicalized LabelSet used to associate with this
+     *     metric instrument.
      */
@@ -66,3 +68,4 @@ bind(labels: LabelSet): T;
      * Removes the Binding from the metric, if it is present.
-     * @param labels the canonicalized LabelSet used to associate with this metric instrument.
+     * @param labels the canonicalized LabelSet used to associate with this
+     *     metric instrument.
      */
@@ -79,20 +82,18 @@ unbind(labels: LabelSet): void;
 }
-export declare class NoopGaugeMetric extends NoopMetric<BoundGauge> implements Pick<MetricUtils, 'set'> {
-    set(value: number, labelSet: LabelSet): void;
-}
 export declare class NoopMeasureMetric extends NoopMetric<BoundMeasure> implements Pick<MetricUtils, 'record'> {
-    record(value: number, labelSet: LabelSet, distContext?: DistributedContext, spanContext?: SpanContext): void;
+    record(value: number, labelSet: LabelSet, correlationContext?: CorrelationContext, spanContext?: SpanContext): void;
 }
+export declare class NoopObserverMetric extends NoopMetric<BoundObserver> implements Pick<MetricUtils, 'setCallback'> {
+    setCallback(callback: (observerResult: ObserverResult) => void): void;
+}
 export declare class NoopBoundCounter implements BoundCounter {
     add(value: number): void;
 }
-export declare class NoopBoundGauge implements BoundGauge {
-    set(value: number): void;
-}
 export declare class NoopBoundMeasure implements BoundMeasure {
-    record(value: number, distContext?: DistributedContext, spanContext?: SpanContext): void;
+    record(value: number, correlationContext?: CorrelationContext, spanContext?: SpanContext): void;
 }
+export declare class NoopBoundObserver implements BoundObserver {
+    setCallback(callback: (observerResult: ObserverResult) => {}): void;
+}
 export declare const NOOP_METER: NoopMeter;
-export declare const NOOP_BOUND_GAUGE: NoopBoundGauge;
-export declare const NOOP_GAUGE_METRIC: NoopGaugeMetric;
 export declare const NOOP_BOUND_COUNTER: NoopBoundCounter;
@@ -102,2 +103,4 @@ export declare const NOOP_COUNTER_METRIC: NoopCounterMetric;
 export declare const NOOP_MEASURE_METRIC: NoopMeasureMetric;
+export declare const NOOP_BOUND_OBSERVER: NoopBoundObserver;
+export declare const NOOP_OBSERVER_METRIC: NoopObserverMetric;
 export declare const NOOP_LABEL_SET: LabelSet;

build/src/metrics/NoopMeter.js

@@ -19,4 +19,4 @@ "use strict";
 /**
- * NoopMeter is a noop implementation of the {@link Meter} interface. It reuses constant
- * NoopMetrics for all of its methods.
+ * NoopMeter is a noop implementation of the {@link Meter} interface. It reuses
+ * constant NoopMetrics for all of its methods.
  */
@@ -42,8 +42,8 @@ class NoopMeter {
     /**
-     * Returns a constant gauge metric.
+     * Returns constant noop observer.
      * @param name the name of the metric.
      * @param [options] the metric options.
      */
-    createGauge(name, options) {
-        return exports.NOOP_GAUGE_METRIC;
+    createObserver(name, options) {
+        return exports.NOOP_OBSERVER_METRIC;
     }
@@ -61,5 +61,6 @@ labels(labels) {
      * Returns a Bound Instrument associated with specified LabelSet.
-     * It is recommended to keep a reference to the Bound Instrument instead of always
-     * calling this method for every operations.
-     * @param labels the canonicalized LabelSet used to associate with this metric instrument.
+     * It is recommended to keep a reference to the Bound Instrument instead of
+     * always calling this method for every operations.
+     * @param labels the canonicalized LabelSet used to associate with this
+     *     metric instrument.
      */
@@ -77,6 +78,6 @@ bind(labels) {
      * Removes the Binding from the metric, if it is present.
-     * @param labels the canonicalized LabelSet used to associate with this metric instrument.
+     * @param labels the canonicalized LabelSet used to associate with this
+     *     metric instrument.
      */
     unbind(labels) {
-        // @todo: implement this method
         return;
@@ -101,18 +102,12 @@ }
 exports.NoopCounterMetric = NoopCounterMetric;
-class NoopGaugeMetric extends NoopMetric {
-    set(value, labelSet) {
-        this.bind(labelSet).set(value);
-    }
-}
-exports.NoopGaugeMetric = NoopGaugeMetric;
 class NoopMeasureMetric extends NoopMetric {
-    record(value, labelSet, distContext, spanContext) {
-        if (typeof distContext === 'undefined') {
+    record(value, labelSet, correlationContext, spanContext) {
+        if (typeof correlationContext === 'undefined') {
             this.bind(labelSet).record(value);
         }
         else if (typeof spanContext === 'undefined') {
-            this.bind(labelSet).record(value, distContext);
+            this.bind(labelSet).record(value, correlationContext);
         }
         else {
-            this.bind(labelSet).record(value, distContext, spanContext);
+            this.bind(labelSet).record(value, correlationContext, spanContext);
         }
@@ -122,2 +117,6 @@ }
 exports.NoopMeasureMetric = NoopMeasureMetric;
+class NoopObserverMetric extends NoopMetric {
+    setCallback(callback) { }
+}
+exports.NoopObserverMetric = NoopObserverMetric;
 class NoopBoundCounter {
@@ -129,10 +128,4 @@ add(value) {
 exports.NoopBoundCounter = NoopBoundCounter;
-class NoopBoundGauge {
-    set(value) {
-        return;
-    }
-}
-exports.NoopBoundGauge = NoopBoundGauge;
 class NoopBoundMeasure {
-    record(value, distContext, spanContext) {
+    record(value, correlationContext, spanContext) {
         return;
@@ -142,5 +135,7 @@ }
 exports.NoopBoundMeasure = NoopBoundMeasure;
+class NoopBoundObserver {
+    setCallback(callback) { }
+}
+exports.NoopBoundObserver = NoopBoundObserver;
 exports.NOOP_METER = new NoopMeter();
-exports.NOOP_BOUND_GAUGE = new NoopBoundGauge();
-exports.NOOP_GAUGE_METRIC = new NoopGaugeMetric(exports.NOOP_BOUND_GAUGE);
 exports.NOOP_BOUND_COUNTER = new NoopBoundCounter();
@@ -150,3 +145,5 @@ exports.NOOP_COUNTER_METRIC = new NoopCounterMetric(exports.NOOP_BOUND_COUNTER);
 exports.NOOP_MEASURE_METRIC = new NoopMeasureMetric(exports.NOOP_BOUND_MEASURE);
+exports.NOOP_BOUND_OBSERVER = new NoopBoundObserver();
+exports.NOOP_OBSERVER_METRIC = new NoopObserverMetric(exports.NOOP_BOUND_OBSERVER);
 exports.NOOP_LABEL_SET = {};
 //# sourceMappingURL=NoopMeter.js.map

build/src/trace/instrumentation/Plugin.d.ts

@@ -28,2 +28,6 @@ /*!
     /**
+     * Name of the module that the plugin instrument.
+     */
+    moduleName: string;
+    /**
      * Method that enables the instrumentation patch.
@@ -30,0 +34,0 @@ * @param moduleExports The value of the `module.exports` property that would

build/src/trace/link.d.ts

@@ -17,3 +17,3 @@ /*!
 import { Attributes } from './attributes';
-import { SpanContext } from './span_context';
+import { LinkContext } from './link_context';
 /**
@@ -25,6 +25,6 @@ * A pointer from the current {@link Span} to another span in the same trace or
 export interface Link {
-    /** The {@link SpanContext} of a linked span. */
-    spanContext: SpanContext;
+    /** The {@link LinkContext} of a linked span. */
+    context: LinkContext;
     /** A set of {@link Attributes} on the link. */
     attributes?: Attributes;
 }

build/src/trace/NoopSpan.d.ts

@@ -35,3 +35,2 @@ /*!
     addEvent(name: string, attributes?: Attributes): this;
-    addLink(spanContext: SpanContext, attributes?: Attributes): this;
     setStatus(status: Status): this;
@@ -38,0 +37,0 @@ updateName(name: string): this;

build/src/trace/NoopSpan.js

@@ -24,3 +24,3 @@ "use strict";
     spanId: exports.INVALID_SPAN_ID,
-    traceFlags: trace_flags_1.TraceFlags.UNSAMPLED,
+    traceFlags: trace_flags_1.TraceFlags.NONE,
 };
@@ -53,6 +53,2 @@ /**
     // By default does nothing
-    addLink(spanContext, attributes) {
-        return this;
-    }
-    // By default does nothing
     setStatus(status) {
@@ -59,0 +55,0 @@ return this;

build/src/trace/NoopTracer.d.ts

@@ -16,3 +16,3 @@ /*!
  */
-import { BinaryFormat, HttpTextFormat, Span, SpanOptions, Tracer } from '..';
+import { Span, SpanOptions, Tracer } from '..';
 /**
@@ -26,5 +26,3 @@ * No-op implementations of {@link Tracer}.
     bind<T>(target: T, span?: Span): T;
-    getBinaryFormat(): BinaryFormat;
-    getHttpTextFormat(): HttpTextFormat;
 }
 export declare const NOOP_TRACER: NoopTracer;

build/src/trace/NoopTracer.js

@@ -18,4 +18,2 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const NoopBinaryFormat_1 = require("../context/propagation/NoopBinaryFormat");
-const NoopHttpTextFormat_1 = require("../context/propagation/NoopHttpTextFormat");
 const NoopSpan_1 = require("./NoopSpan");
@@ -39,10 +37,2 @@ /**
     }
-    // By default does nothing
-    getBinaryFormat() {
-        return NoopBinaryFormat_1.NOOP_BINARY_FORMAT;
-    }
-    // By default does nothing
-    getHttpTextFormat() {
-        return NoopHttpTextFormat_1.NOOP_HTTP_TEXT_FORMAT;
-    }
 }
@@ -49,0 +39,0 @@ exports.NoopTracer = NoopTracer;

build/src/trace/span_context.d.ts

@@ -20,3 +20,3 @@ /*!
  * A SpanContext represents the portion of a {@link Span} which must be
- * serialized and propagated along side of a {@link DistributedContext}.
+ * serialized and propagated along side of a {@link CorrelationContext}.
  */
@@ -49,5 +49,5 @@ export interface SpanContext {
      *
-     * SAMPLED = 0x1 and UNSAMPLED = 0x0;
+     * SAMPLED = 0x1 and NONE = 0x0;
      */
-    traceFlags?: TraceFlags;
+    traceFlags: TraceFlags;
     /**
@@ -54,0 +54,0 @@ * Tracing-system-specific info to propagate.

build/src/trace/SpanOptions.d.ts

@@ -16,7 +16,7 @@ /*!
  */
-import { Span } from './span';
 import { Attributes } from './attributes';
+import { Link } from './link';
 import { SpanKind } from './span_kind';
+import { Span } from './span';
 import { SpanContext } from './span_context';
-import { Link } from './link';
 /**
@@ -33,12 +33,12 @@ * Options needed for span creation
     attributes?: Attributes;
-    /**
-     * Indicates that if this Span is active and recording information like
-     * events with the `AddEvent` operation and attributes using `setAttributes`.
-     */
-    isRecording?: boolean;
     /** A spans links */
     links?: Link[];
     /**
+     * This option is NOT RECOMMENDED for normal use and should ONLY be used
+     * if your application manages context manually without the global context
+     * manager, or you are trying to override the parent extracted from context.
+     *
      * A parent `SpanContext` (or `Span`, for convenience) that the newly-started
-     * span will be the child of.
+     * span will be the child of. This overrides the parent span extracted from
+     * the currently active context.
      */
@@ -45,0 +45,0 @@ parent?: Span | SpanContext | null;

build/src/trace/trace_flags.d.ts

@@ -22,6 +22,6 @@ /*!
 export declare enum TraceFlags {
-    /** Bit to represent whether trace is unsampled in trace flags. */
-    UNSAMPLED = 0,
+    /** Represents no flag set. */
+    NONE = 0,
     /** Bit to represent whether trace is sampled in trace flags. */
     SAMPLED = 1
 }

build/src/trace/trace_flags.js

@@ -25,4 +25,4 @@ "use strict";
 (function (TraceFlags) {
-    /** Bit to represent whether trace is unsampled in trace flags. */
-    TraceFlags[TraceFlags["UNSAMPLED"] = 0] = "UNSAMPLED";
+    /** Represents no flag set. */
+    TraceFlags[TraceFlags["NONE"] = 0] = "NONE";
     /** Bit to represent whether trace is sampled in trace flags. */
@@ -29,0 +29,0 @@ TraceFlags[TraceFlags["SAMPLED"] = 1] = "SAMPLED";

build/src/trace/tracer_provider.d.ts

@@ -22,6 +22,10 @@ /*!
     /**
-     * Returns a Tracer, creating one if one with the given name and version is not already created
+     * Returns a Tracer, creating one if one with the given name and version is
+     * not already created.
      *
-     * If there is no Span associated with the current context, null is returned.
+     * If there is no Span associated with the current context, `null` is
+     * returned.
      *
+     * @param name The name of the tracer or instrumentation library.
+     * @param version The version of the tracer or instrumentation library.
      * @returns Tracer A Tracer with the given name and version
@@ -28,0 +32,0 @@ */

build/src/trace/tracer.d.ts

@@ -16,4 +16,3 @@ /*!
  */
-import { HttpTextFormat } from '../context/propagation/HttpTextFormat';
-import { BinaryFormat } from '../context/propagation/BinaryFormat';
+import { Context } from '@opentelemetry/context-base';
 import { Span } from './span';
@@ -41,5 +40,6 @@ import { SpanOptions } from './SpanOptions';
      * @param [options] SpanOptions used for span creation
+     * @param [context] Context to use to extract parent
      * @returns Span The newly created span
      */
-    startSpan(name: string, options?: SpanOptions): Span;
+    startSpan(name: string, options?: SpanOptions, context?: Context): Span;
     /**
@@ -55,31 +55,8 @@ * Executes the function given by fn within the context provided by Span
     /**
-     * Bind a span as the target's scope or propagate the current one.
+     * Bind a span as the target's context or propagate the current one.
      *
-     * @param target Any object to which a scope need to be set
-     * @param [span] Optionally specify the span which you want to assign
+     * @param target Any object to which a context need to be set
+     * @param [context] Optionally specify the context which you want to bind
      */
-    bind<T>(target: T, span?: Span): T;
-    /**
-     * Returns the {@link BinaryFormat} interface which can serialize/deserialize
-     * Spans.
-     *
-     * If no tracer implementation is provided, this defaults to the W3C Trace
-     * Context binary format {@link BinaryFormat}. For more details see
-     * <a href="https://w3c.github.io/trace-context-binary/">W3C Trace Context
-     * binary protocol</a>.
-     *
-     * @returns the {@link BinaryFormat} for this implementation.
-     */
-    getBinaryFormat(): BinaryFormat;
-    /**
-     * Returns the {@link HttpTextFormat} interface which can inject/extract
-     * Spans.
-     *
-     * If no tracer implementation is provided, this defaults to the W3C Trace
-     * Context HTTP text format {@link HttpTextFormat}. For more details see
-     * <a href="https://w3c.github.io/trace-context/">W3C Trace Context</a>.
-     *
-     * @returns the {@link HttpTextFormat} for this implementation.
-     */
-    getHttpTextFormat(): HttpTextFormat;
+    bind<T>(target: T, context?: Span): T;
 }

build/src/version.d.ts

@@ -16,2 +16,2 @@ /*!
  */
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.5.0";

build/src/version.js

@@ -19,3 +19,3 @@ "use strict";
 // this is autogenerated file, see scripts/version-update.js
-exports.VERSION = '0.4.0';
+exports.VERSION = '0.5.0';
 //# sourceMappingURL=version.js.map

package.json

 {
   "name": "@opentelemetry/api",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Public API for OpenTelemetry",
@@ -9,3 +9,3 @@ "main": "build/src/index.js",
   "scripts": {
-    "test": "nyc ts-mocha -p tsconfig.json test/**/*.ts",
+    "test": "nyc ts-mocha -p tsconfig.json test/**/*.test.ts",
     "test:browser": "nyc karma start --single-run",
@@ -15,10 +15,11 @@ "codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p ../../",
     "build": "npm run compile",
-    "check": "gts check",
+    "lint": "gts check",
+    "lint:fix": "gts fix",
     "precompile": "tsc --version",
     "version:update": "node ../../scripts/version-update.js",
     "compile": "npm run version:update && tsc -p .",
-    "fix": "gts fix",
-    "docs-test": "linkinator docs/out --silent --skip david-dm.org --skip https://open-telemetry.github.io/opentelemetry-js/classes/.+api.html --skip https://www.npmjs.com/package/@opentelemetry/api",
-    "docs": "typedoc --tsconfig tsconfig.json",
-    "prepare": "npm run compile"
+    "docs-test": "linkinator docs/out --silent --skip david-dm.org",
+    "docs": "typedoc --tsconfig tsconfig.json --exclude test/**/*.ts",
+    "prepare": "npm run compile",
+    "watch": "tsc -w"
   },
@@ -50,2 +51,5 @@ "keywords": [
   },
+  "dependencies": {
+    "@opentelemetry/context-base": "^0.5.0"
+  },
   "devDependencies": {
@@ -64,3 +68,3 @@ "@types/mocha": "^5.2.7",
     "karma-webpack": "^4.0.2",
-    "linkinator": "^1.5.0",
+    "linkinator": "^2.0.3",
     "mocha": "^6.1.0",
@@ -67,0 +71,0 @@ "nyc": "^14.1.1",

README.md

@@ -10,10 +10,111 @@ # OpenTelemetry API for JavaScript
 
-## Basic Use
+## Quick Start
 
-### API Entry Point
+To get started tracing you need to install the SDK and plugins, create a TracerProvider, and register it with the API.
 
-API entry points are defined as global singleton objects `trace` and `metrics` which contain methods used to initialize SDK implementations and acquire resources from the API.
+### Install Dependencies
 
+```sh
+$ # Install tracing dependencies
+$ npm install \
+    @opentelemetry/core \
+    @opentelemetry/node \
+    @opentelemetry/tracing \
+    @opentelemetry/exporter-jaeger \ # add exporters as needed
+    @opentelemetry/plugin-http # add plugins as needed
+
+$ # Install metrics dependencies
+$ npm install \
+    @opentelemetry/metrics \
+    @opentelemetry/exporter-prometheus # add exporters as needed
+```
+
+### Initialize the SDK
+
+Before any other module in your application is loaded, you must initialize the global tracer and meter providers. If you fail to initialize a provider, no-op implementations will be provided to any library which acquires them from the API.
+
+To collect traces and metrics, you will have to tell the SDK where to export telemetry data to. This example uses Jaeger and Prometheus, but exporters exist for [other tracing backends][other-tracing-backends]. If you're not sure if there is an exporter for your tracing backend, contact your tracing provider.
+
+#### Tracing
+
+```javascript
+const { NodeTracerProvider } = require("@opentelemetry/node");
+const { SimpleSpanProcessor } = require("@opentelemetry/tracing");
+const { JaegerExporter } = require("@opentelemetry/exporter-jaeger");
+
+const tracerProvider = new NodeTracerProvider();
+
+/**
+ * The SimpleSpanProcessor does no batching and exports spans
+ * immediately when they end. For most production use cases,
+ * OpenTelemetry recommends use of the BatchSpanProcessor.
+ */
+tracerProvider.addSpanProcessor(
+  new SimpleSpanProcessor(
+    new JaegerExporter(
+      /* export options */
+    )
+  )
+);
+
+/**
+ * Registering the provider with the API allows it to be discovered
+ * and used by instrumentation libraries. The OpenTelemetry API provides
+ * methods to set global SDK implementations, but the default SDK provides
+ * a convenience method named `register` which registers sane defaults
+ * for you.
+ *
+ * By default the NodeTracerProvider uses Trace Context for propagation
+ * and AsyncHooksScopeManager for context management. To learn about
+ * customizing this behavior, see API Registration Options below.
+ */
+tracerProvider.register();
+```
+
+#### Metrics
+
+```javascript
+const api = require("@opentelemetry/api");
+const { MeterProvider } = require("@opentelemetry/metrics");
+const { PrometheusExporter } = require("@opentelemetry/exporter-prometheus");
+
+const meterProvider = new MeterProvider({
+  // The Prometheus exporter runs an HTTP server which
+  // the Prometheus backend scrapes to collect metrics.
+  exporter: new PrometheusExporter({ startServer: true }),
+  interval: 1000,
+});
+
+/**
+ * Registering the provider with the API allows it to be discovered
+ * and used by instrumentation libraries.
+ */
+api.metrics.setGlobalMeterProvider(meterProvider);
+```
+
+## Advanced Use
+### API Registration Options
+
+If you prefer to choose your own propagator or context manager, you may pass an options object into the `tracerProvider.register()` method. Omitted or `undefined` options will be replaced by a default value and `null` values will be skipped.
+
+```javascript
+const { B3Propagator } = require("@opentelemetry/core");
+
+tracerProvider.register({
+  // Use B3 Propagation
+  propagator: new B3Propagator(),
+
+  // Skip registering a default context manager
+  contextManager: null,
+})
+```
+
+### API Methods
+
+If you are writing an instrumentation library, or prefer to call the API methods directly rather than using the `register` method on the Tracer/Meter Provider, OpenTelemetry provides direct access to the underlying API methods through the `@opentelemetry/api` package. API entry points are defined as global singleton objects `trace`, `metrics`, `propagation`, and `context` which contain methods used to initialize SDK implementations and acquire resources from the API.
+
 - [Trace API Documentation][trace-api-docs]
 - [Metrics API Documentation][metrics-api-docs]
+- [Propagation API Documentation][propagation-api-docs]
+- [Context API Documentation][context-api-docs]
 
@@ -24,3 +125,3 @@ ```javascript
 /* Initialize TraceProvider */
-api.trace.initGlobalTracerProvider(traceProvider);
+api.trace.setGlobalTracerProvider(traceProvider);
 /* returns traceProvider (no-op if a working provider has not been initialized) */
@@ -32,3 +133,3 @@ api.trace.getTracerProvider();
 /* Initialize MeterProvider */
-api.metrics.initGlobalMeterProvider(meterProvider);
+api.metrics.setGlobalMeterProvider(meterProvider);
 /* returns meterProvider (no-op if a working provider has not been initialized) */
@@ -38,34 +139,8 @@ api.metrics.getMeterProvider();
 api.metrics.getMeter(name, version);
-```
 
-### Application Owners
+/* Initialize Propagator */
+api.propagation.setGlobalPropagator(httpTraceContextPropagator)
 
-Application owners will also need a working OpenTelemetry SDK implementation. OpenTelemetry provides working SDK implementations for [web] and [node] for both [tracing] and [metrics].
-
-#### Simple NodeJS Example
-
-Before any other module in your application is loaded, you must initialize the global tracer and meter registries. If you fail to initialize a provider, no-op implementations will be provided to any library which acquires them from the API.
-
-```javascript
-const api = require("@opentelemetry/api");
-const sdk = require("@opentelemetry/node");
-
-const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
-const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
-
-// Initialize an exporter
-const exporter = new JaegerExporter({
-  serviceName: 'basic-service'
-});
-
-// Create a provider which we will configure as the global tracer provider
-const provider = new sdk.NodeTracerProvider();
-
-// Configure span processor to send spans to the exporter
-provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
-
-// Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
-api.trace.initGlobalTracerProvider(provider);
-
-// your application code below this line
+/* Initialize Context Manager */
+api.context.setGlobalContextManager(asyncHooksContextManager);
 ```
@@ -119,6 +194,8 @@
 [npm-url]: https://www.npmjs.com/package/@opentelemetry/api
-[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Ftypes.svg
+[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fapi.svg
 
 [trace-api-docs]: https://open-telemetry.github.io/opentelemetry-js/classes/traceapi.html
 [metrics-api-docs]: https://open-telemetry.github.io/opentelemetry-js/classes/metricsapi.html
+[propagation-api-docs]: https://open-telemetry.github.io/opentelemetry-js/classes/propagationapi.html
+[context-api-docs]: https://open-telemetry.github.io/opentelemetry-js/classes/contextapi.html
 
@@ -128,2 +205,4 @@ [web]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-web
 [node]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-node
-[metrics]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-metrics
+[metrics]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-metrics
+
+[other-tracing-backends]: https://github.com/open-telemetry/opentelemetry-js#trace-exporters

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

150386

increased by9.87%

Number of package files

87

increased by4.82%

Lines of code

3290

increased by7.83%

Number of lines in readme file

203

increased by65.04%

Worsened metrics

Dependency count

1

increased byInfinity%

Dependency changes

• + Added@opentelemetry/context-base@^0.5.0

• + Added@opentelemetry/context-base@0.5.2(transitive)