feature(trace): adds named tracer factory

examples/basic-tracer-node/index.js

@@ -1,5 +1,5 @@
 const opentelemetry = require('@opentelemetry/core');
-const { BasicTracer, SimpleSpanProcessor } = require('@opentelemetry/tracing');
+const { BasicTracerFactory, SimpleSpanProcessor } = require('@opentelemetry/tracing');
 const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
 const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin');
 
@@ -17,14 +17,14 @@ if (EXPORTER.toLowerCase().startsWith('z')) {
   exporter = new JaegerExporter(options);
 }
 
-const tracer = new BasicTracer();
+// Initialize the OpenTelemetry APIs to use the BasicTracer bindings
+opentelemetry.initGlobalTracerFactory(new BasicTracerFactory());
+
+const tracer = opentelemetry.getTracer();
 
 // Configure span processor to send spans to the provided exporter
 tracer.addSpanProcessor(new SimpleSpanProcessor(exporter));
 
-// Initialize the OpenTelemetry APIs to use the BasicTracer bindings
-opentelemetry.initGlobalTracer(tracer);
-
 // Create a span. A span must be closed.
 const span = opentelemetry.getTracer().startSpan('main');
 for (let i = 0; i < 10; i++) {

examples/grpc/setup.js

@@ -1,14 +1,14 @@
 'use strict';
 
 const opentelemetry = require('@opentelemetry/core');
-const { NodeTracer } = require('@opentelemetry/node');
+const { NodeTracerFactory } = require('@opentelemetry/node');
 const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
 const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
 const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin');
 const EXPORTER = process.env.EXPORTER || '';
 
 function setupTracerAndExporters(service) {
-  const tracer = new NodeTracer({
+  const factory = new NodeTracerFactory({
     plugins: {
       grpc: {
         enabled: true,
@@ -17,6 +17,7 @@ function setupTracerAndExporters(service) {
       }
     }
   });
+  const tracer = factory.getTracer();
 
   let exporter;
   if (EXPORTER.toLowerCase().startsWith('z')) {
@@ -33,8 +34,8 @@ function setupTracerAndExporters(service) {
 
   tracer.addSpanProcessor(new SimpleSpanProcessor(exporter));
 
-  // Initialize the OpenTelemetry APIs to use the BasicTracer bindings
-  opentelemetry.initGlobalTracer(tracer);
+  // Initialize the OpenTelemetry APIs to use the BasicTracerFactory bindings
+  opentelemetry.initGlobalTracerFactory(factory);
 }
 
 exports.setupTracerAndExporters = setupTracerAndExporters;

examples/http/setup.js

@@ -1,14 +1,15 @@
 'use strict';
 
 const opentelemetry = require('@opentelemetry/core');
-const { NodeTracer } = require('@opentelemetry/node');
+const { NodeTracerFactory } = require('@opentelemetry/node');
 const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
 const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
 const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin');
 const EXPORTER = process.env.EXPORTER || '';
 
 function setupTracerAndExporters(service) {
-  const tracer = new NodeTracer();
+  const factory = new NodeTracerFactory();
+  const tracer = factory.getTracer();
 
   let exporter;
   if (EXPORTER.toLowerCase().startsWith('z')) {
@@ -26,7 +27,7 @@ function setupTracerAndExporters(service) {
   tracer.addSpanProcessor(new SimpleSpanProcessor(exporter));
 
   // Initialize the OpenTelemetry APIs to use the BasicTracer bindings
-  opentelemetry.initGlobalTracer(tracer);
+  opentelemetry.initGlobalTracerFactory(factory);
 }
 
 exports.setupTracerAndExporters = setupTracerAndExporters;

examples/https/setup.js

@@ -1,15 +1,17 @@
 'use strict';
 
 const opentelemetry = require('@opentelemetry/core');
-const { NodeTracer } = require('@opentelemetry/node');
+const { NodeTracerFactory } = require('@opentelemetry/node');
 const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
 const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
 const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin');
 const EXPORTER = process.env.EXPORTER || '';
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+
 function setupTracerAndExporters(service) {
   let exporter;
-  const tracer = new NodeTracer();
+  const factory = new NodeTracerFactory();
+  const tracer = factory.getTracer();
 
   if (EXPORTER.toLowerCase().startsWith('z')) {
     exporter = new ZipkinExporter({
@@ -26,7 +28,7 @@ function setupTracerAndExporters(service) {
   tracer.addSpanProcessor(new SimpleSpanProcessor(exporter));
 
   // Initialize the OpenTelemetry APIs to use the BasicTracer bindings
-  opentelemetry.initGlobalTracer(tracer);
+  opentelemetry.initGlobalTracerFactory(factory);
 }
 
 exports.setupTracerAndExporters = setupTracerAndExporters;

packages/opentelemetry-core/src/index.ts

@@ -26,9 +26,10 @@ export * from './trace/globaltracer-utils';
 export * from './trace/instrumentation/BasePlugin';
 export * from './trace/NoopSpan';
 export * from './trace/NoopTracer';
+export * from './trace/NoopTracerFactory';
 export * from './trace/NoRecordingSpan';
 export * from './trace/sampler/ProbabilitySampler';
 export * from './trace/spancontext-utils';
-export * from './trace/TracerDelegate';
+export * from './trace/TracerFactoryDelegate';
 export * from './trace/TraceState';
 export * from './metrics/NoopMeter';

packages/opentelemetry-core/src/trace/NoopTracerFactory.ts

@@ -0,0 +1,30 @@
+/*!
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as types from '@opentelemetry/types';
+import { NoopTracer } from './NoopTracer';
+
+export class NoopTracerFactory implements types.TracerFactory {
+  private readonly _tracer: types.Tracer;
+
+  constructor() {
+    this._tracer = new NoopTracer();
+  }
+
+  getTracer(name?: string, version?: string): types.Tracer {
+    return this._tracer;
+  }
+}

packages/opentelemetry-core/src/trace/TracerFactoryDelegate.ts

@@ -0,0 +1,64 @@
+/*!
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as types from '@opentelemetry/types';
+import { NoopTracerFactory } from './NoopTracerFactory';
+
+// Acts a bridge to the global tracer factory that can be safely called before the
+// global tracer factory is initialized. The purpose of the delegation is to avoid the
+// sometimes nearly intractable initialization order problems that can arise in
+// applications with a complex set of dependencies. Also allows for the factory
+// to be changed/disabled during runtime without needing to change reference
+// to the global factory.
+export class TracerFactoryDelegate implements types.TracerFactory {
+  private _currentTracerFactory: types.TracerFactory;
+  private readonly _tracerFactory: types.TracerFactory | null;
+  private readonly _fallbackTracerFactory: types.TracerFactory;
+
+  // Wrap a TracerFactory with a TracerDelegateFactory. Provided factory becomes the default
+  // fallback factory for when a global factory has not been initialized
+  constructor(
+    tracerFactory?: types.TracerFactory,
+    fallbackTracerFactory?: types.TracerFactory
+  ) {
+    this._tracerFactory = tracerFactory || null;
+    this._fallbackTracerFactory =
+      fallbackTracerFactory || new NoopTracerFactory();
+    this._currentTracerFactory =
+      this._tracerFactory || this._fallbackTracerFactory; // equivalent to this.start()
+  }
+
+  // Begin using the user provided tracer factory. Stop always falling back to fallback tracer
+  // factory.
+  start(): void {
+    this._currentTracerFactory =
+      this._tracerFactory || this._fallbackTracerFactory;
+  }
+
+  // Stop the delegate from using the provided tracer factory. Begin to use the fallback factory
+  stop(): void {
+    this._currentTracerFactory = this._fallbackTracerFactory;
+  }
+
+  // -- TracerFactory interface implementation below -- //
+  getTracer(name?: string, version?: string): types.Tracer {
+    return this._currentTracerFactory.getTracer.apply(
+      this._currentTracerFactory,
+      // tslint:disable-next-line:no-any
+      arguments as any
+    );
+  }
+}

packages/opentelemetry-core/src/trace/globaltracer-utils.ts

@@ -15,21 +15,28 @@
  */
 
 import * as types from '@opentelemetry/types';
-import { TracerDelegate } from './TracerDelegate';
+import { TracerFactoryDelegate } from './TracerFactoryDelegate';
 
-let globalTracerDelegate = new TracerDelegate();
+let globalTracerFactoryDelegate = new TracerFactoryDelegate();
 
 /**
  * Set the current global tracer. Returns the initialized global tracer
  */
-export function initGlobalTracer(tracer: types.Tracer): types.Tracer {
-  return (globalTracerDelegate = new TracerDelegate(tracer));
+export function initGlobalTracerFactory(
+  tracerFactory: types.TracerFactory
+): types.TracerFactory {
+  return (globalTracerFactoryDelegate = new TracerFactoryDelegate(
+    tracerFactory
+  ));
+}
+
+export function getTracerFactory(): types.TracerFactory {
+  return globalTracerFactoryDelegate;
 }
 
 /**
- * Returns the global tracer
+ * Finds or creates tracer from the global TracerFactory
  */
-export function getTracer(): types.Tracer {
-  // Return the global tracer delegate
-  return globalTracerDelegate;
+export function getTracer(name?: string, version?: string): types.Tracer {
+  return globalTracerFactoryDelegate.getTracer(name, version);
 }

packages/opentelemetry-core/test/trace/NoopTracerFactory.test.ts

@@ -0,0 +1,27 @@
+/*!
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as assert from 'assert';
+import { NoopTracerFactory } from '../../src/trace/NoopTracerFactory';
+import { NOOP_SPAN } from '../../src/trace/NoopSpan';
+
+describe('NoopTracerFactory', () => {
+  it('should return a NOOP_SPAN', () => {
+    const factory = new NoopTracerFactory();
+    const span = factory.getTracer().startSpan('my-span');
+    assert.deepStrictEqual(span, NOOP_SPAN);
+  });
+});