@opentelemetry/api - npm Package Compare versions

Comparing version 0.8.2 to 0.8.3

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

@@ -20,3 +20,3 @@ /*!
 /**
- * Injects {@link Context} into and extracts it from carriers that travel
+ * Injects `Context` into and extracts it from carriers that travel
  * in-band across process boundaries. Encoding is expected to conform to the
@@ -27,10 +27,12 @@ * HTTP Header Field semantics. Values are often encoded as RPC/HTTP request
  * The carrier of propagated data on both the client (injector) and server
- * (extractor) side is usually an object such as http headers.
+ * (extractor) side is usually an object such as http headers. Propagation is
+ * usually implemented via library-specific request interceptors, where the
+ * client-side injects values and the server-side extracts them.
  */
 export interface HttpTextPropagator {
     /**
-     * Injects values from a given {@link Context} into a carrier.
+     * Injects values from a given `Context` into a carrier.
      *
-     * OpenTelemetry defines a common set of format values (HttpTextPropagator), and
-     * each has an expected `carrier` type.
+     * OpenTelemetry defines a common set of format values (HttpTextPropagator),
+     * and each has an expected `carrier` type.
      *
@@ -46,3 +48,3 @@ * @param context the Context from which to extract values to transmit over
     /**
-     * Given a {@link Context} and a carrier, extract context values from a
+     * Given a `Context` and a carrier, extract context values from a
      * carrier and return a new context, created from the old context, with the
@@ -49,0 +51,0 @@ * extracted values.

build/src/metrics/MeterProvider.d.ts

@@ -18,3 +18,3 @@ /*!
 /**
- * MeterProvider provides an interface for creating {@link Meter}s
+ * A registry for creating named {@link Meter}s.
  */
@@ -21,0 +21,0 @@ export interface MeterProvider {

build/src/metrics/Metric.d.ts

@@ -94,2 +94,17 @@ /*!
 }
+/**
+ * Counter is the most common synchronous instrument. This instrument supports
+ * an `Add(increment)` function for reporting a sum, and is restricted to
+ * non-negative increments. The default aggregation is Sum, as for any additive
+ * instrument.
+ *
+ * Example uses for Counter:
+ * <ol>
+ *   <li> count the number of bytes received. </li>
+ *   <li> count the number of requests completed. </li>
+ *   <li> count the number of accounts created. </li>
+ *   <li> count the number of checkpoints run. </li>
+ *   <li> count the number of 5xx errors. </li>
+ * <ol>
+ */
 export interface Counter extends UnboundMetric<BoundCounter> {
@@ -96,0 +111,0 @@ /**

build/src/platform/node/globalThis.d.ts

@@ -16,6 +16,4 @@ /*!
  */
-/// <reference types="mocha" />
-/// <reference types="node" />
 /** only globals that common to node and browsers are allowed */
-export declare const _globalThis: typeof globalThis | NodeJS.Global;
+export declare const _globalThis: typeof globalThis;
 //# sourceMappingURL=globalThis.d.ts.map

build/src/trace/attributes.d.ts

@@ -16,3 +16,6 @@ /*!
  */
-/** Defines a attributes interface. */
+/**
+ * Defines a attributes interface.
+ * These attributes provides additional data about the {@link Span}.
+ */
 export interface Attributes {
@@ -19,0 +22,0 @@ [attributeKey: string]: unknown;

build/src/trace/link.d.ts

@@ -20,4 +20,14 @@ /*!
  * A pointer from the current {@link Span} to another span in the same trace or
- * in a different trace. Used (for example) in batching operations, where a
- * single batch handler processes multiple requests from different traces.
+ * in a different trace.
+ * Few examples of Link usage.
+ * 1. Batch Processing: A batch of elements may contain elements associated
+ *    with one or more traces/spans. Since there can only be one parent
+ *    SpanContext, Link is used to keep reference to SpanContext of all
+ *    elements in the batch.
+ * 2. Public Endpoint: A SpanContext in incoming client request on a public
+ *    endpoint is untrusted from service provider perspective. In such case it
+ *    is advisable to start a new trace with appropriate sampling decision.
+ *    However, it is desirable to associate incoming SpanContext to new trace
+ *    initiated on service provider side so two traces (from Client and from
+ *    Service Provider) can be correlated.
  */
@@ -24,0 +34,0 @@ export interface Link {

build/src/trace/NoopTracerProvider.d.ts

@@ -19,4 +19,6 @@ /*!
 /**
- * An implementation of the {@link TracerProvider} which returns an impotent Tracer
- * for all calls to `getTracer`
+ * An implementation of the {@link TracerProvider} which returns an impotent
+ * Tracer for all calls to `getTracer`.
+ *
+ * All operations are no-op.
  */
@@ -23,0 +25,0 @@ export declare class NoopTracerProvider implements TracerProvider {

build/src/trace/NoopTracerProvider.js

@@ -20,4 +20,6 @@ "use strict";
 /**
- * An implementation of the {@link TracerProvider} which returns an impotent Tracer
- * for all calls to `getTracer`
+ * An implementation of the {@link TracerProvider} which returns an impotent
+ * Tracer for all calls to `getTracer`.
+ *
+ * All operations are no-op.
  */
@@ -24,0 +26,0 @@ class NoopTracerProvider {

build/src/trace/span.d.ts

@@ -26,2 +26,4 @@ /*!
  * may have children.
+ *
+ * Spans are created by the {@link Tracer.startSpan} method.
  */
@@ -32,2 +34,6 @@ export interface Span {
      *
+     * Get an immutable, serializable identifier for this span that can be used
+     * to create new child spans. Returned SpanContext is usable even after the
+     * span ends.
+     *
      * @returns the SpanContext object associated with this Span.
@@ -39,2 +45,4 @@ */
      *
+     * Sets a single Attribute with the key and value passed as arguments.
+     *
      * @param key the key for this attribute.
@@ -62,3 +70,4 @@ * @param value the value for this attribute.
      * Sets a status to the span. If used, this will override the default Span
-     * status. Default is {@link CanonicalCode.OK}.
+     * status. Default is {@link CanonicalCode.OK}. SetStatus overrides the value
+     * of previous calls to SetStatus on the Span.
      *
@@ -71,2 +80,7 @@ * @param status the Status to set.
      *
+     * This will override the name provided via {@link Tracer.startSpan}.
+     *
+     * Upon this update, any sampling behavior based on Span name will depend on
+     * the implementation.
+     *
      * @param name the Span name.
@@ -92,3 +106,3 @@ */
      * @returns true if this Span is active and recording information like events
-     * with the AddEvent operation and attributes using setAttributes.
+     *     with the `AddEvent` operation and attributes using `setAttributes`.
      */
@@ -95,0 +109,0 @@ isRecording(): boolean;

build/src/trace/SpanOptions.d.ts

@@ -30,5 +30,5 @@ /*!
     kind?: SpanKind;
-    /** A spans attributes */
+    /** A span's attributes */
     attributes?: Attributes;
-    /** A spans links */
+    /** {@link Link}s span to other spans */
     links?: Link[];
@@ -35,0 +35,0 @@ /**

build/src/trace/tracer_provider.d.ts

@@ -18,3 +18,3 @@ /*!
 /**
- * TracerProvider provides an interface for creating {@link Tracer}s
+ * A registry for creating named {@link Tracer}s.
  */
@@ -26,4 +26,4 @@ export interface TracerProvider {
      *
-     * If there is no Span associated with the current context, `null` is
-     * returned.
+     * This function may return different Tracer types (e.g.
+     * {@link NoopTracerProvider} vs. a functional tracer).
      *
@@ -30,0 +30,0 @@ * @param name The name of the tracer or instrumentation library.

build/src/trace/tracer.d.ts

@@ -30,4 +30,8 @@ /*!
      *
-     * 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.
      *
+     * To install a {@link Span} to the current Context use
+     * {@link Tracer.withSpan}.
+     *
      * @returns Span The currently active Span
@@ -37,3 +41,8 @@ */
     /**
-     * Starts a new {@link Span}.
+     * Starts a new {@link Span}. Start the span without setting it as the current
+     * span in this tracer's context.
+     *
+     * This method do NOT modify the current Context. To install a {@link
+     * Span} to the current Context use {@link Tracer.withSpan}.
+     *
      * @param name The name of the span
@@ -43,11 +52,22 @@ * @param [options] SpanOptions used for span creation
      * @returns Span The newly created span
+     * @example
+     *     const span = tracer.startSpan('op');
+     *     span.setAttribute('key', 'value');
+     *     span.end();
      */
     startSpan(name: string, options?: SpanOptions, context?: Context): Span;
     /**
-     * Executes the function given by fn within the context provided by Span
+     * Executes the function given by fn within the context provided by Span.
      *
+     * This is a convenience method for creating spans attached to the tracer's
+     * context. Applications that need more control over the span lifetime should
+     * use {@link Tracer.startSpan} instead.
+     *
      * @param span The span that provides the context
      * @param fn The function to be executed inside the provided context
      * @example
-     * tracer.withSpan(span, function() { ... });
+     *     tracer.withSpan(span, () => {
+     *         tracer.getCurrentSpan().addEvent("parent's event");
+     *         doSomeOtherWork();  // Here "span" is the current Span.
+     *     });
      */
@@ -54,0 +74,0 @@ withSpan<T extends (...args: unknown[]) => ReturnType<T>>(span: Span, fn: T): ReturnType<T>;

build/src/version.d.ts

@@ -1,2 +0,2 @@
-export declare const VERSION = "0.8.2";
+export declare const VERSION = "0.8.3";
 //# sourceMappingURL=version.d.ts.map

build/src/version.js

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

package.json

 {
   "name": "@opentelemetry/api",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Public API for OpenTelemetry",
@@ -54,8 +54,8 @@ "main": "build/src/index.js",
   "dependencies": {
-    "@opentelemetry/context-base": "^0.8.2"
+    "@opentelemetry/context-base": "^0.8.3"
   },
   "devDependencies": {
     "@types/mocha": "^7.0.0",
-    "@types/node": "^12.6.8",
-    "@types/webpack-env": "1.13.9",
+    "@types/node": "^14.0.5",
+    "@types/webpack-env": "1.15.2",
     "codecov": "^3.6.1",
@@ -62,0 +62,0 @@ "gts": "^2.0.0",

README.md

@@ -12,3 +12,3 @@ # OpenTelemetry API for JavaScript
 
-To get started tracing you need to install the SDK and plugins, create a TracerProvider, and register it with the API.
+To get started you need to install the SDK and plugins, create a TracerProvider and/or MeterProvider, and register it with the API.
 
@@ -20,2 +20,3 @@ ### Install Dependencies
 $ npm install \
+    @opentelemetry/api \
     @opentelemetry/core \
@@ -33,2 +34,4 @@ @opentelemetry/node \
 
+> Note: this example is for node.js. See [examples/tracer-web](https://github.com/open-telemetry/opentelemetry-js/tree/master/examples/tracer-web) for a browser example.
+
 ### Initialize the SDK
@@ -56,5 +59,5 @@
   new SimpleSpanProcessor(
-    new JaegerExporter(
-      /* export options */
-    )
+    new JaegerExporter({
+      serviceName: 'my-service'
+    })
   )
@@ -131,7 +134,7 @@ );
 
-/* Initialize TraceProvider */
-api.trace.setGlobalTracerProvider(traceProvider);
-/* returns traceProvider (no-op if a working provider has not been initialized) */
+/* Initialize TracerProvider */
+api.trace.setGlobalTracerProvider(tracerProvider);
+/* returns tracerProvider (no-op if a working provider has not been initialized) */
 api.trace.getTracerProvider();
-/* returns a tracer from the registered global tracer provider (no-op if a working provider has not been initialized); */
+/* returns a tracer from the registered global tracer provider (no-op if a working provider has not been initialized) */
 api.trace.getTracer(name, version);
@@ -143,3 +146,3 @@
 api.metrics.getMeterProvider();
-/* returns a meter from the registered global meter provider (no-op if a working provider has not been initialized); */
+/* returns a meter from the registered global meter provider (no-op if a working provider has not been initialized) */
 api.metrics.getMeter(name, version);
@@ -181,3 +184,2 @@
 
-
 ## Useful links
@@ -184,0 +186,0 @@ - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

No alert changes

Improved metrics

Total package byte prevSize

166325

increased by1.86%

Lines of code

3544

increased by1.9%

Number of lines in readme file

209

increased by0.97%

Dependency changes

• Updated@opentelemetry/context-base@^0.8.3