New package core-tracing with support for Open Census

rush.json

@@ -401,6 +401,10 @@
     {
       "packageName": "@azure/template",
       "projectFolder": "sdk/template/template"
+    },
+    {
+      "packageName": "@azure/core-tracing",
+      "projectFolder": "sdk/core/core-tracing"
     }
   ]
 }

sdk/core/core-tracing/Changelog.md

@@ -0,0 +1,3 @@
+# 1.0.0-preview.1 5th August 2019
+
+Provides low-level interfaces and helper methods for tracing in Azure SDK

sdk/core/core-tracing/LICENSE.txt

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation. All rights reserved.
+
+    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

sdk/core/core-tracing/README.md

@@ -0,0 +1,23 @@
+# Azure Core HTTP client library for JS
+
+This is the core HTTP pipeline for Azure SDK JavaScript libraries which work in the browser and Node.js. This library is primarily intended to be used in code generated by [AutoRest](https://github.com/Azure/Autorest).
+
+## Getting started
+
+Coming soon....
+
+## Contributing
+
+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.
+
+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.
+
+If you'd like to contribute to this library, please read the [contributing guide](../../../CONTRIBUTING.md) to learn more about how to build and test the code.
+
+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.

sdk/core/core-tracing/api-extractor.json

@@ -0,0 +1,32 @@
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+    "mainEntryPointFilePath": "types/index.d.ts",
+    "docModel": {
+      "enabled": false
+    },
+    "apiReport": {
+      "enabled": true,
+      "reportFolder": "./review"
+    },
+    "dtsRollup": {
+      "enabled": true,
+      "untrimmedFilePath": "",
+      "publicTrimmedFilePath": "./types/core-tracing.d.ts"
+    },
+    "messages": {
+      "tsdocMessageReporting": {
+        "default": {
+          "logLevel": "none"
+        }
+      },
+      "extractorMessageReporting": {
+        "ae-missing-release-tag": {
+          "logLevel": "none"
+        },
+        "ae-unresolved-link": {
+          "logLevel": "none"
+        }
+      }
+    }
+  }
+

sdk/core/core-tracing/lib/implementations/noop/spanNoOpImpl.ts

@@ -0,0 +1,33 @@
+import { Span } from "../../interfaces/span";
+import { SpanContext } from "../../interfaces/span_context";
+import { Attributes } from "../../interfaces/attributes";
+import { Status } from "../../interfaces/status";
+
+export class SpanNoOpImpl implements Span {
+  context(): SpanContext {
+    throw new Error("Method not implemented.");
+  }
+  setAttribute(key: string, value: unknown): this {
+    throw new Error("Method not implemented.");
+  }
+  setAttributes(attributes: Attributes): this {
+    throw new Error("Method not implemented.");
+  }
+  addEvent(name: string, attributes?: Attributes | undefined): this {
+    throw new Error("Method not implemented.");
+  }
+  addLink(spanContext: SpanContext, attributes?: Attributes | undefined): this {
+    throw new Error("Method not implemented.");
+  }
+  setStatus(status: Status): this {
+    throw new Error("Method not implemented.");
+  }
+  updateName(name: string): this {
+    throw new Error("Method not implemented.");
+  }
+  start(startTime?: number): void {}
+  end(endTime?: number): void {}
+  isRecordingEvents(): boolean {
+    throw new Error("Method not implemented.");
+  }
+}

sdk/core/core-tracing/lib/implementations/noop/tracerNoOpImpl.ts

@@ -0,0 +1,25 @@
+import { Tracer } from "../../interfaces/tracer";
+import { SpanOptions } from "../../interfaces/SpanOptions";
+import { Span } from "../../interfaces/span";
+import { SpanNoOpImpl } from "./spanNoOpImpl";
+
+export class TracerNoOpImpl implements Tracer {
+  getCurrentSpan(): Span {
+    throw new Error("Method not implemented.");
+  }
+  startSpan(name: string, options?: SpanOptions | undefined): Span {
+    return new SpanNoOpImpl();
+  }
+  withSpan<T extends (...args: unknown[]) => unknown>(span: Span, fn: T): ReturnType<T> {
+    throw new Error("Method not implemented.");
+  }
+  recordSpanData(span: Span): void {
+    throw new Error("Method not implemented.");
+  }
+  getBinaryFormat(): unknown {
+    throw new Error("Method not implemented.");
+  }
+  getHttpTextFormat(): unknown {
+    throw new Error("Method not implemented.");
+  }
+}

sdk/core/core-tracing/lib/index.ts

@@ -0,0 +1,29 @@
+export { TracerProxy } from "./tracerProxy";
+
+// Utils
+export { SupportedPlugins } from "./utils/supportedPlugins";
+
+// Plugins
+export { NoOpSpanPlugin } from "./plugins/noop/noOpSpanPlugin";
+export { NoOpTracePlugin } from "./plugins/noop/noOpTracePlugin";
+export { OpenCensusSpanPlugin } from "./plugins/opencensus/openCensusSpanPlugin";
+export { OpenCensusTracePlugin } from "./plugins/opencensus/openCensusTracePlugin";
+
+// Implementations
+export { SpanNoOpImpl } from "./implementations/noop/spanNoOpImpl";
+export { TracerNoOpImpl } from "./implementations/noop/tracerNoOpImpl";
+
+// Interfaces
+export { Attributes } from "./interfaces/attributes";
+export { Event } from "./interfaces/Event";
+export { Link } from "./interfaces/link";
+export { Sampler } from "./interfaces/Sampler";
+export { SpanContext } from "./interfaces/span_context";
+export { SpanKind } from "./interfaces/span_kind";
+export { Span } from "./interfaces/span";
+export { SpanOptions } from "./interfaces/SpanOptions";
+export { Status, CanonicalCode } from "./interfaces/status";
+export { TimedEvent } from "./interfaces/TimedEvent";
+export { TraceOptions } from "./interfaces/trace_options";
+export { TraceState } from "./interfaces/trace_state";
+export { Tracer } from "./interfaces/tracer";

sdk/core/core-tracing/lib/interfaces/Event.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Attributes } from './attributes';
+
+/** A text annotation with a set of attributes. */
+export interface Event {
+  /** The name of the event. */
+  name: string;
+  /** The attributes of the event. */
+  attributes?: Attributes;
+}

sdk/core/core-tracing/lib/interfaces/Sampler.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { SpanContext } from './span_context';
+
+/**
+ * This interface represent a sampler. Sampling is a mechanism to control the
+ * noise and overhead introduced by OpenTelemetry by reducing the number of
+ * samples of traces collected and sent to the backend.
+ */
+export interface Sampler {
+  /**
+   * Checks whether span needs to be created and tracked.
+   *
+   * TODO: Consider to add required arguments https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/sampling-api.md#shouldsample
+   * @param [parentContext] Parent span context. Typically taken from the wire.
+   *     Can be null.
+   * @returns whether span should be sampled or not.
+   */
+  shouldSample(parentContext?: SpanContext): boolean;
+
+  /** Returns the sampler name or short description with the configuration. */
+  toString(): string;
+}

sdk/core/core-tracing/lib/interfaces/SpanOptions.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Span } from './span';
+import { Attributes } from './attributes';
+import { SpanKind } from './span_kind';
+import { SpanContext } from './span_context';
+
+/**
+ * Options needed for span creation
+ */
+export interface SpanOptions {
+  /** The SpanKind of a span */
+  kind?: SpanKind;
+
+  /** A spans attributes */
+  attributes?: Attributes;
+
+  /** Indicates that events are being recorded for a span */
+  isRecordingEvents?: boolean;
+
+  /**
+   * A parent SpanContext (or Span, for convenience) that the newly-started
+   * span will be the child of.
+   */
+  parent?: Span | SpanContext;
+
+  /** A manually specified start time for the created Span object. */
+  startTime?: number;
+}

sdk/core/core-tracing/lib/interfaces/TimedEvent.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Event } from './Event';
+
+/**
+ * Represents a timed event.
+ * A timed event is an event with a timestamp.
+ */
+export interface TimedEvent extends Event {
+  time: number;
+}

sdk/core/core-tracing/lib/interfaces/attributes.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** Defines a attributes interface. */
+export interface Attributes {
+  [attributeKey: string]: unknown;
+}

sdk/core/core-tracing/lib/interfaces/link.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Attributes } from './attributes';
+import { SpanContext } from './span_context';
+
+/**
+ * A pointer from the current {@link Span} to another span in the same trace or
+ * in a different trace.
+ */
+export interface Link {
+  /** The {@link SpanContext} of a linked span. */
+  spanContext: SpanContext;
+  /** A set of {@link Attributes} on the link. */
+  attributes?: Attributes;
+}