@azure/core-tracing 1.0.0-preview.9 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Release History
 
+## 1.0.0 (2022-03-31)
+
+This release marks the GA release of our @azure/core-tracing libraries and is unchanged from preview.14
+
+## 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.
+
 ## 1.0.0-preview.9 (2020-08-04)
 
 - Update `@opentelemetry/api` to version 0.10.2 [PR 10393](https://github.com/Azure/azure-sdk-for-js/pull/10393)

package/README.md

@@ -6,85 +6,32 @@ This is the core tracing library that provides low-level interfaces and helper m
 
 ### Installation
 
-Install this library using npm as follows
-
-```
-npm install @azure/core-tracing
-```
+This package is primarily used in Azure client libraries and not meant to be used directly by consumers of Azure SDKs.
 
 ## 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`.
-
-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`.
+- `TracingClient` is the primary interface providing tracing functionality to client libraries. Client libraries should only be aware of and interact with a `TracingClient` instance.
+  - A `TracingClient` implementation can be created using the `createTracingClient` factory function.
+- `Instrumenter` provides an abstraction over an instrumentation and acts as the interop point for using third party libraries like OpenTelemetry. By default, a no-op `Instrumenter` is used. Customers who wish to enable `OpenTelemetry` based tracing will do so by installing and registering the [@azure/opentelemetry-instrumentation-azure-sdk] package.
+- `TracingContext` is an **immutable** data container, used to pass operation-specific information around (such as span parenting information).
+- `TracingSpan` is an abstraction of a `Span` which can be used to record events, attributes, and exceptions.
 
 ## Examples
 
-### Example 1 - Setting an OpenTelemetry Tracer
-
-```js
-const opentelemetry = require("@opentelemetry/core");
-const { BasicTracer, SimpleSpanProcessor } = require("@opentelemetry/tracing");
-const { ZipkinExporter } = require("@opentelemetry/exporter-zipkin");
-const { setTracer } = require("@azure/core-tracing");
-
-const exporter = new ZipkinExporter({
-  serviceName: "azure-tracing-sample"
-});
-const tracer = new BasicTracer();
-tracer.addSpanProcessor(new SimpleSpanProcessor(exporter));
-
-opentelemetry.initGlobalTracer(tracer);
-
-const rootSpan = opentelemetry.getTracer().startSpan("root");
-
-// Call some client library methods and pass rootSpan via tracingOptions.
-
-rootSpan.end();
-exporter.shutdown();
-```
-
-### 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
-});
-```
-
-### Example 3 - Passing parent Spans to library operations
-
-```js
-// Given a BlobClient from @azure/storage-blob
-const result = await blobClient.download(undefined, undefined, {
-  tracingOptions: {
-    spanOptions: { parent: rootSpan }
-  }
-});
-```
+Examples can be found in the `samples` folder.
+
+## 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).
 
 ## 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.
+
+[@azure/opentelemetry-instrumentation-azure-sdk]: https://www.npmjs.com/package/@azure/opentelemetry-instrumentation-azure-sdk
 
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fsdk%2Fcore%2Fcore-tracing%2FREADME.png)