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

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# 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)
+
+## 1.0.0-preview.8 (2020-04-28)
+
+- Update `TestSpan` to allow setting span attributes [PR link](https://github.com/Azure/azure-sdk-for-js/pull/6565).
+- [BREAKING] Migrate to OpenTelemetry 0.6 using the new `@opentelemetry/api` package. There were a few breaking changes:
+  - `SpanContext` now requires traceFlags to be set.
+  - `Tracer` has removed `recordSpanData`, `getBinaryFormat`, and `getHttpTextFormat`.
+  - `Tracer.getCurrentSpan` returns `undefined` instead of `null` when unset.
+  - `Link` objects renamed `spanContext` property to `context`.
+
+## 1.0.0-preview.7 (2019-12-03)
+
+- Updated the behavior of how incompatible versions of OpenTelemetry Tracer are handled. Now, errors will be thrown only if the user has manually set a Tracer. This means that incompatible versions will be silently ignored when tracing is not enabled.
+- Updated to use OpenTelemetry 0.2 via the `@opentelemetry/types` package. There were two breaking changes in this update:
+  - `isRecordingEvents` on `Span` was renamed to `isRecording`. [PR link](https://github.com/open-telemetry/opentelemetry-js/pull/454)
+  - `addLink` was removed from `Span` as links are now only allowed to be added during span creation. This is possible by specifying any necessary links inside `SpanOptions`. [PR link](https://github.com/open-telemetry/opentelemetry-js/pull/449)
+
+## 1.0.0-preview.5 (2019-10-22)
+
+- Fixes issue where loading multiple copies of this module could result in the tracer set by `setTracer()` being reset.
+
+## 1.0.0-preview.4 (2019-10-08)
+
+- Remove dependency on the `debug` module to ensure compatibility with IE11
+
+## 1.0.0-preview.3 (2019-10-07)
+
+- Updated to use the latest types from OpenTelemetry (PR [#5182](https://github.com/Azure/azure-sdk-for-js/pull/5182))
+- Clean up and refactored code for easier usage and testability. (PR [#5233](https://github.com/Azure/azure-sdk-for-js/pull/5233) and PR [#5283](https://github.com/Azure/azure-sdk-for-js/pull/5283))
+
+## 1.0.0-preview.2 (2019-09-09)
+
+Updated the `OpenCensusSpanPlugin` & the `NoOpSpanPlugin` to support for retrieving span context. This allows updating of request headers with the right [span context](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format). (PR [#4712](https://github.com/Azure/azure-sdk-for-js/pull/4712))
+
+## 1.0.0-preview.1 (2019-08-05)
+
+Provides low-level interfaces and helper methods for tracing in Azure SDK

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,4 @@
-# Azure Core tracing library for JS
+# Azure Core tracing library for JavaScript
 
 This is the core tracing library that provides low-level interfaces and helper methods for tracing in Azure SDK JavaScript libraries which work in the browser and Node.js.
 
@@ -6,98 +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.
 
-## Contributing
+## Next steps
 
-This project welcomes contributions and suggestions. Most contributions require you to agree to a
-Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.microsoft.com.
+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.
 
-When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
-a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
-provided by the bot. You will only need to do this once across all repos using our CLA.
+## Troubleshooting
 
-If you'd like to contribute to this library, please read the [contributing guide](https://github.com/Azure/azure-sdk-for-js/tree/48cdcfb307b4754c1cac269ef2867c70206492af/CONTRIBUTING.md) to learn more about how to build and test the code.
+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
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
-contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+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)