@fluidframework/telemetry-utils 0.57.1 → 0.58.0-55561

package/src/errorLogging.ts

@@ -78,16 +78,20 @@ export interface IFluidErrorAnnotations {
     props?: ITelemetryProperties;
 }
 
-/** For backwards compatibility with pre-fluidErrorCode valid errors */
-function patchWithErrorCode(
-    legacyError: Omit<IFluidErrorBase, "fluidErrorCode">,
+/** For backwards compatibility with pre-errorInstanceId valid errors */
+function patchLegacyError(
+    legacyError: Omit<IFluidErrorBase, "errorInstanceId">,
 ): asserts legacyError is IFluidErrorBase {
-    const patchMe: { -readonly [P in "fluidErrorCode"]?: IFluidErrorBase[P] } = legacyError as any;
-    if (patchMe.fluidErrorCode === undefined) {
-        patchMe.fluidErrorCode = "<error predates fluidErrorCode>";
+    const patchMe: { -readonly [P in "errorInstanceId"]?: IFluidErrorBase[P] } = legacyError as any;
+    if (patchMe.errorInstanceId === undefined) {
+        patchMe.errorInstanceId = uuid();
     }
 }
 
+// errorType "genericError" is used as a default value throughout the code.
+// Note that this matches ContainerErrorType/DriverErrorType's genericError
+const defaultErrorTypeForNormalize = "genericError";
+
 /**
  * Normalize the given error yielding a valid Fluid Error
  * @returns A valid Fluid Error with any provided annotations applied
@@ -100,7 +104,7 @@ export function normalizeError(
 ): IFluidErrorBase {
     // Back-compat, while IFluidErrorBase is rolled out
     if (isValidLegacyError(error)) {
-        patchWithErrorCode(error);
+        patchLegacyError(error);
     }
 
     if (isFluidError(error)) {
@@ -112,8 +116,7 @@ export function normalizeError(
     // We have to construct a new Fluid Error, copying safe properties over
     const { message, stack } = extractLogSafeErrorProperties(error, false /* sanitizeStack */);
     const fluidError: IFluidErrorBase = new SimpleFluidError({
-        errorType: "genericError", // Match Container/Driver generic error type
-        fluidErrorCode: "",
+        errorType: defaultErrorTypeForNormalize,
         message,
         stack,
     });
@@ -171,7 +174,7 @@ export function generateStack(): string | undefined {
  * @param newErrorFn - callback that will create a new error given the original error's message
  * @returns A new error object "wrapping" the given error
  */
- export function wrapError<T extends IFluidErrorBase>(
+export function wrapError<T extends LoggingError>(
     innerError: unknown,
     newErrorFn: (message: string) => T,
 ): T {
@@ -186,7 +189,16 @@ export function generateStack(): string | undefined {
         overwriteStack(newError, stack);
     }
 
+    // Mark external errors with untrustedOrigin flag
+    if (originatedAsExternalError(innerError)) {
+        newError.addTelemetryProperties({ untrustedOrigin: 1 });
+    }
+
+    // Reuse errorInstanceId
     if (hasErrorInstanceId(innerError)) {
+        newError.overwriteErrorInstanceId(innerError.errorInstanceId);
+
+        // For "back-compat" in the logs
         newError.addTelemetryProperties({ innerErrorInstanceId: innerError.errorInstanceId });
     }
 
@@ -194,25 +206,29 @@ export function generateStack(): string | undefined {
 }
 
 /** The same as wrapError, but also logs the innerError, including the wrapping error's instance id */
-export function wrapErrorAndLog<T extends IFluidErrorBase>(
+export function wrapErrorAndLog<T extends LoggingError>(
     innerError: unknown,
     newErrorFn: (message: string) => T,
     logger: ITelemetryLogger,
 ) {
     const newError = wrapError(innerError, newErrorFn);
-    const wrappedByErrorInstanceId = hasErrorInstanceId(newError)
-        ? newError.errorInstanceId
-        : undefined;
+
+    // This will match innerError.errorInstanceId if present (see wrapError)
+    const errorInstanceId = newError.errorInstanceId;
+
+    // For "back-compat" in the logs
+    const wrappedByErrorInstanceId = errorInstanceId;
 
     logger.sendTelemetryEvent({
         eventName: "WrapError",
+        errorInstanceId,
         wrappedByErrorInstanceId,
     }, innerError);
 
     return newError;
 }
 
-function overwriteStack(error: IFluidErrorBase, stack: string) {
+function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string) {
     // supposedly setting stack on an Error can throw.
     try {
         Object.assign(error, { stack });
@@ -221,6 +237,24 @@ function overwriteStack(error: IFluidErrorBase, stack: string) {
     }
 }
 
+/**
+ * True for any error object that is either external itself or is a wrapped/normalized external error
+ * False for any error we created and raised within the FF codebase.
+ */
+export function originatedAsExternalError(e: any): boolean {
+    return !isValidLegacyError(e) || (e.getTelemetryProperties().untrustedOrigin === 1);
+}
+
+/**
+ * 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
+ */
+export function isExternalError(e: any): boolean {
+    return !isValidLegacyError(e) ||
+        (e.getTelemetryProperties().untrustedOrigin === 1 &&
+         e.errorType === defaultErrorTypeForNormalize);
+}
+
 /**
  * Type guard to identify if a particular value (loosely) appears to be a tagged telemetry property
  */
@@ -287,7 +321,13 @@ export const getCircularReplacer = () => {
  * PLEASE take care to avoid setting sensitive data on this object without proper tagging!
  */
 export class LoggingError extends Error implements ILoggingError, Pick<IFluidErrorBase, "errorInstanceId"> {
-    readonly errorInstanceId = uuid();
+    private _errorInstanceId = uuid();
+    get errorInstanceId() { return this._errorInstanceId; }
+    overwriteErrorInstanceId(id: string) { this._errorInstanceId = id; }
+
+    /** Back-compat to appease isFluidError typeguard 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.
+    private fluidErrorCode: "-" = "-";
 
     /**
      * Create a new LoggingError
@@ -302,8 +342,9 @@ export class LoggingError extends Error implements ILoggingError, Pick<IFluidErr
     ) {
         super(message);
 
-        // Don't log this list itself either
+        // Don't log this list itself, or the private _errorInstanceId
         omitPropsFromLogging.add("omitPropsFromLogging");
+        omitPropsFromLogging.add("_errorInstanceId");
 
         if (props) {
             this.addTelemetryProperties(props);
@@ -322,11 +363,12 @@ export class LoggingError extends Error implements ILoggingError, Pick<IFluidErr
      */
     public getTelemetryProperties(): ITelemetryProperties {
         const taggableProps = getValidTelemetryProps(this, this.omitPropsFromLogging);
-        // Include non-enumerable props inherited from Error that are not returned by getValidTelemetryProps
+        // Include non-enumerable props that are not returned by getValidTelemetryProps
         return {
             ...taggableProps,
             stack: this.stack,
             message: this.message,
+            errorInstanceId: this._errorInstanceId,
         };
     }
 }
@@ -334,18 +376,16 @@ export class LoggingError extends Error implements ILoggingError, Pick<IFluidErr
 /** Simple implementation of IFluidErrorBase, extending LoggingError */
 class SimpleFluidError extends LoggingError implements IFluidErrorBase {
     readonly errorType: string;
-    readonly fluidErrorCode: string;
 
     constructor(
-        errorProps: Omit<IFluidErrorBase,
-            | "getTelemetryProperties"
-            | "addTelemetryProperties"
-            | "errorInstanceId"
-            | "name">,
+        errorProps: Pick<IFluidErrorBase,
+            | "message"
+            | "stack"
+            | "errorType"
+        >,
     ) {
         super(errorProps.message);
         this.errorType = errorProps.errorType;
-        this.fluidErrorCode = errorProps.fluidErrorCode;
         if (errorProps.stack !== undefined) {
             overwriteStack(this, errorProps.stack);
         }

package/src/fluidErrorBase.ts

@@ -7,7 +7,7 @@ import { ITelemetryProperties } from "@fluidframework/common-definitions";
 
 /**
  * All normalized errors flowing through the Fluid Framework adhere to this readonly interface.
- * It features errorType, fluidErrorCode, and message strings, plus Error's members as optional
+ * It features errorType and errorInstanceId on top of Error's members as readonly,
  * and a getter/setter for telemetry props to be included when the error is logged.
  */
 export interface IFluidErrorBase extends Error {
@@ -15,12 +15,10 @@ export interface IFluidErrorBase extends Error {
     readonly errorType: string;
 
     /**
-     * Indicates a point in code where this error originated.
-     * Avoid crafting these via string format or otherwise including variable data, so they're easy to find the code.
+     * Error's message property, made readonly.
+     * Be specific, but also take care when including variable data to consider suitability for aggregation in telemetry
+     * Also avoid including any data that jeopardizes the user's privacy.  Add a tagged telemetry property instead.
      */
-    readonly fluidErrorCode: string;
-
-    /** The free-form error message */
     readonly message: string;
 
     /** Error's stack property, made readonly */
@@ -52,14 +50,13 @@ export const hasErrorInstanceId = (x: any): x is { errorInstanceId: string } =>
 /** type guard for IFluidErrorBase interface */
 export function isFluidError(e: any): e is IFluidErrorBase {
     return typeof e?.errorType === "string" &&
-        typeof e?.fluidErrorCode === "string" &&
         typeof e?.message === "string" &&
-        typeof e?.errorInstanceId === "string" &&
+        hasErrorInstanceId(e) &&
         hasTelemetryPropFunctions(e);
 }
 
 /** type guard for old standard of valid/known errors */
-export function isValidLegacyError(e: any): e is Omit<IFluidErrorBase, "fluidErrorCode"> {
+export function isValidLegacyError(e: any): e is Omit<IFluidErrorBase, "errorInstanceId"> {
     return typeof e?.errorType === "string" &&
         typeof e?.message === "string" &&
         hasTelemetryPropFunctions(e);

package/src/mockLogger.ts

@@ -4,7 +4,6 @@
  */
 
 import { ITelemetryLogger, ITelemetryBaseEvent } from "@fluidframework/common-definitions";
-import { assert } from "@fluidframework/common-utils";
 import { TelemetryLogger } from "./logger";
 
 /**
@@ -35,14 +34,16 @@ export class MockLogger extends TelemetryLogger implements ITelemetryLogger {
     }
 
     /** Asserts that matchEvents is true, and prints the actual/expected output if not */
-    assertMatch(expectedEvents: Omit<ITelemetryBaseEvent, "category">[]) {
-        // const actualEvents = this.events;
-        assert(this.matchEvents(expectedEvents), 0x2ba /* `
-            expected:
-            ${JSON.stringify(expectedEvents)}
+    assertMatch(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string) {
+        const actualEvents = this.events;
+        if (!this.matchEvents(expectedEvents)) {
+            throw new Error(`${message}
+expected:
+${JSON.stringify(expectedEvents)}
 
-            actual:
-            ${JSON.stringify(actualEvents)}` */);
+actual:
+${JSON.stringify(actualEvents)}`);
+        }
     }
 
     /**
@@ -59,15 +60,16 @@ export class MockLogger extends TelemetryLogger implements ITelemetryLogger {
     }
 
     /** Asserts that matchAnyEvent is true, and prints the actual/expected output if not */
-    assertMatchAny(expectedEvents: Omit<ITelemetryBaseEvent, "category">[]) {
-        // const actualEvents = this.events;
+    assertMatchAny(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string) {
+        const actualEvents = this.events;
+        if (!this.matchAnyEvent(expectedEvents)) {
+            throw new Error(`${message}
+expected:
+${JSON.stringify(expectedEvents)}
 
-        assert(this.matchAnyEvent(expectedEvents), 0x2bb /* `
-            expected:
-            ${JSON.stringify(expectedEvents)}
-
-            actual:
-            ${JSON.stringify(actualEvents)}` */);
+actual:
+${JSON.stringify(actualEvents)}`);
+            }
     }
 
     private getMatchedEventsCount(expectedEvents: Omit<ITelemetryBaseEvent, "category">[]): number {

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/telemetry-utils";
-export const pkgVersion = "0.57.1";
+export const pkgVersion = "0.58.0-55561";