@fluidframework/telemetry-utils 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.224419

package/dist/errorLogging.d.ts

@@ -2,26 +2,43 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { ILoggingError, ITaggedTelemetryPropertyType, ITelemetryLogger, ITelemetryProperties } from "@fluidframework/common-definitions";
+import { ILoggingError, ITelemetryBaseProperties, Tagged } from "@fluidframework/core-interfaces";
 import { IFluidErrorBase } from "./fluidErrorBase";
-/** Inspect the given error for common "safe" props and return them */
-export declare function extractLogSafeErrorProperties(error: any, sanitizeStack: boolean): {
+import { ITelemetryLoggerExt, TelemetryEventPropertyTypeExt } from "./telemetryTypes";
+/**
+ * Inspect the given error for common "safe" props and return them.
+ *
+ * @internal
+ */
+export declare function extractLogSafeErrorProperties(error: unknown, sanitizeStack: boolean): {
     message: string;
     errorType?: string | undefined;
     stack?: string | undefined;
 };
-/** type guard for ILoggingError interface */
-export declare const isILoggingError: (x: any) => x is ILoggingError;
-/** Metadata to annotate an error object when annotating or normalizing it */
+/**
+ * Type-guard for {@link @fluidframework/core-interfaces#ILoggingError}.
+ *
+ * @internal
+ */
+export declare const isILoggingError: (x: unknown) => x is ILoggingError;
+/**
+ * Metadata to annotate an error object when annotating or normalizing it
+ *
+ * @internal
+ */
 export interface IFluidErrorAnnotations {
-    /** Telemetry props to log with the error */
-    props?: ITelemetryProperties;
+    /**
+     * Telemetry props to log with the error
+     */
+    props?: ITelemetryBaseProperties;
 }
 /**
  * Normalize the given error yielding a valid Fluid Error
  * @returns A valid Fluid Error with any provided annotations applied
  * @param error - The error to normalize
  * @param annotations - Annotations to apply to the normalized error
+ *
+ * @internal
  */
 export declare function normalizeError(error: unknown, annotations?: IFluidErrorAnnotations): IFluidErrorBase;
 /**
@@ -32,8 +49,16 @@ export declare function normalizeError(error: unknown, annotations?: IFluidError
  * For such cases it's better to not read stack property right away, but rather delay it until / if it's needed
  * Some browsers will populate stack right away, others require throwing Error, so we do auto-detection on the fly.
  * @returns Error object that has stack populated.
+ *
+ * @internal
  */
 export declare function generateErrorWithStack(): Error;
+/**
+ * Generate a stack at this callsite as if an error were thrown from here.
+ * @returns the callstack (does not throw)
+ *
+ * @internal
+ */
 export declare function generateStack(): string | undefined;
 /**
  * Create a new error using newErrorFn, wrapping and caused by the given unknown error.
@@ -41,40 +66,69 @@ export declare function generateStack(): string | undefined;
  * @param innerError - An error from untrusted/unknown origins
  * @param newErrorFn - callback that will create a new error given the original error's message
  * @returns A new error object "wrapping" the given error
+ *
+ * @internal
  */
 export declare function wrapError<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T): T;
-/** The same as wrapError, but also logs the innerError, including the wrapping error's instance id */
-export declare function wrapErrorAndLog<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T, logger: ITelemetryLogger): T;
+/**
+ * The same as wrapError, but also logs the innerError, including the wrapping error's instance ID.
+ *
+ * @typeParam T - The kind of wrapper error to create.
+ *
+ * @internal
+ */
+export declare function wrapErrorAndLog<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T, logger: ITelemetryLoggerExt): T;
+/**
+ * Attempts to overwrite the error's stack
+ *
+ * There have been reports of certain JS environments where overwriting stack will throw.
+ * If that happens, this adds the given stack as the telemetry property "stack2"
+ *
+ * @internal
+ */
+export declare function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string): void;
 /**
  * True for any error object that is an (optionally normalized) external error
- * False for any error we created and raised within the FF codebase, or wrapped in a well-known error type
+ * False for any error we created and raised within the FF codebase via LoggingError base class,
+ * or wrapped in a well-known error type
+ *
+ * @internal
  */
-export declare function isExternalError(e: any): boolean;
+export declare function isExternalError(error: unknown): boolean;
 /**
- * Type guard to identify if a particular value (loosely) appears to be a tagged telemetry property
+ * Type guard to identify if a particular telemetry property appears to be a
+ * {@link @fluidframework/core-interfaces#Tagged} telemetry property.
+ *
+ * @internal
  */
-export declare function isTaggedTelemetryPropertyValue(x: any): x is ITaggedTelemetryPropertyType;
+export declare function isTaggedTelemetryPropertyValue(x: Tagged<TelemetryEventPropertyTypeExt> | TelemetryEventPropertyTypeExt): x is Tagged<TelemetryEventPropertyTypeExt>;
 /**
  * Borrowed from
  * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cyclic_object_value#examples}
  * Avoids runtime errors with circular references.
  * Not ideal, as will cut values that are not necessarily circular references.
  * Could be improved by implementing Node's util.inspect() for browser (minus all the coloring code)
-*/
-export declare const getCircularReplacer: () => (key: string, value: any) => any;
+ *
+ * @internal
+ */
+export declare const getCircularReplacer: () => (key: string, value: unknown) => any;
 /**
  * Base class for "trusted" errors we create, whose properties can generally be logged to telemetry safely.
  * All properties set on the object, or passed in (via the constructor or addTelemetryProperties),
  * will be logged in accordance with their tag, if present.
  *
  * PLEASE take care to avoid setting sensitive data on this object without proper tagging!
+ *
+ * @internal
  */
 export declare class LoggingError extends Error implements ILoggingError, Omit<IFluidErrorBase, "errorType"> {
     private readonly omitPropsFromLogging;
     private _errorInstanceId;
     get errorInstanceId(): string;
     overwriteErrorInstanceId(id: string): void;
-    /** Back-compat to appease isFluidError typeguard in old code that may handle this error */
+    /**
+     * Backwards compatibility to appease {@link isFluidError} in old code that may handle this error.
+     */
     private readonly fluidErrorCode;
     /**
      * Create a new LoggingError
@@ -82,14 +136,26 @@ export declare class LoggingError extends Error implements ILoggingError, Omit<I
      * @param props - telemetry props to include on the error for when it's logged
      * @param omitPropsFromLogging - properties by name to omit from telemetry props
      */
-    constructor(message: string, props?: ITelemetryProperties, omitPropsFromLogging?: Set<string>);
+    constructor(message: string, props?: ITelemetryBaseProperties, omitPropsFromLogging?: Set<string>);
+    /**
+     * Determines if a given object is an instance of a LoggingError
+     * @param object - any object
+     * @returns true if the object is an instance of a LoggingError, false if not.
+     */
+    static typeCheck(object: unknown): object is LoggingError;
     /**
      * Add additional properties to be logged
      */
-    addTelemetryProperties(props: ITelemetryProperties): void;
+    addTelemetryProperties(props: ITelemetryBaseProperties): void;
     /**
      * Get all properties fit to be logged to telemetry for this error
      */
-    getTelemetryProperties(): ITelemetryProperties;
+    getTelemetryProperties(): ITelemetryBaseProperties;
 }
+/**
+ * The Error class used when normalizing an external error
+ *
+ * @internal
+ */
+export declare const NORMALIZED_ERROR_TYPE = "genericError";
 //# sourceMappingURL=errorLogging.d.ts.map

package/dist/errorLogging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorLogging.d.ts","sourceRoot":"","sources":["../src/errorLogging.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACH,aAAa,EACb,4BAA4B,EAC5B,gBAAgB,EAChB,oBAAoB,EACvB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAEH,eAAe,EAGlB,MAAM,kBAAkB,CAAC;AAO1B,sEAAsE;AACtE,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO;aAiBhD,MAAM;;;EAkBrC;AAED,6CAA6C;AAC7C,eAAO,MAAM,eAAe,MAAO,GAAG,uBAAwE,CAAC;AAW/G,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACnC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,oBAAoB,CAAC;CAChC;AAYD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,OAAO,EACd,WAAW,GAAE,sBAA2B,GACzC,eAAe,CAwCjB;AAID;;;;;;;;GAQG;AACF,wBAAgB,sBAAsB,IAAI,KAAK,CAgB/C;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,YAAY,EAC5C,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,GACnC,CAAC,CAgCH;AAED,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EAClD,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,EAClC,MAAM,EAAE,gBAAgB,KAiB3B;AAWD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,GAAG,OAAO,CAI/C;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,IAAI,4BAA4B,CAExF;AAiCD;;;;;;EAME;AACF,eAAO,MAAM,mBAAmB,cAEf,MAAM,SAAS,GAAG,KAAG,GASrC,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,YAAa,SAAQ,KAAM,YAAW,aAAa,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC;IAkB5F,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IAjBzC,OAAO,CAAC,gBAAgB,CAAU;IAClC,IAAI,eAAe,WAAoC;IACvD,wBAAwB,CAAC,EAAE,EAAE,MAAM;IAEnC,2FAA2F;IAE3F,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAY;IAE3C;;;;;OAKG;gBAEC,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,oBAAoB,EACX,oBAAoB,GAAE,GAAG,CAAC,MAAM,CAAa;IAalE;;OAEG;IACI,sBAAsB,CAAC,KAAK,EAAE,oBAAoB;IAIzD;;OAEG;IACI,sBAAsB,IAAI,oBAAoB;CAUxD"}
+{"version":3,"file":"errorLogging.d.ts","sourceRoot":"","sources":["../src/errorLogging.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,aAAa,EACb,wBAAwB,EAExB,MAAM,EACN,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAEN,eAAe,EAGf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AAStF;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC5C,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,OAAO,GACpB;IACF,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,CAoCA;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,MAAO,OAAO,uBACkC,CAAC;AAgB7E;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC;;OAEG;IACH,KAAK,CAAC,EAAE,wBAAwB,CAAC;CACjC;AAeD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,OAAO,EACd,WAAW,GAAE,sBAA2B,GACtC,eAAe,CAqDjB;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,IAAI,KAAK,CAgB9C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,YAAY,EAC/C,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,GAChC,CAAC,CA6BH;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACrD,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,EAClC,MAAM,EAAE,mBAAmB,GACzB,CAAC,CAmBH;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAMzF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWvD;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC7C,CAAC,EAAE,MAAM,CAAC,6BAA6B,CAAC,GAAG,6BAA6B,GACtE,CAAC,IAAI,MAAM,CAAC,6BAA6B,CAAC,CAE5C;AA2DD;;;;;;;;GAQG;AAGH,eAAO,MAAM,mBAAmB,cAAc,MAAM,SAAS,OAAO,KAAK,GAWxE,CAAC;AAGF;;;;;;;;GAQG;AACH,qBAAa,YACZ,SAAQ,KACR,YAAW,aAAa,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC;IA0B3D,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IAxBtC,OAAO,CAAC,gBAAgB,CAAU;IAClC,IAAI,eAAe,IAAI,MAAM,CAE5B;IACD,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI1C;;OAEG;IAGH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAY;IAE3C;;;;;OAKG;gBAEF,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,wBAAwB,EACf,oBAAoB,GAAE,GAAG,CAAC,MAAM,CAAa;IAa/D;;;;OAIG;WACW,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,YAAY;IAWhE;;OAEG;IACI,sBAAsB,CAAC,KAAK,EAAE,wBAAwB,GAAG,IAAI;IAIpE;;OAEG;IACI,sBAAsB,IAAI,wBAAwB;CAUzD;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,iBAAiB,CAAC"}

package/dist/errorLogging.js

@@ -4,14 +4,20 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LoggingError = exports.getCircularReplacer = exports.isTaggedTelemetryPropertyValue = exports.isExternalError = exports.wrapErrorAndLog = exports.wrapError = exports.generateStack = exports.generateErrorWithStack = exports.normalizeError = exports.isILoggingError = exports.extractLogSafeErrorProperties = void 0;
+exports.NORMALIZED_ERROR_TYPE = exports.LoggingError = exports.getCircularReplacer = exports.isTaggedTelemetryPropertyValue = exports.isExternalError = exports.overwriteStack = exports.wrapErrorAndLog = exports.wrapError = exports.generateStack = exports.generateErrorWithStack = exports.normalizeError = exports.isILoggingError = exports.extractLogSafeErrorProperties = void 0;
 const uuid_1 = require("uuid");
 const fluidErrorBase_1 = require("./fluidErrorBase");
-/** @returns true if value is an object but neither null nor an array */
+/**
+ * Determines if the provided value is an object but neither null nor an array.
+ */
 const isRegularObject = (value) => {
     return value !== null && !Array.isArray(value) && typeof value === "object";
 };
-/** Inspect the given error for common "safe" props and return them */
+/**
+ * Inspect the given error for common "safe" props and return them.
+ *
+ * @internal
+ */
 function extractLogSafeErrorProperties(error, sanitizeStack) {
     const removeMessageFromStack = (stack, errorName) => {
         if (!sanitizeStack) {
@@ -24,7 +30,7 @@ function extractLogSafeErrorProperties(error, sanitizeStack) {
         }
         return stackFrames.join("\n");
     };
-    const message = (typeof (error === null || error === void 0 ? void 0 : error.message) === "string")
+    const message = typeof error?.message === "string"
         ? error.message
         : String(error);
     const safeProps = {
@@ -36,17 +42,23 @@ function extractLogSafeErrorProperties(error, sanitizeStack) {
             safeProps.errorType = errorType;
         }
         if (typeof stack === "string") {
-            const errorName = (typeof name === "string") ? name : undefined;
+            const errorName = typeof name === "string" ? name : undefined;
             safeProps.stack = removeMessageFromStack(stack, errorName);
         }
     }
     return safeProps;
 }
 exports.extractLogSafeErrorProperties = extractLogSafeErrorProperties;
-/** type guard for ILoggingError interface */
-const isILoggingError = (x) => typeof (x === null || x === void 0 ? void 0 : x.getTelemetryProperties) === "function";
+/**
+ * Type-guard for {@link @fluidframework/core-interfaces#ILoggingError}.
+ *
+ * @internal
+ */
+const isILoggingError = (x) => typeof x?.getTelemetryProperties === "function";
 exports.isILoggingError = isILoggingError;
-/** Copy props from source onto target, but do not overwrite an existing prop that matches */
+/**
+ * Copy props from source onto target, but do not overwrite an existing prop that matches
+ */
 function copyProps(target, source) {
     for (const key of Object.keys(source)) {
         if (target[key] === undefined) {
@@ -54,8 +66,11 @@ function copyProps(target, source) {
         }
     }
 }
-/** For backwards compatibility with pre-errorInstanceId valid errors */
+/**
+ * For backwards compatibility with pre-errorInstanceId valid errors
+ */
 function patchLegacyError(legacyError) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
     const patchMe = legacyError;
     if (patchMe.errorInstanceId === undefined) {
         patchMe.errorInstanceId = (0, uuid_1.v4)();
@@ -66,21 +81,22 @@ function patchLegacyError(legacyError) {
  * @returns A valid Fluid Error with any provided annotations applied
  * @param error - The error to normalize
  * @param annotations - Annotations to apply to the normalized error
+ *
+ * @internal
  */
 function normalizeError(error, annotations = {}) {
-    var _a;
     // Back-compat, while IFluidErrorBase is rolled out
     if ((0, fluidErrorBase_1.isValidLegacyError)(error)) {
         patchLegacyError(error);
     }
     if ((0, fluidErrorBase_1.isFluidError)(error)) {
         // We can simply add the telemetry props to the error and return it
-        error.addTelemetryProperties((_a = annotations.props) !== null && _a !== void 0 ? _a : {});
+        error.addTelemetryProperties(annotations.props ?? {});
         return error;
     }
     // We have to construct a new Fluid Error, copying safe properties over
     const { message, stack } = extractLogSafeErrorProperties(error, false /* sanitizeStack */);
-    const fluidError = new NormalizedExternalError({
+    const fluidError = new NormalizedLoggingError({
         message,
         stack,
     });
@@ -88,15 +104,31 @@ function normalizeError(error, annotations = {}) {
     // Anywhere they are set should be on a valid Fluid Error that would have been returned above,
     // but we can't prove it with the types, so adding this defensive measure.
     if (typeof error === "object" && error !== null) {
-        const { canRetry, retryAfterSeconds } = error;
-        Object.assign(normalizeError, { canRetry, retryAfterSeconds });
+        const maybeHasRetry = error;
+        let retryProps;
+        if ("canRetry" in error) {
+            retryProps ?? (retryProps = {});
+            retryProps.canRetry = maybeHasRetry.canRetry;
+        }
+        if ("retryAfterSeconds" in error) {
+            retryProps ?? (retryProps = {});
+            retryProps.retryAfterSeconds = maybeHasRetry.retryAfterSeconds;
+        }
+        if (retryProps !== undefined) {
+            Object.assign(fluidError, retryProps);
+        }
     }
-    if (typeof (error) !== "object") {
+    if (typeof error !== "object") {
         // This is only interesting for non-objects
-        fluidError.addTelemetryProperties({ typeofError: typeof (error) });
+        fluidError.addTelemetryProperties({ typeofError: typeof error });
     }
-    const originalErrorTelemetryProps = (0, exports.isILoggingError)(error) ? error.getTelemetryProperties() : {};
-    fluidError.addTelemetryProperties(Object.assign(Object.assign(Object.assign({}, originalErrorTelemetryProps), annotations.props), { untrustedOrigin: 1 }));
+    const errorTelemetryProps = LoggingError.typeCheck(error)
+        ? error.getTelemetryProperties()
+        : { untrustedOrigin: 1 }; // This will let us filter errors that did not originate from our own codebase
+    fluidError.addTelemetryProperties({
+        ...errorTelemetryProps,
+        ...annotations.props,
+    });
     return fluidError;
 }
 exports.normalizeError = normalizeError;
@@ -109,11 +141,13 @@ let stackPopulatedOnCreation;
  * For such cases it's better to not read stack property right away, but rather delay it until / if it's needed
  * Some browsers will populate stack right away, others require throwing Error, so we do auto-detection on the fly.
  * @returns Error object that has stack populated.
+ *
+ * @internal
  */
 function generateErrorWithStack() {
     const err = new Error("<<generated stack>>");
     if (stackPopulatedOnCreation === undefined) {
-        stackPopulatedOnCreation = (err.stack !== undefined);
+        stackPopulatedOnCreation = err.stack !== undefined;
     }
     if (stackPopulatedOnCreation) {
         return err;
@@ -121,11 +155,17 @@ function generateErrorWithStack() {
     try {
         throw err;
     }
-    catch (e) {
-        return e;
+    catch (error) {
+        return error;
     }
 }
 exports.generateErrorWithStack = generateErrorWithStack;
+/**
+ * Generate a stack at this callsite as if an error were thrown from here.
+ * @returns the callstack (does not throw)
+ *
+ * @internal
+ */
 function generateStack() {
     return generateErrorWithStack().stack;
 }
@@ -136,9 +176,11 @@ exports.generateStack = generateStack;
  * @param innerError - An error from untrusted/unknown origins
  * @param newErrorFn - callback that will create a new error given the original error's message
  * @returns A new error object "wrapping" the given error
+ *
+ * @internal
  */
 function wrapError(innerError, newErrorFn) {
-    const { message, stack, } = extractLogSafeErrorProperties(innerError, false /* sanitizeStack */);
+    const { message, stack } = extractLogSafeErrorProperties(innerError, false /* sanitizeStack */);
     const newError = newErrorFn(message);
     if (stack !== undefined) {
         overwriteStack(newError, stack);
@@ -161,7 +203,13 @@ function wrapError(innerError, newErrorFn) {
     return newError;
 }
 exports.wrapError = wrapError;
-/** The same as wrapError, but also logs the innerError, including the wrapping error's instance id */
+/**
+ * The same as wrapError, but also logs the innerError, including the wrapping error's instance ID.
+ *
+ * @typeParam T - The kind of wrapper error to create.
+ *
+ * @internal
+ */
 function wrapErrorAndLog(innerError, newErrorFn, logger) {
     const newError = wrapError(innerError, newErrorFn);
     // This will match innerError.errorInstanceId if present (see wrapError)
@@ -176,32 +224,84 @@ function wrapErrorAndLog(innerError, newErrorFn, logger) {
     return newError;
 }
 exports.wrapErrorAndLog = wrapErrorAndLog;
+/**
+ * Attempts to overwrite the error's stack
+ *
+ * There have been reports of certain JS environments where overwriting stack will throw.
+ * If that happens, this adds the given stack as the telemetry property "stack2"
+ *
+ * @internal
+ */
 function overwriteStack(error, stack) {
-    // supposedly setting stack on an Error can throw.
     try {
         Object.assign(error, { stack });
     }
-    catch (errorSettingStack) {
+    catch {
         error.addTelemetryProperties({ stack2: stack });
     }
 }
+exports.overwriteStack = overwriteStack;
 /**
  * True for any error object that is an (optionally normalized) external error
- * False for any error we created and raised within the FF codebase, or wrapped in a well-known error type
+ * False for any error we created and raised within the FF codebase via LoggingError base class,
+ * or wrapped in a well-known error type
+ *
+ * @internal
  */
-function isExternalError(e) {
-    return !(0, fluidErrorBase_1.isValidLegacyError)(e) ||
-        (e.getTelemetryProperties().untrustedOrigin === 1 &&
-            e.errorType === NormalizedExternalError.normalizedErrorType);
+function isExternalError(error) {
+    // LoggingErrors are an internal FF error type. However, an external error can be converted
+    // into a LoggingError if it is normalized. In this case we must use the untrustedOrigin flag to
+    // determine whether the original error was infact external.
+    if (LoggingError.typeCheck(error)) {
+        if (error.errorType === exports.NORMALIZED_ERROR_TYPE) {
+            return error.getTelemetryProperties().untrustedOrigin === 1;
+        }
+        return false;
+    }
+    return !(0, fluidErrorBase_1.isValidLegacyError)(error);
 }
 exports.isExternalError = isExternalError;
 /**
- * Type guard to identify if a particular value (loosely) appears to be a tagged telemetry property
+ * Type guard to identify if a particular telemetry property appears to be a
+ * {@link @fluidframework/core-interfaces#Tagged} telemetry property.
+ *
+ * @internal
  */
 function isTaggedTelemetryPropertyValue(x) {
-    return (typeof (x === null || x === void 0 ? void 0 : x.value) !== "object" && typeof (x === null || x === void 0 ? void 0 : x.tag) === "string");
+    return typeof x?.tag === "string";
 }
 exports.isTaggedTelemetryPropertyValue = isTaggedTelemetryPropertyValue;
+/**
+ * Filter serializable telemetry properties
+ * @param x - Any telemetry prop
+ * @returns As-is if x is primitive. returns stringified if x is an array of primitive.
+ * otherwise returns null since this is what we support at the moment.
+ */
+function filterValidTelemetryProps(x, key) {
+    if (Array.isArray(x) && x.every((val) => isTelemetryEventPropertyValue(val))) {
+        return JSON.stringify(x);
+    }
+    if (isTelemetryEventPropertyValue(x)) {
+        return x;
+    }
+    // We don't support logging arbitrary objects
+    console.error(`UnSupported Format of Logging Error Property for key ${key}:`, x);
+    return "REDACTED (arbitrary object)";
+}
+// checking type of x, returns false if x is null
+function isTelemetryEventPropertyValue(x) {
+    switch (typeof x) {
+        case "string":
+        case "number":
+        case "boolean":
+        case "undefined": {
+            return true;
+        }
+        default: {
+            return false;
+        }
+    }
+}
 /**
  * Walk an object's enumerable properties to find those fit for telemetry.
  */
@@ -212,24 +312,13 @@ function getValidTelemetryProps(obj, keysToOmit) {
             continue;
         }
         const val = obj[key];
-        switch (typeof val) {
-            case "string":
-            case "number":
-            case "boolean":
-            case "undefined":
-                props[key] = val;
-                break;
-            default: {
-                if (isTaggedTelemetryPropertyValue(val)) {
-                    props[key] = val;
-                }
-                else {
-                    // We don't support logging arbitrary objects
-                    props[key] = "REDACTED (arbitrary object)";
-                }
-                break;
+        // ensure only valid props get logged, since props of logging error could be in any shape
+        props[key] = isTaggedTelemetryPropertyValue(val)
+            ? {
+                value: filterValidTelemetryProps(val.value, key),
+                tag: val.tag,
             }
-        }
+            : filterValidTelemetryProps(val, key);
     }
     return props;
 }
@@ -239,7 +328,11 @@ function getValidTelemetryProps(obj, keysToOmit) {
  * Avoids runtime errors with circular references.
  * Not ideal, as will cut values that are not necessarily circular references.
  * Could be improved by implementing Node's util.inspect() for browser (minus all the coloring code)
-*/
+ *
+ * @internal
+ */
+// TODO: Use `unknown` instead (API breaking change)
+/* eslint-disable @typescript-eslint/no-explicit-any */
 const getCircularReplacer = () => {
     const seen = new WeakSet();
     return (key, value) => {
@@ -253,14 +346,23 @@ const getCircularReplacer = () => {
     };
 };
 exports.getCircularReplacer = getCircularReplacer;
+/* eslint-enable @typescript-eslint/no-explicit-any */
 /**
  * Base class for "trusted" errors we create, whose properties can generally be logged to telemetry safely.
  * All properties set on the object, or passed in (via the constructor or addTelemetryProperties),
  * will be logged in accordance with their tag, if present.
  *
  * PLEASE take care to avoid setting sensitive data on this object without proper tagging!
+ *
+ * @internal
  */
 class LoggingError extends Error {
+    get errorInstanceId() {
+        return this._errorInstanceId;
+    }
+    overwriteErrorInstanceId(id) {
+        this._errorInstanceId = id;
+    }
     /**
      * Create a new LoggingError
      * @param message - Error message to use for Error base class
@@ -271,8 +373,11 @@ class LoggingError extends Error {
         super(message);
         this.omitPropsFromLogging = omitPropsFromLogging;
         this._errorInstanceId = (0, uuid_1.v4)();
-        /** Back-compat to appease isFluidError typeguard in old code that may handle this error */
+        /**
+         * Backwards compatibility to appease {@link isFluidError} in old code that may handle this error.
+         */
         // @ts-expect-error - This field shouldn't be referenced in the current version, but needs to exist at runtime.
+        // eslint-disable-next-line @typescript-eslint/prefer-as-const
         this.fluidErrorCode = "-";
         // Don't log this list itself, or the private _errorInstanceId
         omitPropsFromLogging.add("omitPropsFromLogging");
@@ -281,8 +386,19 @@ class LoggingError extends Error {
             this.addTelemetryProperties(props);
         }
     }
-    get errorInstanceId() { return this._errorInstanceId; }
-    overwriteErrorInstanceId(id) { this._errorInstanceId = id; }
+    /**
+     * Determines if a given object is an instance of a LoggingError
+     * @param object - any object
+     * @returns true if the object is an instance of a LoggingError, false if not.
+     */
+    static typeCheck(object) {
+        if (typeof object === "object" && object !== null) {
+            return (typeof object.addTelemetryProperties === "function" &&
+                typeof object.getTelemetryProperties === "function" &&
+                typeof object.errorInstanceId === "string");
+        }
+        return false;
+    }
     /**
      * Add additional properties to be logged
      */
@@ -295,21 +411,35 @@ class LoggingError extends Error {
     getTelemetryProperties() {
         const taggableProps = getValidTelemetryProps(this, this.omitPropsFromLogging);
         // Include non-enumerable props that are not returned by getValidTelemetryProps
-        return Object.assign(Object.assign({}, taggableProps), { stack: this.stack, message: this.message, errorInstanceId: this._errorInstanceId });
+        return {
+            ...taggableProps,
+            stack: this.stack,
+            message: this.message,
+            errorInstanceId: this._errorInstanceId,
+        };
     }
 }
 exports.LoggingError = LoggingError;
-/** The Error class used when normalizing an external error */
-class NormalizedExternalError extends LoggingError {
+/**
+ * The Error class used when normalizing an external error
+ *
+ * @internal
+ */
+exports.NORMALIZED_ERROR_TYPE = "genericError";
+/**
+ * Subclass of LoggingError returned by normalizeError
+ *
+ * @internal
+ */
+class NormalizedLoggingError extends LoggingError {
     constructor(errorProps) {
         super(errorProps.message);
-        this.errorType = NormalizedExternalError.normalizedErrorType;
+        // errorType "genericError" is used as a default value throughout the code.
+        // Note that this matches ContainerErrorType/DriverErrorType's genericError
+        this.errorType = exports.NORMALIZED_ERROR_TYPE;
         if (errorProps.stack !== undefined) {
             overwriteStack(this, errorProps.stack);
         }
     }
 }
-// errorType "genericError" is used as a default value throughout the code.
-// Note that this matches ContainerErrorType/DriverErrorType's genericError
-NormalizedExternalError.normalizedErrorType = "genericError";
 //# sourceMappingURL=errorLogging.js.map