From 177f672786f8b3ebf02d8083ec9354043e4e33a2 Mon Sep 17 00:00:00 2001 From: Mayur Kale Date: Thu, 28 May 2020 10:29:01 -0700 Subject: [PATCH] chore: improve API documentation (#1106) * chore: improve API documentation * chore: add @link * fix: code review Co-authored-by: Daniel Dyla --- packages/opentelemetry-api/README.md | 22 ++++++++------- .../context/propagation/HttpTextPropagator.ts | 14 ++++++---- .../src/metrics/MeterProvider.ts | 2 +- .../opentelemetry-api/src/metrics/Metric.ts | 15 ++++++++++ .../src/trace/NoopTracerProvider.ts | 6 ++-- .../src/trace/SpanOptions.ts | 4 +-- .../opentelemetry-api/src/trace/attributes.ts | 5 +++- packages/opentelemetry-api/src/trace/link.ts | 14 ++++++++-- packages/opentelemetry-api/src/trace/span.ts | 18 ++++++++++-- .../opentelemetry-api/src/trace/tracer.ts | 28 ++++++++++++++++--- .../src/trace/tracer_provider.ts | 6 ++-- 11 files changed, 101 insertions(+), 33 deletions(-) diff --git a/packages/opentelemetry-api/README.md b/packages/opentelemetry-api/README.md index 46ca4fd212..2e965c0fd4 100644 --- a/packages/opentelemetry-api/README.md +++ b/packages/opentelemetry-api/README.md @@ -9,13 +9,14 @@ This package provides everything needed to interact with the OpenTelemetry API, ## Quick Start -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. ### Install Dependencies ```sh $ # Install tracing dependencies $ npm install \ + @opentelemetry/api \ @opentelemetry/core \ @opentelemetry/node \ @opentelemetry/tracing \ @@ -28,6 +29,8 @@ $ npm install \ @opentelemetry/exporter-prometheus # add exporters as needed ``` +> 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 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. @@ -50,9 +53,9 @@ const tracerProvider = new NodeTracerProvider(); */ tracerProvider.addSpanProcessor( new SimpleSpanProcessor( - new JaegerExporter( - /* export options */ - ) + new JaegerExporter({ + serviceName: 'my-service' + }) ) ); @@ -124,18 +127,18 @@ If you are writing an instrumentation library, or prefer to call the API methods ```javascript const api = require("@opentelemetry/api"); -/* 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); /* Initialize MeterProvider */ api.metrics.setGlobalMeterProvider(meterProvider); /* returns meterProvider (no-op if a working provider has not been initialized) */ 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); /* Initialize Propagator */ @@ -172,7 +175,6 @@ async function doSomething() { } ``` - ## Useful links - For more information on OpenTelemetry, visit: - For more about OpenTelemetry JavaScript: diff --git a/packages/opentelemetry-api/src/context/propagation/HttpTextPropagator.ts b/packages/opentelemetry-api/src/context/propagation/HttpTextPropagator.ts index 84c5dbd03e..a95a0a4384 100644 --- a/packages/opentelemetry-api/src/context/propagation/HttpTextPropagator.ts +++ b/packages/opentelemetry-api/src/context/propagation/HttpTextPropagator.ts @@ -19,20 +19,22 @@ import { SetterFunction } from './setter'; import { GetterFunction } from './getter'; /** - * 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 * 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 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. * * @param context the Context from which to extract values to transmit over * the wire. @@ -44,7 +46,7 @@ export interface HttpTextPropagator { inject(context: Context, carrier: unknown, setter: SetterFunction): void; /** - * 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 * extracted values. * diff --git a/packages/opentelemetry-api/src/metrics/MeterProvider.ts b/packages/opentelemetry-api/src/metrics/MeterProvider.ts index 8802acb615..465dff91fe 100644 --- a/packages/opentelemetry-api/src/metrics/MeterProvider.ts +++ b/packages/opentelemetry-api/src/metrics/MeterProvider.ts @@ -17,7 +17,7 @@ import { Meter } from './Meter'; /** - * MeterProvider provides an interface for creating {@link Meter}s + * A registry for creating named {@link Meter}s. */ export interface MeterProvider { /** diff --git a/packages/opentelemetry-api/src/metrics/Metric.ts b/packages/opentelemetry-api/src/metrics/Metric.ts index 3c44696cc8..3996e5498b 100644 --- a/packages/opentelemetry-api/src/metrics/Metric.ts +++ b/packages/opentelemetry-api/src/metrics/Metric.ts @@ -106,6 +106,21 @@ export interface UnboundMetric extends Metric { unbind(labels: Labels): void; } +/** + * 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: + *
    + *
  1. count the number of bytes received.
    2. + *
  2. count the number of requests completed.
    3. + *
  3. count the number of accounts created.
    4. + *
  4. count the number of checkpoints run.
    5. + *
  5. count the number of 5xx errors.
    6. + *
      + */ export interface Counter extends UnboundMetric { /** * Adds the given value to the current value. Values cannot be negative. diff --git a/packages/opentelemetry-api/src/trace/NoopTracerProvider.ts b/packages/opentelemetry-api/src/trace/NoopTracerProvider.ts index 9398d51608..4eb66c056b 100644 --- a/packages/opentelemetry-api/src/trace/NoopTracerProvider.ts +++ b/packages/opentelemetry-api/src/trace/NoopTracerProvider.ts @@ -19,8 +19,10 @@ import { Tracer } from './tracer'; import { TracerProvider } from './tracer_provider'; /** - * 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. */ export class NoopTracerProvider implements TracerProvider { getTracer(_name?: string, _version?: string): Tracer { diff --git a/packages/opentelemetry-api/src/trace/SpanOptions.ts b/packages/opentelemetry-api/src/trace/SpanOptions.ts index bfda7e001c..13a2c2f389 100644 --- a/packages/opentelemetry-api/src/trace/SpanOptions.ts +++ b/packages/opentelemetry-api/src/trace/SpanOptions.ts @@ -30,10 +30,10 @@ export interface SpanOptions { */ kind?: SpanKind; - /** A spans attributes */ + /** A span's attributes */ attributes?: Attributes; - /** A spans links */ + /** {@link Link}s span to other spans */ links?: Link[]; /** diff --git a/packages/opentelemetry-api/src/trace/attributes.ts b/packages/opentelemetry-api/src/trace/attributes.ts index 188b1e574a..e0f0e922e3 100644 --- a/packages/opentelemetry-api/src/trace/attributes.ts +++ b/packages/opentelemetry-api/src/trace/attributes.ts @@ -14,7 +14,10 @@ * limitations under the License. */ -/** Defines a attributes interface. */ +/** + * Defines a attributes interface. + * These attributes provides additional data about the {@link Span}. + */ export interface Attributes { [attributeKey: string]: unknown; } diff --git a/packages/opentelemetry-api/src/trace/link.ts b/packages/opentelemetry-api/src/trace/link.ts index 2125b82b6c..4226bf1830 100644 --- a/packages/opentelemetry-api/src/trace/link.ts +++ b/packages/opentelemetry-api/src/trace/link.ts @@ -19,8 +19,18 @@ import { LinkContext } from './link_context'; /** * 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. */ export interface Link { /** The {@link LinkContext} of a linked span. */ diff --git a/packages/opentelemetry-api/src/trace/span.ts b/packages/opentelemetry-api/src/trace/span.ts index 2a725afdc2..8408a48d20 100644 --- a/packages/opentelemetry-api/src/trace/span.ts +++ b/packages/opentelemetry-api/src/trace/span.ts @@ -25,11 +25,17 @@ import { TimeInput } from '../common/Time'; * 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. + * + * Spans are created by the {@link Tracer.startSpan} method. */ export interface Span { /** * Returns the {@link SpanContext} object associated with this 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. */ context(): SpanContext; @@ -37,6 +43,8 @@ export interface Span { /** * Sets an attribute to the span. * + * Sets a single Attribute with the key and value passed as arguments. + * * @param key the key for this attribute. * @param value the value for this attribute. */ @@ -66,7 +74,8 @@ export interface Span { /** * 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. * * @param status the Status to set. */ @@ -75,6 +84,11 @@ export interface Span { /** * Updates the Span name. * + * 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. */ updateName(name: string): this; @@ -97,7 +111,7 @@ export interface Span { * Returns the flag whether this span will be recorded. * * @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`. */ isRecording(): boolean; } diff --git a/packages/opentelemetry-api/src/trace/tracer.ts b/packages/opentelemetry-api/src/trace/tracer.ts index e57f2ee176..f7edc856a0 100644 --- a/packages/opentelemetry-api/src/trace/tracer.ts +++ b/packages/opentelemetry-api/src/trace/tracer.ts @@ -29,28 +29,48 @@ export interface Tracer { /** * Returns the current Span from the current context if available. * - * 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 */ getCurrentSpan(): Span | undefined; /** - * 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 * @param [options] SpanOptions used for span creation * @param [context] Context to use to extract parent * @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. + * }); */ withSpan ReturnType>( span: Span, diff --git a/packages/opentelemetry-api/src/trace/tracer_provider.ts b/packages/opentelemetry-api/src/trace/tracer_provider.ts index 63c6c50285..df5e576e90 100644 --- a/packages/opentelemetry-api/src/trace/tracer_provider.ts +++ b/packages/opentelemetry-api/src/trace/tracer_provider.ts @@ -17,15 +17,15 @@ import { Tracer } from './tracer'; /** - * TracerProvider provides an interface for creating {@link Tracer}s + * A registry for creating named {@link Tracer}s. */ export interface TracerProvider { /** * 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. + * This function may return different Tracer types (e.g. + * {@link NoopTracerProvider} vs. a functional tracer). * * @param name The name of the tracer or instrumentation library. * @param version The version of the tracer or instrumentation library.