diff --git a/doc/plugin-guide.md b/doc/plugin-guide.md index dfabec26089..497fa82fa6f 100644 --- a/doc/plugin-guide.md +++ b/doc/plugin-guide.md @@ -1,6 +1,6 @@ # Plugin Developer Guide -The `NodeTracer` or `Node-SDK` is driven by a set of plugins that describe how to patch a module to generate trace spans when that module is used. We provide out-of-the-box instrumentation for many popular frameworks and libraries by using a plugin system (see [builtin plugins][builtin-plugins]), and provide a means for developers to create their own. +The `NodeTracerProvider` or `Node-SDK` is driven by a set of plugins that describe how to patch a module to generate trace spans when that module is used. We provide out-of-the-box instrumentation for many popular frameworks and libraries by using a plugin system (see [builtin plugins][builtin-plugins]), and provide a means for developers to create their own. We strongly recommended to create a dedicated package for newly added plugin, example: `@opentelemetry/plugin-xxx`. diff --git a/packages/opentelemetry-api/src/metrics/Meter.ts b/packages/opentelemetry-api/src/metrics/Meter.ts index dec54e8a9f4..4623176c900 100644 --- a/packages/opentelemetry-api/src/metrics/Meter.ts +++ b/packages/opentelemetry-api/src/metrics/Meter.ts @@ -20,20 +20,20 @@ import { BoundCounter, BoundGauge, BoundMeasure } 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 (`Gauge` and + * `Counter`), or raw values (`Measure`) in which the aggregation and labels * for the exported metric are deferred. */ export interface Meter { /** - * Creates and returns a new {@link Measure}. + * Creates and returns a new `Measure`. * @param name the name of the metric. * @param [options] the metric options. */ createMeasure(name: string, options?: MetricOptions): Metric; /** - * 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 * and value distribution are not of primary interest. * @param name the name of the metric. @@ -41,16 +41,8 @@ export interface Meter { */ createCounter(name: string, options?: MetricOptions): Metric; - // TODO: Measurements can have a long or double type. However, it looks like - // the metric timeseries API (according to spec) accepts values instead of - // Measurements, meaning that if you accept a `number`, the type gets lost. - // Both java and csharp have gone down the route of having two gauge interfaces, - // GaugeDoubleTimeseries and GaugeLongTimeseries, with param for that type. It'd - // be cool to only have a single interface, but maybe having two is necessary? - // Maybe include the type as a metrics option? Probs a good gh issue, the same goes for Measure types. - /** - * Creates a new gauge metric. Generally, this kind of metric should be used + * 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. diff --git a/packages/opentelemetry-api/src/metrics/MeterProvider.ts b/packages/opentelemetry-api/src/metrics/MeterProvider.ts index ac682e238d4..8802acb6156 100644 --- a/packages/opentelemetry-api/src/metrics/MeterProvider.ts +++ b/packages/opentelemetry-api/src/metrics/MeterProvider.ts @@ -21,8 +21,11 @@ import { Meter } from './Meter'; */ export interface MeterProvider { /** - * 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 */ getMeter(name: string, version?: string): Meter; diff --git a/packages/opentelemetry-api/src/metrics/Metric.ts b/packages/opentelemetry-api/src/metrics/Metric.ts index 0c6ca61a708..6c9d84fb1e9 100644 --- a/packages/opentelemetry-api/src/metrics/Metric.ts +++ b/packages/opentelemetry-api/src/metrics/Metric.ts @@ -81,7 +81,8 @@ export interface Metric { * Returns a Instrument associated with specified LabelSet. * It is recommended to keep a reference to the Instrument instead of always * 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; @@ -92,7 +93,8 @@ export interface Metric { /** * 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. */ unbind(labels: LabelSet): void; diff --git a/packages/opentelemetry-api/src/metrics/NoopMeter.ts b/packages/opentelemetry-api/src/metrics/NoopMeter.ts index c39a664aa57..df468329619 100644 --- a/packages/opentelemetry-api/src/metrics/NoopMeter.ts +++ b/packages/opentelemetry-api/src/metrics/NoopMeter.ts @@ -21,8 +21,8 @@ import { DistributedContext } from '../distributed_context/DistributedContext'; import { SpanContext } from '../trace/span_context'; /** - * 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. */ export class NoopMeter implements Meter { constructor() {} @@ -67,9 +67,10 @@ export class NoopMetric implements Metric { } /** * 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. */ bind(labels: LabelSet): T { return this._instrument; @@ -84,10 +85,10 @@ export class NoopMetric implements Metric { /** * 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: LabelSet): void { - // @todo: implement this method return; } diff --git a/packages/opentelemetry-api/src/trace/tracer_provider.ts b/packages/opentelemetry-api/src/trace/tracer_provider.ts index 1093210ae4c..63c6c50285a 100644 --- a/packages/opentelemetry-api/src/trace/tracer_provider.ts +++ b/packages/opentelemetry-api/src/trace/tracer_provider.ts @@ -21,10 +21,14 @@ import { Tracer } from './tracer'; */ export interface TracerProvider { /** - * 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 */ getTracer(name: string, version?: string): Tracer; diff --git a/packages/opentelemetry-metrics/src/Metric.ts b/packages/opentelemetry-metrics/src/Metric.ts index f9a010dfd83..65321f3c02b 100644 --- a/packages/opentelemetry-metrics/src/Metric.ts +++ b/packages/opentelemetry-metrics/src/Metric.ts @@ -77,7 +77,8 @@ export abstract class Metric /** * Removes the Instrument from the metric, if it is present. - * @param labelSet the canonicalized LabelSet used to associate with this metric instrument. + * @param labelSet the canonicalized LabelSet used to associate with this + * metric instrument. */ unbind(labelSet: types.LabelSet): void { this._instruments.delete(labelSet.identifier); diff --git a/packages/opentelemetry-node/test/NodeTracer.test.ts b/packages/opentelemetry-node/test/NodeTracerProvider.test.ts similarity index 100% rename from packages/opentelemetry-node/test/NodeTracer.test.ts rename to packages/opentelemetry-node/test/NodeTracerProvider.test.ts diff --git a/packages/opentelemetry-web/README.md b/packages/opentelemetry-web/README.md index 54e6a8d94cc..ce14ca59fd1 100644 --- a/packages/opentelemetry-web/README.md +++ b/packages/opentelemetry-web/README.md @@ -11,17 +11,17 @@ For manual instrumentation see the [@opentelemetry/tracing](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-tracing) package. ## How does automatic tracing work? -This package exposes a class `WebTracer` that will be able to automatically trace things in Browser only. +This package exposes a class `WebTracerProvider` that will be able to automatically trace things in Browser only. See the example how to use it. OpenTelemetry comes with a growing number of instrumentation plugins for well know modules (see [supported modules](https://github.com/open-telemetry/opentelemetry-js#plugins)) and an API to create custom plugins (see [the plugin developer guide](https://github.com/open-telemetry/opentelemetry-js/blob/master/doc/plugin-guide.md)). Web Tracer currently supports one plugin for document load. -Unlike Node Tracer, the plugins needs to be initialised and passed in configuration. -The reason is to give user full control over which plugin will be bundled into web page. +Unlike Node Tracer (`NodeTracerProvider`), the plugins needs to be initialised and passed in configuration. +The reason is to give user full control over which plugin will be bundled into web page. -You can choose to use the ZoneScopeManager if you want to trace asynchronous operations. +You can choose to use the `ZoneScopeManager` if you want to trace asynchronous operations. ## Installation @@ -33,27 +33,27 @@ npm install --save @opentelemetry/web ```js import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/tracing'; -import { WebTracer } from '@opentelemetry/web'; +import { WebTracerProvider } from '@opentelemetry/web'; import { DocumentLoad } from '@opentelemetry/plugin-document-load'; import { ZoneScopeManager } from '@opentelemetry/scope-zone'; // Minimum required setup - supports only synchronous operations -const webTracer = new WebTracer({ +const provider = new WebTracerProvider({ plugins: [ new DocumentLoad() ] }); -webTracer.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); +provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); // Changing default scopeManager to use ZoneScopeManager - supports asynchronous operations -const webTracerWithZone = new WebTracer({ +const providerWithZone = new WebTracerProvider({ scopeManager: new ZoneScopeManager(), plugins: [ new DocumentLoad() ] }); -webTracerWithZone.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); +providerWithZone.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); ``` diff --git a/packages/opentelemetry-web/test/WebTracer.test.ts b/packages/opentelemetry-web/test/WebTracerProvider.test.ts similarity index 99% rename from packages/opentelemetry-web/test/WebTracer.test.ts rename to packages/opentelemetry-web/test/WebTracerProvider.test.ts index 1232cb0cc22..266cd119ae8 100644 --- a/packages/opentelemetry-web/test/WebTracer.test.ts +++ b/packages/opentelemetry-web/test/WebTracerProvider.test.ts @@ -33,7 +33,7 @@ class DummyPlugin extends BasePlugin { unpatch() {} } -describe('WebTracer', () => { +describe('WebTracerProvider', () => { describe('constructor', () => { let defaultOptions: WebTracerConfig;