@azure/core-tracing 1.0.0-preview.10 → 1.0.0-preview.14

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Release History
 
+## 1.0.0-preview.14 (2022-02-03)
+
+### Breaking Changes
+
+- @azure/core-tracing has been rewritten in order to provide cleaner abstractions for client libraries as well as remove @opentelemetry/api as a direct dependency.
+  - @opentelemetry/api is no longer a direct dependency of @azure/core-tracing providing for smaller bundle sizes and lower incidence of version conflicts
+  - `createSpanFunction` has been removed and replaced with a stateful `TracingClient` which can be created using the `createTracingClient` function.
+  - `TracingClient` introduces a new API for creating tracing spans. Use `TracingClient#withSpan` to wrap an invocation in a span, ensuring the span is ended and exceptions are captured.
+  - `TracingClient` also provides the lower-level APIs necessary to start a span without making it active, create request headers, serialize `traceparent` header, and wrapping a callback with an active context.
+
+### Other Changes
+
+- Updates package to work with the react native bundler. [PR #17783](https://github.com/Azure/azure-sdk-for-js/pull/17783)
+
+## 1.0.0-preview.13 (2021-07-15)
+
+### Features Added
+
+- Added support for disabling distributed tracing using the AZURE_TRACING_DISABLED environment variable.
+
+### Breaking Changes
+
+- Removed `TestTracer` and `TestSpan` from public API and into `@azure/test-utils`. [PR #16315](https://github.com/Azure/azure-sdk-for-js/pull/16315)
+  - `TestTracer` and `TestSpan` are intended for test support when used by other Azure packages and not intended for use by end users.
+- Removed `setTracer`, @azure/core-tracing will now rely on the `trace` API to fetch a tracer from the global tracer provider. [PR #16347](https://github.com/Azure/azure-sdk-for-js/pull/16347)
+  - If you are using `setTracer`, please use `trace.setGlobalTracerProvider(provider)` instead as described in the OpenTelemetry documentation.
+- Removed `NoOpTracer` and `NoOpSpan` from the public API. Please use `trace.wrapSpanContext(INVALID_SPAN_CONTEXT)` from `@opentelemetry/api` instead. [PR #16315](https://github.com/Azure/azure-sdk-for-js/pull/16315)
+
+## 1.0.0-preview.12 (2021-06-30)
+
+- Update `@opentelemetry/api` to version 1.0.0 [PR #15883](https://github.com/Azure/azure-sdk-for-js/pull/15883)
+  - This version ships with ESM modules and fixes an issue where Angular projects would warn ab out optimization bailouts due to dependencies on CommonJS or AMD.
+
+### Breaking Changes
+
+- Removed `OpenCensusSpanWrapper` and `OpenCensusTracerWrapper` from the public API. Customers using these wrappers should migrate to using `OpenTelemetry` directly. [PR #15770](https://github.com/Azure/azure-sdk-for-js/pull/15770)
+- Update `@azure/core-tracing` to version 1.0.0-preview.12. This brings core-tracing up to date with `@opentelemetry/api@1.0.0`.
+  - `Span#context` was renamed to `Span#spanContext`. This change is supported in `@azure/core-http@1.2.7`.
+
+## 1.0.0-preview.11 (2021-03-30)
+
+### Breaking Changes
+
+- Update @azure/core-tracing to version 1.0.0-preview.11. This brings core-tracing up to date with @opentelemetry/api@1.0.0-rc.0.
+  There are two scenarios that will require changes if you are using tracing:
+  - Previously, you would pass a parent span using the `OperationOptions.tracingOptions.spanOptions.parentSpan` property. This has been
+    changed so that you now specify a parent `Context` using the `OperationOptions.tracingOptions.tracingContext` property instead.
+  - The status code for Spans is no longer of type `CanonicalCode`. Instead, it's now `SpanStatusCode`, which also has a smaller range of values.
+
 ## 1.0.0-preview.10 (2021-03-04)
 
 - Internal improvements to make future opentelemetry updates simpler.

package/README.md

@@ -14,77 +14,93 @@ npm install @azure/core-tracing
 
 ## Key Concepts
 
-The `@azure/core-tracing` package supports enabling tracing for Azure SDK packages, using an [OpenTelemetry](https://opentelemetry.io/) `Tracer`. If you are using [OpenCensus](https://opencensus.io/) instead, we provide an `OpenCensusTracerWrapper` that allows you to convert an OpenCensus `Tracer` into an OpenTelemetry `Tracer`.
+The `@azure/core-tracing` package supports enabling tracing for Azure SDK packages, using an [OpenTelemetry](https://opentelemetry.io/) `Tracer`.
 
-By default, all libraries log with a `NoOpTracer` that takes no action.
-To change this, you have to use `setTracer` to set a new default `Tracer`.
+By default, all libraries log with a `NoOpTracer` that takes no action. To enable tracing, you will need to set a global tracer provider following the instructions in the [OpenTelemetry getting started guide](https://opentelemetry.io/docs/js/getting_started/nodejs) or the [Enabling Tracing using OpenTelemetry example](#enabling-tracing-using-opentelemetry) below.
 
-## Examples
+### Span Propagation
 
-### Example 1 - Setting an OpenTelemetry Tracer
+Core Tracing supports both automatic and manual span propagation. Automatic propagation is handled using OpenTelemetry's API and will work well in most scenarios when run in `Node.js`.
 
-```js
-const opentelemetry = require("@opentelemetry/core");
-const { BasicTracer, SimpleSpanProcessor } = require("@opentelemetry/tracing");
-const { ZipkinExporter } = require("@opentelemetry/exporter-zipkin");
-const { setTracer } = require("@azure/core-tracing");
+For customers who require manual propagation, or to provide context propagation in the browser, all client library operations accept an optional options collection where a tracingContext can be passed in and used as the currently active context. Please see the [Manual Span Propagation example](#manual-span-propagation-using-opentelemetry) below for more details.
 
-const exporter = new ZipkinExporter({
-  serviceName: "azure-tracing-sample"
-});
-const tracer = new BasicTracer();
-tracer.addSpanProcessor(new SimpleSpanProcessor(exporter));
+### OpenTelemetry Compatibility
 
-opentelemetry.initGlobalTracer(tracer);
+Most Azure SDKs and Microsoft's [Application Insights](https://www.npmjs.com/package/applicationinsights) use [OpenTelemetry](https://opentelemetry.io/) to support tracing. Specifically, we depend on the [@opentelemetry/api](https://www.npmjs.com/package/@opentelemetry/api) npm package.
 
-const rootSpan = opentelemetry.getTracer().startSpan("root");
+As OpenTelemetry iterated on their API towards their 1.0 GA release, our libraries were updated to match.
 
-// Call some client library methods and pass rootSpan via tracingOptions.
+Some incompatibility between the libraries is due to mismatches between the OpenTelemetry versions used in either `@azure/core-tracing` or `applicationinsights` when the two are used side-by-side. For folks who are using both an Azure Client Library (and transitively, `@azure/core-tracing`) and Application Insights in the same application, we recommend using the same version of OpenTelemetry for both libraries by upgrading to their latest versions.
 
-rootSpan.end();
-exporter.shutdown();
-```
+> Please note that we do not foresee any future compatibility concerns now that OpenTelemetry 1.0.0 has been released and the API considered stable.
 
-### Example 2 - Setting an OpenCensus Tracer
-
-```js
-const tracing = require("@opencensus/nodejs");
-const { ZipkinTraceExporter } = require("@opencensus/exporter-zipkin");
-const {
-  setTracer,
-  OpenCensusTracerWrapper,
-  OpenCensusSpanWrapper
-} = require("@azure/core-tracing");
-
-const tracer = tracing.start({ samplingRate: 1 }).tracer;
-
-tracer.registerSpanEventListener(
-  new ZipkinTraceExporter({
-    serviceName: "azure-tracing-sample",
-    bufferTimeout: 2
-  })
-);
-setTracer(new OpenCensusTracerWrapper(tracer));
-tracer.startRootSpan({ name: "root" }, async (rootSpanEx) => {
-  const rootSpan = new OpenCensusSpanWrapper(rootSpanEx);
-  // Call some client library methods and pass rootSpan via tracingOptions.
-  rootSpanEx.end(); // rootSpan.end() should work as well
-});
+#### Compatibility Matrix
+
+| Core Tracing     | Application Insights | @opentelemetry/api |
+| ---------------- | -------------------- | ------------------ |
+| 1.0.0-preview.10 |                      | 0.10.2             |
+| 1.0.0-preview.11 | 2.1.0-2.1.3          | 1.0.0-rc.0         |
+| 1.0.0-preview.12 | ^2.1.4               | ^1.0.0             |
+| 1.0.0-preview.13 | ^2.1.4               | ^1.0.0             |
+
+Please see the [troubleshooting](#troubleshooting) section for additional information about handling compatibility errors.
+
+## Examples
+
+### Enabling tracing using OpenTelemetry
+
+```ts
+const opentelemetry = require("@opentelemetry/api");
+const { SimpleSpanProcessor, ConsoleSpanExporter } = require("@opentelemetry/tracing");
+
+const provider = new NodeTracerProvider();
+provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+provider.register();
+
+// Call some client library methods using automatic span propagation.
 ```
 
-### Example 3 - Passing parent Spans to library operations
+### Manual Span Propagation using OpenTelemetry
 
-```js
-// Given a BlobClient from @azure/storage-blob
-const result = await blobClient.download(undefined, undefined, {
+```ts
+const opentelemetry = require("@opentelemetry/api");
+// Get a tracer from a registered provider, create a span, and get the current context
+const tracer = opentelemetry.trace.getTracer("my-tracer");
+const span = tracer.startSpan("main");
+const ctx = opentelemetry.trace.setSpan(opentelemetry.context.active(), span);
+
+// Assuming we have an existing BlobClient, let's see if the blob exists.
+// The context is passed to the client library as a tracingContext option and will be propagated downstream to any child spans.
+const result = await blobClient.exists({
   tracingOptions: {
-    spanOptions: { parent: rootSpan }
+    tracingContext: ctx
   }
 });
 ```
 
+## Next steps
+
+You can build and run the tests locally by executing `rushx test`. Explore the `test` folder to see advanced usage and behavior of the public classes.
+
+## Troubleshooting
+
+If you run into issues while using this library, please feel free to [file an issue](https://github.com/Azure/azure-sdk-for-js/issues/new).
+
+### OpenTelemetry Compatibility Errors
+
+Errors such as `span.spanContext is not a function` or `span.context is not a function` are likely due to a mismatch of OpenTelemetry versions between two libraries.
+
+To resolve this, please ensure that all Azure client libraries are using a compatible version of OpenTelemetry as per the [compatibility matrix](#compatibility-matrix). If you are using `applicationinsights` please ensure that you are using the same version of OpenTelemetry as the Azure client libraries.
+
+> Ideally you'd want to use OpenTelemetry 1.0.0 or higher.
+
+- If you are using `npm` you may run `npm ls @opentelemetry/api` to see the version of OpenTelemetry you are using and which client libraries are using it.
+- For `yarn` users, `yarn why @opentelemetry/api` will show you the version of OpenTelemetry you are using and which client libraries are using it.
+
+You may then upgrade client libraries as needed to ensure compatibility. Things should work as expected when the above command returns a version of OpenTelemetry that is >= 1.0.0.
+
 ## Contributing
 
-If you'd like to contribute to this library, please read the [contributing guide](https://github.com/Azure/azure-sdk-for-js/blob/master/CONTRIBUTING.md) to learn more about how to build and test the code.
+If you'd like to contribute to this library, please read the [contributing guide](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) to learn more about how to build and test the code.
 
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fsdk%2Fcore%2Fcore-tracing%2FREADME.png)