[core] - Extract OpenTelemetry to a separate package

rush.json

@@ -606,6 +606,11 @@
       "projectFolder": "sdk/core/logger",
       "versionPolicyName": "core"
     },
+    {
+      "packageName": "@azure/opentelemetry-instrumentation-azure-sdk",
+      "projectFolder": "sdk/instrumentation/opentelemetry-instrumentation-azure-sdk",
+      "versionPolicyName": "client"
+    },
     {
       "packageName": "@azure/schema-registry",
       "projectFolder": "sdk/schemaregistry/schema-registry",
@@ -1247,4 +1252,4 @@
       "versionPolicyName": "management"
     }
   ]
-}
+}

sdk/core/core-auth/review/core-auth.api.md

@@ -34,13 +34,6 @@ export class AzureSASCredential implements SASCredential {
     update(newSignature: string): void;
 }
 
-// @public
-export interface Context {
-    deleteValue(key: symbol): Context;
-    getValue(key: symbol): unknown;
-    setValue(key: symbol, value: unknown): Context;
-}
-
 // @public
 export interface GetTokenOptions {
     abortSignal?: AbortSignalLike;
@@ -49,7 +42,7 @@ export interface GetTokenOptions {
     };
     tenantId?: string;
     tracingOptions?: {
-        tracingContext?: Context;
+        tracingContext?: TracingContext;
     };
 }
 
@@ -83,6 +76,12 @@ export interface TokenCredential {
     getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
 }
 
+// @public
+export interface TracingContext {
+    deleteValue(key: symbol): TracingContext;
+    getValue(key: symbol): unknown;
+    setValue(key: symbol, value: unknown): TracingContext;
+}
 
 // (No @packageDocumentation comment for this package)
 

sdk/core/core-auth/src/index.ts

@@ -16,4 +16,4 @@ export {
   isTokenCredential,
 } from "./tokenCredential";
 
-export { Context } from "./tracing";
+export { TracingContext } from "./tracing";

sdk/core/core-auth/src/tokenCredential.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT license.
 
 import { AbortSignalLike } from "@azure/abort-controller";
-import { Context } from "./tracing";
+import { TracingContext } from "./tracing";
 
 /**
  * Represents a credential capable of providing an authentication token.
@@ -43,9 +43,9 @@ export interface GetTokenOptions {
    */
   tracingOptions?: {
     /**
-     * OpenTelemetry context
+     * Tracing Context for the current request.
      */
-    tracingContext?: Context;
+    tracingContext?: TracingContext;
   };
 
   /**

sdk/core/core-auth/src/tracing.ts

@@ -7,7 +7,7 @@
 /**
  * An interface structurally compatible with OpenTelemetry.
  */
-export interface Context {
+export interface TracingContext {
   /**
    * Get a value from the context.
    *
@@ -21,12 +21,12 @@ export interface Context {
    * @param key - context key for which to set the value
    * @param value - value to set for the given key
    */
-  setValue(key: symbol, value: unknown): Context;
+  setValue(key: symbol, value: unknown): TracingContext;
   /**
    * Return a new context which inherits from this context but does
    * not contain a value for the given key.
    *
    * @param key - context key for which to clear a value
    */
-  deleteValue(key: symbol): Context;
+  deleteValue(key: symbol): TracingContext;
 }

sdk/core/core-tracing/CHANGELOG.md

@@ -6,8 +6,11 @@
 
 ### Breaking Changes
 
-- SpanOptions has been removed from OperationTracingOptions as it is internal and should not be exposed by client libraries.
-  - Customizing a newly created Span is only supported via passing `SpanOptions` to `createSpanFunction`
+- @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.
 
 ### Bugs Fixed
 

sdk/core/core-tracing/package.json

@@ -5,9 +5,7 @@
   "sdk-type": "client",
   "main": "dist/index.js",
   "module": "dist-esm/src/index.js",
-  "browser": {
-    "./dist-esm/src/utils/global.js": "./dist-esm/src/utils/global.browser.js"
-  },
+  "browser": {},
   "react-native": {
     "./dist/index.js": "./dist-esm/src/index.js"
   },
@@ -59,15 +57,13 @@
   "homepage": "https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/core/core-tracing/README.md",
   "sideEffects": false,
   "dependencies": {
-    "@opentelemetry/api": "^1.0.1",
     "tslib": "^2.2.0"
   },
   "devDependencies": {
     "@azure/core-auth": "^1.3.0",
     "@azure/dev-tool": "^1.0.0",
     "@azure/eslint-plugin-azure-sdk": "^3.0.0",
     "@microsoft/api-extractor": "^7.18.11",
-    "@opentelemetry/tracing": "^0.22.0",
     "@types/chai": "^4.1.6",
     "@types/mocha": "^7.0.2",
     "@types/node": "^12.0.0",

sdk/core/core-tracing/review/core-tracing.api.md

@@ -5,183 +5,106 @@
 ```ts
 
 // @public
-export interface Context {
-    deleteValue(key: symbol): Context;
-    getValue(key: symbol): unknown;
-    setValue(key: symbol, value: unknown): Context;
-}
-
-// @public
-const context_2: ContextAPI;
-export { context_2 as context }
-
-// @public
-export interface ContextAPI {
-    active(): Context;
-}
+export function createTracingClient(options: TracingClientOptions): TracingClient;
 
 // @public
-export function createSpanFunction(args: CreateSpanFunctionArgs): <T extends {
-    tracingOptions?: OperationTracingOptions | undefined;
-}>(operationName: string, operationOptions?: T | undefined, startSpanOptions?: SpanOptions | undefined) => {
-    span: Span;
-    updatedOptions: T;
-};
-
-// @public
-export interface CreateSpanFunctionArgs {
-    namespace: string;
-    packagePrefix: string;
+export interface Instrumenter {
+    createRequestHeaders(tracingContext?: TracingContext): Record<string, string>;
+    parseTraceparentHeader(traceparentHeader: string): TracingContext | undefined;
+    startSpan(name: string, spanOptions: InstrumenterSpanOptions): {
+        span: TracingSpan;
+        tracingContext: TracingContext;
+    };
+    withContext<CallbackArgs extends unknown[], Callback extends (...args: CallbackArgs) => ReturnType<Callback>>(context: TracingContext, callback: Callback, ...callbackArgs: CallbackArgs): ReturnType<Callback>;
 }
 
 // @public
-export type Exception = ExceptionWithCode | ExceptionWithMessage | ExceptionWithName | string;
-
-// @public
-export interface ExceptionWithCode {
-    code: string | number;
-    message?: string;
-    name?: string;
-    stack?: string;
-}
-
-// @public
-export interface ExceptionWithMessage {
-    code?: string | number;
-    message: string;
-    name?: string;
-    stack?: string;
-}
-
-// @public
-export interface ExceptionWithName {
-    code?: string | number;
-    message?: string;
-    name: string;
-    stack?: string;
-}
-
-// @public
-export function extractSpanContextFromTraceParentHeader(traceParentHeader: string): SpanContext | undefined;
-
-// @public
-export function getSpan(context: Context): Span | undefined;
-
-// @public
-export function getSpanContext(context: Context): SpanContext | undefined;
-
-// @public
-export function getTraceParentHeader(spanContext: SpanContext): string | undefined;
-
-// @public
-export function getTracer(): Tracer;
-
-// @public
-export function getTracer(name: string, version?: string): Tracer;
-
-// @public
-export type HrTime = [number, number];
-
-// @public
-export function isSpanContextValid(context: SpanContext): boolean;
-
-// @public
-export interface Link {
-    attributes?: SpanAttributes;
-    context: SpanContext;
+export interface InstrumenterSpanOptions extends TracingSpanOptions {
+    packageName: string;
+    packageVersion?: string;
+    tracingContext?: TracingContext;
 }
 
 // @public
 export interface OperationTracingOptions {
-    tracingContext?: Context;
+    tracingContext?: TracingContext;
 }
 
 // @public
-export function setSpan(context: Context, span: Span): Context;
+export type SpanStatus = SpanStatusSuccess | SpanStatusError;
 
 // @public
-export function setSpanContext(context: Context, spanContext: SpanContext): Context;
-
-// @public
-export interface Span {
-    addEvent(name: string, attributesOrStartTime?: SpanAttributes | TimeInput, startTime?: TimeInput): this;
-    end(endTime?: TimeInput): void;
-    isRecording(): boolean;
-    recordException(exception: Exception, time?: TimeInput): void;
-    setAttribute(key: string, value: SpanAttributeValue): this;
-    setAttributes(attributes: SpanAttributes): this;
-    setStatus(status: SpanStatus): this;
-    spanContext(): SpanContext;
-    updateName(name: string): this;
-}
-
-// @public
-export interface SpanAttributes {
-    [attributeKey: string]: SpanAttributeValue | undefined;
-}
-
-// @public
-export type SpanAttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
+export type SpanStatusError = {
+    status: "error";
+    error?: Error | string;
+};
 
 // @public
-export interface SpanContext {
-    spanId: string;
-    traceFlags: number;
-    traceId: string;
-    traceState?: TraceState;
-}
+export type SpanStatusSuccess = {
+    status: "success";
+};
 
 // @public
-export enum SpanKind {
-    CLIENT = 2,
-    CONSUMER = 4,
-    INTERNAL = 0,
-    PRODUCER = 3,
-    SERVER = 1
+export interface TracingClient {
+    createRequestHeaders(tracingContext?: TracingContext): Record<string, string>;
+    parseTraceparentHeader(traceparentHeader: string): TracingContext | undefined;
+    startSpan<Options extends {
+        tracingOptions?: OperationTracingOptions;
+    }>(name: string, operationOptions?: Options, spanOptions?: TracingSpanOptions): {
+        span: TracingSpan;
+        updatedOptions: Options;
+    };
+    withContext<CallbackArgs extends unknown[], Callback extends (...args: CallbackArgs) => ReturnType<Callback>>(context: TracingContext, callback: Callback, ...callbackArgs: CallbackArgs): ReturnType<Callback>;
+    withSpan<Options extends {
+        tracingOptions?: OperationTracingOptions;
+    }, Callback extends (updatedOptions: Options, span: Omit<TracingSpan, "end">) => ReturnType<Callback>>(name: string, operationOptions: Options, callback: Callback, spanOptions?: TracingSpanOptions): Promise<ReturnType<Callback>>;
 }
 
 // @public
-export interface SpanOptions {
-    attributes?: SpanAttributes;
-    kind?: SpanKind;
-    links?: Link[];
-    startTime?: TimeInput;
+export interface TracingClientOptions {
+    namespace: string;
+    packageName: string;
+    packageVersion?: string;
 }
 
 // @public
-export interface SpanStatus {
-    code: SpanStatusCode;
-    message?: string;
+export interface TracingContext {
+    deleteValue(key: symbol): TracingContext;
+    getValue(key: symbol): unknown;
+    setValue(key: symbol, value: unknown): TracingContext;
 }
 
 // @public
-export enum SpanStatusCode {
-    ERROR = 2,
-    OK = 1,
-    UNSET = 0
+export interface TracingSpan {
+    end(): void;
+    isRecording(): boolean;
+    recordException(exception: Error | string): void;
+    setAttribute(name: string, value: unknown): void;
+    setStatus(status: SpanStatus): void;
 }
 
 // @public
-export type TimeInput = HrTime | number | Date;
+export type TracingSpanKind = "client" | "server" | "producer" | "consumer" | "internal";
 
 // @public
-export const enum TraceFlags {
-    NONE = 0,
-    SAMPLED = 1
+export interface TracingSpanLink {
+    attributes?: {
+        [key: string]: unknown;
+    };
+    tracingContext: TracingContext;
 }
 
 // @public
-export interface Tracer {
-    startSpan(name: string, options?: SpanOptions, context?: Context): Span;
+export interface TracingSpanOptions {
+    spanAttributes?: {
+        [key: string]: unknown;
+    };
+    spanKind?: TracingSpanKind;
+    spanLinks?: TracingSpanLink[];
 }
 
 // @public
-export interface TraceState {
-    get(key: string): string | undefined;
-    serialize(): string;
-    set(key: string, value: string): TraceState;
-    unset(key: string): TraceState;
-}
+export function useInstrumenter(instrumenter: Instrumenter): void;
 
 // (No @packageDocumentation comment for this package)