@itwin/core-bentley 4.0.0-dev.28 → 4.0.0-dev.30

package/lib/cjs/Tracing.d.ts

@@ -1,41 +1,41 @@
-import type { SpanAttributes, SpanContext, SpanOptions, Tracer } from "@opentelemetry/api";
-/**
- * Mirrors the SpanKind enum from [@opentelemetry/api](https://open-telemetry.github.io/opentelemetry-js-api/enums/spankind)
- * @alpha
- */
-export declare enum SpanKind {
-    INTERNAL = 0,
-    SERVER = 1,
-    CLIENT = 2,
-    PRODUCER = 3,
-    CONSUMER = 4
-}
-/**
- * Enables OpenTelemetry tracing in addition to traditional logging.
- * @alpha
- */
-export declare class Tracing {
-    private static _tracer?;
-    private static _openTelemetry?;
-    /**
-     * If OpenTelemetry tracing is enabled, creates a new span and runs the provided function in it.
-     * If OpenTelemetry tracing is _not_ enabled, runs the provided function.
-     * @param name name of the new span
-     * @param fn function to run inside the new span
-     * @param options span options
-     * @param parentContext optional context used to retrieve parent span id
-     */
-    static withSpan<T>(name: string, fn: () => Promise<T>, options?: SpanOptions, parentContext?: SpanContext): Promise<T>;
-    /**
-     * Enable logging to OpenTelemetry. [[Tracing.withSpan]] will be enabled, all log entries will be attached to active span as span events.
-     * [[IModelHost.startup]] will call this automatically if it succeeds in requiring `@opentelemetry/api`.
-     * @note Node.js OpenTelemetry SDK should be initialized by the user.
-     */
-    static enableOpenTelemetry(tracer: Tracer, api: typeof Tracing._openTelemetry): void;
-    private static withOpenTelemetry;
-    /** Set attributes on currently active openTelemetry span. Doesn't do anything if openTelemetry logging is not initialized.
-     * @param attributes  The attributes to set
-     */
-    static setAttributes(attributes: SpanAttributes): void;
-}
+import type { SpanAttributes, SpanContext, SpanOptions, Tracer } from "@opentelemetry/api";
+/**
+ * Mirrors the SpanKind enum from [@opentelemetry/api](https://open-telemetry.github.io/opentelemetry-js-api/enums/spankind)
+ * @alpha
+ */
+export declare enum SpanKind {
+    INTERNAL = 0,
+    SERVER = 1,
+    CLIENT = 2,
+    PRODUCER = 3,
+    CONSUMER = 4
+}
+/**
+ * Enables OpenTelemetry tracing in addition to traditional logging.
+ * @alpha
+ */
+export declare class Tracing {
+    private static _tracer?;
+    private static _openTelemetry?;
+    /**
+     * If OpenTelemetry tracing is enabled, creates a new span and runs the provided function in it.
+     * If OpenTelemetry tracing is _not_ enabled, runs the provided function.
+     * @param name name of the new span
+     * @param fn function to run inside the new span
+     * @param options span options
+     * @param parentContext optional context used to retrieve parent span id
+     */
+    static withSpan<T>(name: string, fn: () => Promise<T>, options?: SpanOptions, parentContext?: SpanContext): Promise<T>;
+    /**
+     * Enable logging to OpenTelemetry. [[Tracing.withSpan]] will be enabled, all log entries will be attached to active span as span events.
+     * [[IModelHost.startup]] will call this automatically if it succeeds in requiring `@opentelemetry/api`.
+     * @note Node.js OpenTelemetry SDK should be initialized by the user.
+     */
+    static enableOpenTelemetry(tracer: Tracer, api: typeof Tracing._openTelemetry): void;
+    private static withOpenTelemetry;
+    /** Set attributes on currently active openTelemetry span. Doesn't do anything if openTelemetry logging is not initialized.
+     * @param attributes  The attributes to set
+     */
+    static setAttributes(attributes: SpanAttributes): void;
+}
 //# sourceMappingURL=Tracing.d.ts.map

package/lib/cjs/Tracing.js

@@ -1,128 +1,128 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Tracing = exports.SpanKind = void 0;
-const Logger_1 = require("./Logger");
-// re-export so that consumers can construct full SpanOptions object without external dependencies
-/**
- * Mirrors the SpanKind enum from [@opentelemetry/api](https://open-telemetry.github.io/opentelemetry-js-api/enums/spankind)
- * @alpha
- */
-var SpanKind;
-(function (SpanKind) {
-    SpanKind[SpanKind["INTERNAL"] = 0] = "INTERNAL";
-    SpanKind[SpanKind["SERVER"] = 1] = "SERVER";
-    SpanKind[SpanKind["CLIENT"] = 2] = "CLIENT";
-    SpanKind[SpanKind["PRODUCER"] = 3] = "PRODUCER";
-    SpanKind[SpanKind["CONSUMER"] = 4] = "CONSUMER";
-})(SpanKind = exports.SpanKind || (exports.SpanKind = {}));
-function isValidPrimitive(val) {
-    return typeof val === "string" || typeof val === "number" || typeof val === "boolean";
-}
-// Only _homogenous_ arrays of strings, numbers, or booleans are supported as OpenTelemetry Attribute values.
-// Per the spec (https://opentelemetry.io/docs/reference/specification/common/common/#attribute), empty arrays and null values are supported too.
-function isValidPrimitiveArray(val) {
-    if (!Array.isArray(val))
-        return false;
-    let itemType;
-    for (const x of val) {
-        if (x === undefined || x === null)
-            continue;
-        if (!itemType) {
-            itemType = typeof x;
-            if (!isValidPrimitive(x))
-                return false;
-        }
-        if (typeof x !== itemType)
-            return false;
-    }
-    return true;
-}
-function isPlainObject(obj) {
-    return typeof obj === "object" && obj !== null && Object.getPrototypeOf(obj) === Object.prototype;
-}
-function* getFlatEntries(obj, path = "") {
-    if (isValidPrimitiveArray(obj)) {
-        yield [path, obj];
-        return;
-    }
-    // Prefer JSON serialization over flattening for any non-POJO types.
-    // There's just too many ways trying to flatten those can go wrong (Dates, Buffers, TypedArrays, etc.)
-    if (!isPlainObject(obj) && !Array.isArray(obj)) {
-        yield [path, isValidPrimitive(obj) ? obj : JSON.stringify(obj)];
-        return;
-    }
-    // Always serialize empty objects/arrays as empty array values
-    const entries = Object.entries(obj);
-    if (entries.length === 0)
-        yield [path, []];
-    for (const [key, val] of entries)
-        yield* getFlatEntries(val, (path === "") ? key : `${path}.${key}`);
-}
-function flattenObject(obj) {
-    return Object.fromEntries(getFlatEntries(obj));
-}
-/**
- * Enables OpenTelemetry tracing in addition to traditional logging.
- * @alpha
- */
-class Tracing {
-    /**
-     * If OpenTelemetry tracing is enabled, creates a new span and runs the provided function in it.
-     * If OpenTelemetry tracing is _not_ enabled, runs the provided function.
-     * @param name name of the new span
-     * @param fn function to run inside the new span
-     * @param options span options
-     * @param parentContext optional context used to retrieve parent span id
-     */
-    static async withSpan(name, fn, options, parentContext) {
-        if (Tracing._tracer === undefined || Tracing._openTelemetry === undefined)
-            return fn();
-        // this case is for context propagation - parentContext is typically constructed from HTTP headers
-        const parent = parentContext === undefined
-            ? Tracing._openTelemetry.context.active()
-            : Tracing._openTelemetry.trace.setSpanContext(Tracing._openTelemetry.context.active(), parentContext);
-        return Tracing._openTelemetry.context.with(Tracing._openTelemetry.trace.setSpan(parent, Tracing._tracer.startSpan(name, options, Tracing._openTelemetry.context.active())), async () => {
-            try {
-                return await fn();
-            }
-            catch (err) {
-                if (err instanceof Error) // ignore non-Error throws, such as RpcControlResponse
-                    Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.setAttribute("error", true);
-                throw err;
-            }
-            finally {
-                Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.end();
-            }
-        });
-    }
-    /**
-     * Enable logging to OpenTelemetry. [[Tracing.withSpan]] will be enabled, all log entries will be attached to active span as span events.
-     * [[IModelHost.startup]] will call this automatically if it succeeds in requiring `@opentelemetry/api`.
-     * @note Node.js OpenTelemetry SDK should be initialized by the user.
-     */
-    static enableOpenTelemetry(tracer, api) {
-        Tracing._tracer = tracer;
-        Tracing._openTelemetry = api;
-        Logger_1.Logger.logTrace = Tracing.withOpenTelemetry(Logger_1.Logger.logTrace);
-        Logger_1.Logger.logInfo = Tracing.withOpenTelemetry(Logger_1.Logger.logInfo);
-        Logger_1.Logger.logWarning = Tracing.withOpenTelemetry(Logger_1.Logger.logWarning);
-        Logger_1.Logger.logError = Tracing.withOpenTelemetry(Logger_1.Logger.logError);
-    }
-    static withOpenTelemetry(base, isError = false) {
-        return (category, message, metaData) => {
-            try {
-                Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.addEvent(message, { ...flattenObject(Logger_1.Logger.getMetaData(metaData)), error: isError });
-            }
-            catch (_e) { } // avoid throwing random errors (with stack trace mangled by async hooks) when openTelemetry collector doesn't work
-            base(category, message, metaData);
-        };
-    }
-    /** Set attributes on currently active openTelemetry span. Doesn't do anything if openTelemetry logging is not initialized.
-     * @param attributes  The attributes to set
-     */
-    static setAttributes(attributes) {
-        Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.setAttributes(attributes);
-    }
-}
-exports.Tracing = Tracing;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tracing = exports.SpanKind = void 0;
+const Logger_1 = require("./Logger");
+// re-export so that consumers can construct full SpanOptions object without external dependencies
+/**
+ * Mirrors the SpanKind enum from [@opentelemetry/api](https://open-telemetry.github.io/opentelemetry-js-api/enums/spankind)
+ * @alpha
+ */
+var SpanKind;
+(function (SpanKind) {
+    SpanKind[SpanKind["INTERNAL"] = 0] = "INTERNAL";
+    SpanKind[SpanKind["SERVER"] = 1] = "SERVER";
+    SpanKind[SpanKind["CLIENT"] = 2] = "CLIENT";
+    SpanKind[SpanKind["PRODUCER"] = 3] = "PRODUCER";
+    SpanKind[SpanKind["CONSUMER"] = 4] = "CONSUMER";
+})(SpanKind = exports.SpanKind || (exports.SpanKind = {}));
+function isValidPrimitive(val) {
+    return typeof val === "string" || typeof val === "number" || typeof val === "boolean";
+}
+// Only _homogenous_ arrays of strings, numbers, or booleans are supported as OpenTelemetry Attribute values.
+// Per the spec (https://opentelemetry.io/docs/reference/specification/common/common/#attribute), empty arrays and null values are supported too.
+function isValidPrimitiveArray(val) {
+    if (!Array.isArray(val))
+        return false;
+    let itemType;
+    for (const x of val) {
+        if (x === undefined || x === null)
+            continue;
+        if (!itemType) {
+            itemType = typeof x;
+            if (!isValidPrimitive(x))
+                return false;
+        }
+        if (typeof x !== itemType)
+            return false;
+    }
+    return true;
+}
+function isPlainObject(obj) {
+    return typeof obj === "object" && obj !== null && Object.getPrototypeOf(obj) === Object.prototype;
+}
+function* getFlatEntries(obj, path = "") {
+    if (isValidPrimitiveArray(obj)) {
+        yield [path, obj];
+        return;
+    }
+    // Prefer JSON serialization over flattening for any non-POJO types.
+    // There's just too many ways trying to flatten those can go wrong (Dates, Buffers, TypedArrays, etc.)
+    if (!isPlainObject(obj) && !Array.isArray(obj)) {
+        yield [path, isValidPrimitive(obj) ? obj : JSON.stringify(obj)];
+        return;
+    }
+    // Always serialize empty objects/arrays as empty array values
+    const entries = Object.entries(obj);
+    if (entries.length === 0)
+        yield [path, []];
+    for (const [key, val] of entries)
+        yield* getFlatEntries(val, (path === "") ? key : `${path}.${key}`);
+}
+function flattenObject(obj) {
+    return Object.fromEntries(getFlatEntries(obj));
+}
+/**
+ * Enables OpenTelemetry tracing in addition to traditional logging.
+ * @alpha
+ */
+class Tracing {
+    /**
+     * If OpenTelemetry tracing is enabled, creates a new span and runs the provided function in it.
+     * If OpenTelemetry tracing is _not_ enabled, runs the provided function.
+     * @param name name of the new span
+     * @param fn function to run inside the new span
+     * @param options span options
+     * @param parentContext optional context used to retrieve parent span id
+     */
+    static async withSpan(name, fn, options, parentContext) {
+        if (Tracing._tracer === undefined || Tracing._openTelemetry === undefined)
+            return fn();
+        // this case is for context propagation - parentContext is typically constructed from HTTP headers
+        const parent = parentContext === undefined
+            ? Tracing._openTelemetry.context.active()
+            : Tracing._openTelemetry.trace.setSpanContext(Tracing._openTelemetry.context.active(), parentContext);
+        return Tracing._openTelemetry.context.with(Tracing._openTelemetry.trace.setSpan(parent, Tracing._tracer.startSpan(name, options, Tracing._openTelemetry.context.active())), async () => {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                if (err instanceof Error) // ignore non-Error throws, such as RpcControlResponse
+                    Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.setAttribute("error", true);
+                throw err;
+            }
+            finally {
+                Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.end();
+            }
+        });
+    }
+    /**
+     * Enable logging to OpenTelemetry. [[Tracing.withSpan]] will be enabled, all log entries will be attached to active span as span events.
+     * [[IModelHost.startup]] will call this automatically if it succeeds in requiring `@opentelemetry/api`.
+     * @note Node.js OpenTelemetry SDK should be initialized by the user.
+     */
+    static enableOpenTelemetry(tracer, api) {
+        Tracing._tracer = tracer;
+        Tracing._openTelemetry = api;
+        Logger_1.Logger.logTrace = Tracing.withOpenTelemetry(Logger_1.Logger.logTrace);
+        Logger_1.Logger.logInfo = Tracing.withOpenTelemetry(Logger_1.Logger.logInfo);
+        Logger_1.Logger.logWarning = Tracing.withOpenTelemetry(Logger_1.Logger.logWarning);
+        Logger_1.Logger.logError = Tracing.withOpenTelemetry(Logger_1.Logger.logError);
+    }
+    static withOpenTelemetry(base, isError = false) {
+        return (category, message, metaData) => {
+            try {
+                Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.addEvent(message, { ...flattenObject(Logger_1.Logger.getMetaData(metaData)), error: isError });
+            }
+            catch (_e) { } // avoid throwing random errors (with stack trace mangled by async hooks) when openTelemetry collector doesn't work
+            base(category, message, metaData);
+        };
+    }
+    /** Set attributes on currently active openTelemetry span. Doesn't do anything if openTelemetry logging is not initialized.
+     * @param attributes  The attributes to set
+     */
+    static setAttributes(attributes) {
+        Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.setAttributes(attributes);
+    }
+}
+exports.Tracing = Tracing;
 //# sourceMappingURL=Tracing.js.map

package/lib/cjs/Tracing.js.map

@@ -1 +1 @@
-{"version":3,"file":"Tracing.js","sourceRoot":"","sources":["../../src/Tracing.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\nimport type { ContextAPI, SpanAttributes, SpanAttributeValue, SpanContext, SpanOptions, TraceAPI, Tracer } from \"@opentelemetry/api\";\nimport { LogFunction, Logger } from \"./Logger\";\n\n// re-export so that consumers can construct full SpanOptions object without external dependencies\n/**\n * Mirrors the SpanKind enum from [@opentelemetry/api](https://open-telemetry.github.io/opentelemetry-js-api/enums/spankind)\n * @alpha\n */\nexport enum SpanKind {\n  INTERNAL = 0,\n  SERVER = 1,\n  CLIENT = 2,\n  PRODUCER = 3,\n  CONSUMER = 4\n}\n\nfunction isValidPrimitive(val: unknown): val is SpanAttributeValue {\n  return typeof val === \"string\" || typeof val === \"number\" || typeof val === \"boolean\";\n}\n\n// Only _homogenous_ arrays of strings, numbers, or booleans are supported as OpenTelemetry Attribute values.\n// Per the spec (https://opentelemetry.io/docs/reference/specification/common/common/#attribute), empty arrays and null values are supported too.\nfunction isValidPrimitiveArray(val: unknown): val is SpanAttributeValue {\n  if (!Array.isArray(val))\n    return false;\n\n  let itemType;\n  for (const x of val) {\n    if (x === undefined || x === null)\n      continue;\n\n    if (!itemType) {\n      itemType = typeof x;\n      if (!isValidPrimitive(x))\n        return false;\n    }\n\n    if (typeof x !== itemType)\n      return false;\n  }\n  return true;\n}\n\nfunction isPlainObject(obj: unknown): obj is object {\n  return typeof obj === \"object\" && obj !== null && Object.getPrototypeOf(obj) === Object.prototype;\n}\n\nfunction* getFlatEntries(obj: unknown, path = \"\"): Iterable<[string, SpanAttributeValue]> {\n  if (isValidPrimitiveArray(obj)) {\n    yield [path, obj];\n    return;\n  }\n\n  // Prefer JSON serialization over flattening for any non-POJO types.\n  // There's just too many ways trying to flatten those can go wrong (Dates, Buffers, TypedArrays, etc.)\n  if (!isPlainObject(obj) && !Array.isArray(obj)) {\n    yield [path, isValidPrimitive(obj) ? obj : JSON.stringify(obj)];\n    return;\n  }\n\n  // Always serialize empty objects/arrays as empty array values\n  const entries = Object.entries(obj);\n  if (entries.length === 0)\n    yield [path, []];\n\n  for (const [key, val] of entries)\n    yield* getFlatEntries(val, (path === \"\") ? key : `${path}.${key}`);\n}\n\nfunction flattenObject(obj: object): SpanAttributes {\n  return Object.fromEntries(getFlatEntries(obj));\n}\n\n/**\n * Enables OpenTelemetry tracing in addition to traditional logging.\n * @alpha\n */\nexport class Tracing {\n  private static _tracer?: Tracer;\n  private static _openTelemetry?: { trace: Pick<TraceAPI, \"setSpan\" | \"setSpanContext\" | \"getSpan\">, context: Pick<ContextAPI, \"active\" | \"with\"> };\n\n  /**\n   * If OpenTelemetry tracing is enabled, creates a new span and runs the provided function in it.\n   * If OpenTelemetry tracing is _not_ enabled, runs the provided function.\n   * @param name name of the new span\n   * @param fn function to run inside the new span\n   * @param options span options\n   * @param parentContext optional context used to retrieve parent span id\n   */\n  public static async withSpan<T>(name: string, fn: () => Promise<T>, options?: SpanOptions, parentContext?: SpanContext): Promise<T> {\n    if (Tracing._tracer === undefined || Tracing._openTelemetry === undefined)\n      return fn();\n\n    // this case is for context propagation - parentContext is typically constructed from HTTP headers\n    const parent = parentContext === undefined\n      ? Tracing._openTelemetry.context.active()\n      : Tracing._openTelemetry.trace.setSpanContext(Tracing._openTelemetry.context.active(), parentContext);\n\n    return Tracing._openTelemetry.context.with(\n      Tracing._openTelemetry.trace.setSpan(\n        parent,\n        Tracing._tracer.startSpan(name, options, Tracing._openTelemetry.context.active())\n      ),\n      async () => {\n        try {\n          return await fn();\n        } catch (err) {\n          if (err instanceof Error) // ignore non-Error throws, such as RpcControlResponse\n            Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.setAttribute(\"error\", true);\n          throw err;\n        } finally {\n          Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.end();\n        }\n      },\n    );\n  }\n\n  /**\n   * Enable logging to OpenTelemetry. [[Tracing.withSpan]] will be enabled, all log entries will be attached to active span as span events.\n   * [[IModelHost.startup]] will call this automatically if it succeeds in requiring `@opentelemetry/api`.\n   * @note Node.js OpenTelemetry SDK should be initialized by the user.\n   */\n  public static enableOpenTelemetry(tracer: Tracer, api: typeof Tracing._openTelemetry) {\n    Tracing._tracer = tracer;\n    Tracing._openTelemetry = api;\n    Logger.logTrace = Tracing.withOpenTelemetry(Logger.logTrace);\n    Logger.logInfo = Tracing.withOpenTelemetry(Logger.logInfo);\n    Logger.logWarning = Tracing.withOpenTelemetry(Logger.logWarning);\n    Logger.logError = Tracing.withOpenTelemetry(Logger.logError);\n  }\n\n  private static withOpenTelemetry(base: LogFunction, isError: boolean = false): LogFunction {\n    return (category, message, metaData) => {\n      try {\n        Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.addEvent(message, { ...flattenObject(Logger.getMetaData(metaData)), error: isError });\n      } catch (_e) { } // avoid throwing random errors (with stack trace mangled by async hooks) when openTelemetry collector doesn't work\n      base(category, message, metaData);\n    };\n  }\n\n  /** Set attributes on currently active openTelemetry span. Doesn't do anything if openTelemetry logging is not initialized.\n   * @param attributes  The attributes to set\n   */\n  public static setAttributes(attributes: SpanAttributes) {\n    Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.setAttributes(attributes);\n  }\n}\n"]}
+{"version":3,"file":"Tracing.js","sourceRoot":"","sources":["../../src/Tracing.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\nimport type { ContextAPI, SpanAttributes, SpanAttributeValue, SpanContext, SpanOptions, TraceAPI, Tracer } from \"@opentelemetry/api\";\r\nimport { LogFunction, Logger } from \"./Logger\";\r\n\r\n// re-export so that consumers can construct full SpanOptions object without external dependencies\r\n/**\r\n * Mirrors the SpanKind enum from [@opentelemetry/api](https://open-telemetry.github.io/opentelemetry-js-api/enums/spankind)\r\n * @alpha\r\n */\r\nexport enum SpanKind {\r\n  INTERNAL = 0,\r\n  SERVER = 1,\r\n  CLIENT = 2,\r\n  PRODUCER = 3,\r\n  CONSUMER = 4\r\n}\r\n\r\nfunction isValidPrimitive(val: unknown): val is SpanAttributeValue {\r\n  return typeof val === \"string\" || typeof val === \"number\" || typeof val === \"boolean\";\r\n}\r\n\r\n// Only _homogenous_ arrays of strings, numbers, or booleans are supported as OpenTelemetry Attribute values.\r\n// Per the spec (https://opentelemetry.io/docs/reference/specification/common/common/#attribute), empty arrays and null values are supported too.\r\nfunction isValidPrimitiveArray(val: unknown): val is SpanAttributeValue {\r\n  if (!Array.isArray(val))\r\n    return false;\r\n\r\n  let itemType;\r\n  for (const x of val) {\r\n    if (x === undefined || x === null)\r\n      continue;\r\n\r\n    if (!itemType) {\r\n      itemType = typeof x;\r\n      if (!isValidPrimitive(x))\r\n        return false;\r\n    }\r\n\r\n    if (typeof x !== itemType)\r\n      return false;\r\n  }\r\n  return true;\r\n}\r\n\r\nfunction isPlainObject(obj: unknown): obj is object {\r\n  return typeof obj === \"object\" && obj !== null && Object.getPrototypeOf(obj) === Object.prototype;\r\n}\r\n\r\nfunction* getFlatEntries(obj: unknown, path = \"\"): Iterable<[string, SpanAttributeValue]> {\r\n  if (isValidPrimitiveArray(obj)) {\r\n    yield [path, obj];\r\n    return;\r\n  }\r\n\r\n  // Prefer JSON serialization over flattening for any non-POJO types.\r\n  // There's just too many ways trying to flatten those can go wrong (Dates, Buffers, TypedArrays, etc.)\r\n  if (!isPlainObject(obj) && !Array.isArray(obj)) {\r\n    yield [path, isValidPrimitive(obj) ? obj : JSON.stringify(obj)];\r\n    return;\r\n  }\r\n\r\n  // Always serialize empty objects/arrays as empty array values\r\n  const entries = Object.entries(obj);\r\n  if (entries.length === 0)\r\n    yield [path, []];\r\n\r\n  for (const [key, val] of entries)\r\n    yield* getFlatEntries(val, (path === \"\") ? key : `${path}.${key}`);\r\n}\r\n\r\nfunction flattenObject(obj: object): SpanAttributes {\r\n  return Object.fromEntries(getFlatEntries(obj));\r\n}\r\n\r\n/**\r\n * Enables OpenTelemetry tracing in addition to traditional logging.\r\n * @alpha\r\n */\r\nexport class Tracing {\r\n  private static _tracer?: Tracer;\r\n  private static _openTelemetry?: { trace: Pick<TraceAPI, \"setSpan\" | \"setSpanContext\" | \"getSpan\">, context: Pick<ContextAPI, \"active\" | \"with\"> };\r\n\r\n  /**\r\n   * If OpenTelemetry tracing is enabled, creates a new span and runs the provided function in it.\r\n   * If OpenTelemetry tracing is _not_ enabled, runs the provided function.\r\n   * @param name name of the new span\r\n   * @param fn function to run inside the new span\r\n   * @param options span options\r\n   * @param parentContext optional context used to retrieve parent span id\r\n   */\r\n  public static async withSpan<T>(name: string, fn: () => Promise<T>, options?: SpanOptions, parentContext?: SpanContext): Promise<T> {\r\n    if (Tracing._tracer === undefined || Tracing._openTelemetry === undefined)\r\n      return fn();\r\n\r\n    // this case is for context propagation - parentContext is typically constructed from HTTP headers\r\n    const parent = parentContext === undefined\r\n      ? Tracing._openTelemetry.context.active()\r\n      : Tracing._openTelemetry.trace.setSpanContext(Tracing._openTelemetry.context.active(), parentContext);\r\n\r\n    return Tracing._openTelemetry.context.with(\r\n      Tracing._openTelemetry.trace.setSpan(\r\n        parent,\r\n        Tracing._tracer.startSpan(name, options, Tracing._openTelemetry.context.active())\r\n      ),\r\n      async () => {\r\n        try {\r\n          return await fn();\r\n        } catch (err) {\r\n          if (err instanceof Error) // ignore non-Error throws, such as RpcControlResponse\r\n            Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.setAttribute(\"error\", true);\r\n          throw err;\r\n        } finally {\r\n          Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.end();\r\n        }\r\n      },\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Enable logging to OpenTelemetry. [[Tracing.withSpan]] will be enabled, all log entries will be attached to active span as span events.\r\n   * [[IModelHost.startup]] will call this automatically if it succeeds in requiring `@opentelemetry/api`.\r\n   * @note Node.js OpenTelemetry SDK should be initialized by the user.\r\n   */\r\n  public static enableOpenTelemetry(tracer: Tracer, api: typeof Tracing._openTelemetry) {\r\n    Tracing._tracer = tracer;\r\n    Tracing._openTelemetry = api;\r\n    Logger.logTrace = Tracing.withOpenTelemetry(Logger.logTrace);\r\n    Logger.logInfo = Tracing.withOpenTelemetry(Logger.logInfo);\r\n    Logger.logWarning = Tracing.withOpenTelemetry(Logger.logWarning);\r\n    Logger.logError = Tracing.withOpenTelemetry(Logger.logError);\r\n  }\r\n\r\n  private static withOpenTelemetry(base: LogFunction, isError: boolean = false): LogFunction {\r\n    return (category, message, metaData) => {\r\n      try {\r\n        Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.addEvent(message, { ...flattenObject(Logger.getMetaData(metaData)), error: isError });\r\n      } catch (_e) { } // avoid throwing random errors (with stack trace mangled by async hooks) when openTelemetry collector doesn't work\r\n      base(category, message, metaData);\r\n    };\r\n  }\r\n\r\n  /** Set attributes on currently active openTelemetry span. Doesn't do anything if openTelemetry logging is not initialized.\r\n   * @param attributes  The attributes to set\r\n   */\r\n  public static setAttributes(attributes: SpanAttributes) {\r\n    Tracing._openTelemetry?.trace.getSpan(Tracing._openTelemetry.context.active())?.setAttributes(attributes);\r\n  }\r\n}\r\n"]}

package/lib/cjs/TupleKeyedMap.d.ts

@@ -1,37 +1,37 @@
-/** @packageDocumentation
- * @module Collections
- */
-/** A map similar to the standard JavaScript Map collection except that the keys must be a tuple
- * (javascript array), and two keys are considered equal if their elements in order are strict-equal,
- * and the tuples have the same amount of elements
- *
- * This means you can use array literals to key data in Maps that would otherwise be reference-compared
- * if using JavaScript's built in Map
- *
- * Note that JavaScript's Map type, unlike this one that uses strict equality, uses instead
- * SameValueZero equality comparison
- * @see https://262.ecma-international.org/6.0/#sec-samevaluezero
- *
- * ```js
- * const map = new TupleKeyedMap([[1,"y"], "value"]);
- * const value = map.get([1, "y"]); // a normal map would identify these keys as different because they are independent objects
- * ```
- *
- * It is implemented by each index of the tuple key being used as a singular key into a submap
- * @note this only implements a subset of the Map interface
- * @public
- */
-export declare class TupleKeyedMap<K extends readonly any[], V> {
-    private _map;
-    constructor(entries?: readonly (readonly [K, V])[] | null);
-    clear(): void;
-    private makeKeyError;
-    get(key: K): V | undefined;
-    has(key: K): boolean;
-    set(key: K, value: V): this;
-    [Symbol.iterator](): IterableIterator<[K, V]>;
-    private _size;
-    get size(): number;
-    get [Symbol.toStringTag](): string;
-}
+/** @packageDocumentation
+ * @module Collections
+ */
+/** A map similar to the standard JavaScript Map collection except that the keys must be a tuple
+ * (javascript array), and two keys are considered equal if their elements in order are strict-equal,
+ * and the tuples have the same amount of elements
+ *
+ * This means you can use array literals to key data in Maps that would otherwise be reference-compared
+ * if using JavaScript's built in Map
+ *
+ * Note that JavaScript's Map type, unlike this one that uses strict equality, uses instead
+ * SameValueZero equality comparison
+ * @see https://262.ecma-international.org/6.0/#sec-samevaluezero
+ *
+ * ```js
+ * const map = new TupleKeyedMap([[1,"y"], "value"]);
+ * const value = map.get([1, "y"]); // a normal map would identify these keys as different because they are independent objects
+ * ```
+ *
+ * It is implemented by each index of the tuple key being used as a singular key into a submap
+ * @note this only implements a subset of the Map interface
+ * @public
+ */
+export declare class TupleKeyedMap<K extends readonly any[], V> {
+    private _map;
+    constructor(entries?: readonly (readonly [K, V])[] | null);
+    clear(): void;
+    private makeKeyError;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    set(key: K, value: V): this;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+    private _size;
+    get size(): number;
+    get [Symbol.toStringTag](): string;
+}
 //# sourceMappingURL=TupleKeyedMap.d.ts.map