chore: remove tracer apis not part of spec (#1764)

Co-authored-by: Mayur Kale <[email protected]>
Co-authored-by: Daniel Dyla <[email protected]>

README.md

@@ -225,6 +225,16 @@ To request automatic tracing support for a module not on this list, please [file
 |----------------------------------------------------------|-----------------------------------------------------------------------------------------|
 | [@opentelemetry/shim-opentracing][otel-shim-opentracing] | OpenTracing shim allows existing OpenTracing instrumentation to report to OpenTelemetry |
 
+## Upgrade guidelines
+
+### 0.14.0 to 0.15.0
+
+[PR-1764](https://github.com/open-telemetry/opentelemetry-js/pull/1764) removed some APIs from `Tracer`:
+
+- `Tracer.getCurrentSpan()`: use `api.getSpan(api.context.active())`
+- `Tracer.withSpan(span)`: use `api.context.with(api.setSpan(api.context.active(), span))`
+- `Tracer.bind(target)`: use `api.context.bind(target)`
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

examples/basic-tracer-node/index.js

@@ -37,9 +37,8 @@ exporter.shutdown();
 function doWork(parent) {
   // Start another span. In this example, the main method already started a
   // span, so that'll be the parent span, and this will be a child span.
-  const span = tracer.startSpan('doWork', {
-    parent,
-  });
+  const ctx = opentelemetry.setSpan(opentelemetry.context.active(), parent);
+  const span = tracer.startSpan('doWork', undefined, ctx);
 
   // simulate some random work.
   for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {

examples/collector-exporter-node/tracing.js

@@ -39,9 +39,8 @@ setTimeout(() => {
 function doWork(parent) {
   // Start another span. In this example, the main method already started a
   // span, so that'll be the parent span, and this will be a child span.
-  const span = tracer.startSpan('doWork', {
-    parent,
-  });
+  const ctx = opentelemetry.setSpan(opentelemetry.context.active(), parent);
+  const span = tracer.startSpan('doWork', undefined, ctx);
 
   // simulate some random work.
   for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {

examples/grpc-js/client.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const api = require('@opentelemetry/api');
 const tracer = require('./tracer')('example-grpc-client');
 // eslint-disable-next-line import/order
 const grpc = require('@grpc/grpc-js');
@@ -14,7 +15,7 @@ function main() {
   // the span, which is created to track work that happens outside of the
   // request lifecycle entirely.
   const span = tracer.startSpan('client.js:main()');
-  tracer.withSpan(span, () => {
+  api.context.with(api.setSpan(api.context.active(), span), () => {
     console.log('Client traceId ', span.context().traceId);
     const client = new services.GreeterClient(
       `localhost:${PORT}`,

examples/grpc-js/server.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const api = require('@opentelemetry/api');
 const tracer = require('./tracer')(('example-grpc-server'));
 // eslint-disable-next-line import/order
 const grpc = require('@grpc/grpc-js');
@@ -21,11 +22,10 @@ function startServer() {
 }
 
 function sayHello(call, callback) {
-  const currentSpan = tracer.getCurrentSpan();
+  const currentSpan = api.getSpan(api.context.active());
   // display traceid in the terminal
   console.log(`traceid: ${currentSpan.context().traceId}`);
   const span = tracer.startSpan('server.js:sayHello()', {
-    parent: currentSpan,
     kind: 1, // server
     attributes: { key: 'value' },
   });

examples/grpc/client.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const api = require('@opentelemetry/api');
 const tracer = require('./tracer')('example-grpc-client');
 // eslint-disable-next-line import/order
 const grpc = require('grpc');
@@ -14,7 +15,7 @@ function main() {
   // the span, which is created to track work that happens outside of the
   // request lifecycle entirely.
   const span = tracer.startSpan('client.js:main()');
-  tracer.withSpan(span, () => {
+  api.context.with(api.setSpan(api.context.active(), span), () => {
     console.log('Client traceId ', span.context().traceId);
     const client = new services.GreeterClient(
       `localhost:${PORT}`,

examples/grpc/server.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const api = require('@opentelemetry/api');
 const tracer = require('./tracer')(('example-grpc-server'));
 // eslint-disable-next-line import/order
 const grpc = require('grpc');
@@ -20,7 +21,7 @@ function startServer() {
 }
 
 function sayHello(call, callback) {
-  const currentSpan = tracer.getCurrentSpan();
+  const currentSpan = api.getSpan(api.context.active());
   // display traceid in the terminal
   console.log(`traceid: ${currentSpan.context().traceId}`);
   const span = tracer.startSpan('server.js:sayHello()', {

examples/http/client.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const api = require('@opentelemetry/api');
 const tracer = require('./tracer')('example-http-client');
 // eslint-disable-next-line import/order
 const http = require('http');
@@ -10,7 +11,7 @@ function makeRequest() {
   // the span, which is created to track work that happens outside of the
   // request lifecycle entirely.
   const span = tracer.startSpan('makeRequest');
-  tracer.withSpan(span, () => {
+  api.context.with(api.setSpan(api.context.active(), span), () => {
     http.get({
       host: 'localhost',
       port: 8080,

examples/http/server.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const api = require('@opentelemetry/api');
 const tracer = require('./tracer')('example-http-server');
 // eslint-disable-next-line import/order
 const http = require('http');
@@ -19,11 +20,10 @@ function startServer(port) {
 
 /** A function which handles requests and send response. */
 function handleRequest(request, response) {
-  const currentSpan = tracer.getCurrentSpan();
+  const currentSpan = api.getSpan(api.context.active());
   // display traceid in the terminal
   console.log(`traceid: ${currentSpan.context().traceId}`);
   const span = tracer.startSpan('handleRequest', {
-    parent: currentSpan,
     kind: 1, // server
     attributes: { key: 'value' },
   });

examples/https/client.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const api = require('@opentelemetry/api');
 const tracer = require('./tracer')('example-https-client');
 // eslint-disable-next-line import/order
 const https = require('https');
@@ -10,7 +11,7 @@ function makeRequest() {
   // the span, which is created to track work that happens outside of the
   // request lifecycle entirely.
   const span = tracer.startSpan('makeRequest');
-  tracer.withSpan(span, () => {
+  api.context.with(api.setSpan(api.context.active(), span), () => {
     https.get({
       host: 'localhost',
       port: 443,

examples/https/server.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const api = require('@opentelemetry/api');
 // eslint-disable-next-line import/order
 const tracer = require('./tracer')('example-https-server');
 const fs = require('fs');
@@ -24,11 +25,10 @@ function startServer(port) {
 
 /** A function which handles requests and send response. */
 function handleRequest(request, response) {
-  const currentSpan = tracer.getCurrentSpan();
+  const currentSpan = api.getSpan(api.context.active());
   // display traceid in the terminal
   console.log(`traceid: ${currentSpan.context().traceId}`);
   const span = tracer.startSpan('handleRequest', {
-    parent: currentSpan,
     kind: 1, // server
     attributes: { key: 'value' },
   });

examples/tracer-web/examples/document-load/index.js

@@ -1,3 +1,4 @@
+import { context, getSpan, setSpan } from '@opentelemetry/api';
 import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/tracing';
 import { WebTracerProvider } from '@opentelemetry/web';
 import { DocumentLoad } from '@opentelemetry/plugin-document-load';
@@ -52,31 +53,29 @@ const prepareClickEvent = () => {
     }
 
     const mainSpan = tracer.startSpan('click button');
-    tracer.withSpan(mainSpan, () => {
-      const span1 = tracer.startSpan('files-series-info-1', {
-        parent: tracer.getCurrentSpan(),
-      });
+    context.with(setSpan(context.active(), mainSpan), () => {
+      const span1 = tracer.startSpan('files-series-info-1');
 
-      const span2 = tracer.startSpan('files-series-info-2', {
-        parent: tracer.getCurrentSpan(),
-      });
+      const span2 = tracer.startSpan('files-series-info-2');
 
-      tracer.withSpan(span1, () => {
+      context.with(setSpan(context.active(), span1), () => {
         getData(url1).then((data) => {
-          console.log('current span is span1', tracer.getCurrentSpan() === span1);
+          const curSpan = getSpan(context.active());
+          console.log('current span is span1', curSpan === span1);
           console.log('info from package.json', data.description, data.version);
-          tracer.getCurrentSpan().addEvent('fetching-span1-completed');
+          curSpan.addEvent('fetching-span1-completed');
           span1.end();
           finish();
         });
       });
 
-      tracer.withSpan(span2, () => {
+      context.with(setSpan(context.active(), span2), () => {
         getData(url2).then((data) => {
           setTimeout(() => {
-            console.log('current span is span2', tracer.getCurrentSpan() === span2);
+            const curSpan = getSpan(context.active());
+            console.log('current span is span2', curSpan === span2);
             console.log('info from package.json', data.description, data.version);
-            tracer.getCurrentSpan().addEvent('fetching-span2-completed');
+            curSpan.addEvent('fetching-span2-completed');
             span2.end();
             finish();
           }, 100);

examples/tracer-web/examples/fetch/index.js

@@ -1,5 +1,6 @@
 'use strict';
 
+import { context, getSpan, setSpan } from '@opentelemetry/api';
 import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/tracing';
 import { CollectorTraceExporter } from '@opentelemetry/exporter-collector';
 import { WebTracerProvider } from '@opentelemetry/web';
@@ -44,22 +45,18 @@ const prepareClickEvent = () => {
   const element = document.getElementById('button1');
 
   const onClick = () => {
-    const singleSpan = webTracerWithZone.startSpan(`files-series-info`, {
-      parent: webTracerWithZone.getCurrentSpan(),
-    });
-    webTracerWithZone.withSpan(singleSpan, () => {
+    const singleSpan = webTracerWithZone.startSpan(`files-series-info`);
+    context.with(setSpan(context.active(), singleSpan), () => {
       getData(url).then((_data) => {
-        webTracerWithZone.getCurrentSpan().addEvent('fetching-single-span-completed');
+        getSpan(context.active()).addEvent('fetching-single-span-completed');
         singleSpan.end();
       });
     });
     for (let i = 0, j = 5; i < j; i += 1) {
-      const span = webTracerWithZone.startSpan(`files-series-info-${i}`, {
-        parent: webTracerWithZone.getCurrentSpan(),
-      });
-      webTracerWithZone.withSpan(span, () => {
+      const span = webTracerWithZone.startSpan(`files-series-info-${i}`);
+      context.with(setSpan(context.active(), span), () => {
         getData(url).then((_data) => {
-          webTracerWithZone.getCurrentSpan().addEvent(`fetching-span-${i}-completed`);
+          getSpan(context.active()).addEvent(`fetching-span-${i}-completed`);
           span.end();
         });
       });

examples/tracer-web/examples/xml-http-request/index.js

@@ -1,3 +1,4 @@
+import { context, getSpan, setSpan } from '@opentelemetry/api';
 import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/tracing';
 import { WebTracerProvider } from '@opentelemetry/web';
 import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';
@@ -49,15 +50,13 @@ const prepareClickEvent = () => {
 
   const onClick = () => {
     for (let i = 0, j = 5; i < j; i += 1) {
-      const span1 = webTracerWithZone.startSpan(`files-series-info-${i}`, {
-        parent: webTracerWithZone.getCurrentSpan(),
-      });
-      webTracerWithZone.withSpan(span1, () => {
+      const span1 = webTracerWithZone.startSpan(`files-series-info-${i}`);
+      context.with(setSpan(context.active(), span1), () => {
         getData(url1).then((_data) => {
-          webTracerWithZone.getCurrentSpan().addEvent('fetching-span1-completed');
+          getSpan(context.active()).addEvent('fetching-span1-completed');
           span1.end();
         }, ()=> {
-          webTracerWithZone.getCurrentSpan().addEvent('fetching-error');
+          getSpan(context.active()).addEvent('fetching-error');
           span1.end();
         });
       });

integration-tests/propagation-validation-server/validation-server.js

@@ -1,7 +1,7 @@
 const axios = require("axios");
 const { HttpTraceContext } = require("@opentelemetry/core");
 const { BasicTracerProvider } = require("@opentelemetry/tracing");
-const { context, propagation, trace, ROOT_CONTEXT } = require("@opentelemetry/api");
+const { context, propagation, setSpan, trace, ROOT_CONTEXT } = require("@opentelemetry/api");
 const {
   AsyncHooksContextManager,
 } = require("@opentelemetry/context-async-hooks");
@@ -36,7 +36,7 @@ app.post("/verify-tracecontext", (req, res) => {
       req.body.map((action) => {
         const span = tracer.startSpan("propagate-w3c");
         let promise;
-        tracer.withSpan(span, () => {
+        context.with(setSpan(context.active(), span), () => {
           const headers = {};
           propagation.inject(context.active(), headers);
           promise = axios

packages/opentelemetry-api/README.md

@@ -160,7 +160,7 @@ const api = require("@opentelemetry/api");
 const tracer = api.trace.getTracer("my-library-name", "0.2.3");
 
 async function doSomething() {
-  const span = tracer.startSpan("doSomething", { parent: tracer.getCurrentSpan() });
+  const span = tracer.startSpan("doSomething");
   try {
     const result = await doSomethingElse();
     span.end();

packages/opentelemetry-api/src/api/global-utils.ts

@@ -65,4 +65,4 @@ export function makeGetter<T>(
  * version. If the global API is not compatible with the API package
  * attempting to get it, a NOOP API implementation will be returned.
  */
-export const API_BACKWARDS_COMPATIBILITY_VERSION = 2;
+export const API_BACKWARDS_COMPATIBILITY_VERSION = 3;

packages/opentelemetry-api/src/trace/NoopTracer.ts

@@ -24,10 +24,6 @@ import { getSpanContext } from '../context/context';
  * No-op implementations of {@link Tracer}.
  */
 export class NoopTracer implements Tracer {
-  getCurrentSpan(): Span {
-    return NOOP_SPAN;
-  }
-
   // startSpan starts a noop span.
   startSpan(name: string, options?: SpanOptions, context?: Context): Span {
     const root = Boolean(options?.root);
@@ -46,17 +42,6 @@ export class NoopTracer implements Tracer {
       return NOOP_SPAN;
     }
   }
-
-  withSpan<T extends (...args: unknown[]) => ReturnType<T>>(
-    span: Span,
-    fn: T
-  ): ReturnType<T> {
-    return fn();
-  }
-
-  bind<T>(target: T, _span?: Span): T {
-    return target;
-  }
 }
 
 function isSpanContext(spanContext: any): spanContext is SpanContext {

packages/opentelemetry-api/src/trace/ProxyTracer.ts

@@ -31,25 +31,10 @@ export class ProxyTracer implements Tracer {
     public readonly version?: string
   ) {}
 
-  getCurrentSpan(): Span | undefined {
-    return this._getTracer().getCurrentSpan();
-  }
-
   startSpan(name: string, options?: SpanOptions): Span {
     return this._getTracer().startSpan(name, options);
   }
 
-  withSpan<T extends (...args: unknown[]) => ReturnType<T>>(
-    span: Span,
-    fn: T
-  ): ReturnType<T> {
-    return this._getTracer().withSpan(span, fn);
-  }
-
-  bind<T>(target: T, span?: Span): T {
-    return this._getTracer().bind(target, span);
-  }
-
   /**
    * Try to get a tracer from the proxy tracer provider.
    * If the proxy tracer provider has no delegate, return a noop tracer.