@fluidframework/telemetry-utils 0.52.1 → 0.54.0

package/src/config.ts

@@ -0,0 +1,265 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ITelemetryBaseLogger, ITelemetryLogger } from "@fluidframework/common-definitions";
+import { Lazy } from "@fluidframework/common-utils";
+
+export type ConfigTypes = string | number | boolean | number[] | string[] | boolean[] | undefined;
+
+/**
+ * Base interface for providing configurations to enable/disable/control features
+ */
+export interface IConfigProviderBase {
+    getRawConfig(name: string): ConfigTypes;
+}
+
+/**
+ * Explicitly typed interface for reading configurations
+ */
+ export interface IConfigProvider extends IConfigProviderBase {
+    getBoolean(name: string): boolean | undefined;
+    getNumber(name: string): number | undefined;
+    getString(name: string): string | undefined;
+    getBooleanArray(name: string): boolean[] | undefined;
+    getNumberArray(name: string): number[] | undefined;
+    getStringArray(name: string): string[] | undefined;
+ }
+/**
+ * Creates a base configuration provider based on `sessionStorage`
+ *
+ * @returns A lazy initialized base configuration provider with `sessionStorage` as the underlying config store
+ */
+export const sessionStorageConfigProvider =
+    new Lazy<IConfigProviderBase>(() => inMemoryConfigProvider(safeSessionStorage()));
+
+const NullConfigProvider: IConfigProviderBase = {
+    getRawConfig: () => undefined,
+};
+
+/**
+ * Creates a base configuration provider based on the supplied `Storage` instance
+ *
+ * @param storage - instance of `Storage` to be used as storage media for the config
+ * @returns A base configuration provider with
+ * the supplied `Storage` instance as the underlying config store
+ */
+export const inMemoryConfigProvider =
+    (storage: Storage | undefined): IConfigProviderBase => {
+    if (storage !== undefined && storage !== null) {
+        return new CachedConfigProvider({
+            getRawConfig: (name: string) => {
+                try {
+                    return stronglyTypedParse(storage.getItem(name) ?? undefined)?.raw;
+                } catch { }
+                return undefined;
+            },
+        });
+    }
+    return NullConfigProvider;
+};
+
+interface ConfigTypeStringToType {
+    number: number;
+    string: string;
+    boolean: boolean;
+    ["number[]"]: number[];
+    ["string[]"]: string[];
+    ["boolean[]"]: boolean[];
+}
+
+type PrimitiveTypeStrings = "number" | "string" | "boolean";
+
+function isPrimitiveType(type: string): type is PrimitiveTypeStrings {
+    switch (type) {
+        case "boolean":
+        case "number":
+        case "string":
+            return true;
+        default:
+            return false;
+    }
+}
+
+interface StronglyTypedValue extends Partial<ConfigTypeStringToType> {
+    raw: ConfigTypes;
+}
+/**
+ * Takes any supported config type, and returns the value with a strong type. If the type of
+ * the config is not a supported type undefined will be returned.
+ * The user of this function should cache the result to avoid duplicated work.
+ *
+ * Strings will be attempted to be parsed and coerced into a strong config type.
+ * if it is not possible to parsed and coerce a string to a strong config type the original string
+ * will be return with a string type for the consumer to handle further if necessary.
+ */
+function stronglyTypedParse(input: ConfigTypes): StronglyTypedValue | undefined {
+    let output: ConfigTypes = input;
+    let defaultReturn: Pick<StronglyTypedValue,"raw" | "string"> | undefined;
+    // we do special handling for strings to try and coerce
+    // them into a config type if we can. This makes it easy
+    // for config sources like sessionStorage which only
+    // holds strings
+    if (typeof input === "string") {
+        try {
+            output = JSON.parse(input);
+            // we succeeded in parsing, but we don't support parsing
+            // for any object as we can't do it type safely
+            // so in this case, the default return will be string
+            // rather than undefined, and the consumer
+            // can parse, as we don't want to provide
+            // a false sense of security by just
+            // casting.
+            defaultReturn = { raw: input, string: input };
+        } catch { }
+    }
+
+    if (output === undefined) {
+        return defaultReturn;
+    }
+
+    const outputType = typeof output;
+    if (isPrimitiveType(outputType)) {
+        return { ...defaultReturn, raw: input, [outputType]: output };
+    }
+
+    if (Array.isArray(output)) {
+        const firstType = typeof output[0];
+        // ensure the first elements is a primitive type
+        if (!isPrimitiveType(firstType)) {
+            return defaultReturn;
+        }
+        // ensue all the elements types are homogeneous
+        // aka they all have the same type as the first
+        for (const v of output) {
+            if (typeof v !== firstType) {
+                return defaultReturn;
+            }
+        }
+        return { ...defaultReturn, raw: input, [`${firstType}[]`]: output };
+    }
+
+    return defaultReturn;
+}
+
+/** Referencing the `sessionStorage` variable can throw in some environments such as Node */
+const safeSessionStorage = (): Storage | undefined => {
+    try {
+        return sessionStorage !== null ? sessionStorage : undefined;
+    } catch { return undefined; }
+};
+
+/**
+ * Implementation of {@link IConfigProvider} which contains nested {@link IConfigProviderBase} instances
+ */
+export class CachedConfigProvider implements IConfigProvider {
+    private readonly configCache = new Map<string, StronglyTypedValue>();
+    private readonly orderedBaseProviders: (IConfigProviderBase | undefined)[];
+
+    constructor(
+        ... orderedBaseProviders: (IConfigProviderBase | undefined)[]
+    ) {
+        this.orderedBaseProviders = [];
+        const knownProviders = new Set<IConfigProviderBase>();
+        const candidateProviders = [...orderedBaseProviders];
+        while (candidateProviders.length > 0) {
+            const baseProvider = candidateProviders.shift()!;
+            if (baseProvider !== undefined
+                && isConfigProviderBase(baseProvider)
+                && !knownProviders.has(baseProvider)
+            ) {
+                knownProviders.add(baseProvider);
+                if (baseProvider instanceof CachedConfigProvider) {
+                    candidateProviders.push(...baseProvider.orderedBaseProviders);
+                } else {
+                    this.orderedBaseProviders.push(baseProvider);
+                }
+            }
+        }
+    }
+    getBoolean(name: string): boolean | undefined {
+        return this.getCacheEntry(name)?.boolean;
+    }
+    getNumber(name: string): number | undefined {
+        return this.getCacheEntry(name)?.number;
+    }
+    getString(name: string): string | undefined {
+        return this.getCacheEntry(name)?.string;
+    }
+    getBooleanArray(name: string): boolean[] | undefined {
+        return this.getCacheEntry(name)?.["boolean[]"];
+    }
+    getNumberArray(name: string): number[] | undefined {
+        return this.getCacheEntry(name)?.["number[]"];
+    }
+    getStringArray(name: string): string[] | undefined {
+        return this.getCacheEntry(name)?.["string[]"];
+    }
+
+    getRawConfig(name: string): ConfigTypes {
+        return this.getCacheEntry(name)?.raw;
+    }
+
+    private getCacheEntry(name: string): StronglyTypedValue | undefined {
+        if (!this.configCache.has(name)) {
+            for (const provider of this.orderedBaseProviders) {
+                const parsed = stronglyTypedParse(provider?.getRawConfig(name));
+                if (parsed !== undefined) {
+                    this.configCache.set(name, parsed);
+                    return parsed;
+                }
+            }
+            // configs are immutable, if the first lookup returned no results, all lookups should
+            this.configCache.set(name, { raw: undefined });
+        }
+        return this.configCache.get(name);
+    }
+}
+
+/**
+ * A type containing both a telemetry logger and a configuration provider
+ */
+export interface MonitoringContext<
+    L extends ITelemetryBaseLogger = ITelemetryLogger
+> {
+    config: IConfigProvider;
+    logger: L;
+}
+
+export function loggerIsMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLogger>(
+    obj: L): obj is L & MonitoringContext<L> {
+    const maybeConfig = obj as Partial<MonitoringContext<L>> | undefined;
+    return isConfigProviderBase(maybeConfig?.config) && maybeConfig?.logger !== undefined;
+}
+
+export function loggerToMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLogger>(
+    logger: L): MonitoringContext<L> {
+    if(loggerIsMonitoringContext<L>(logger)) {
+        return logger;
+    }
+    return mixinMonitoringContext<L>(logger, sessionStorageConfigProvider.value);
+}
+
+export function mixinMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLogger>(
+    logger: L, ... configs: (IConfigProviderBase | undefined)[]) {
+    if (loggerIsMonitoringContext<L>(logger)) {
+        throw new Error("Logger is already a monitoring context");
+    }
+    /**
+     * this is the tricky bit we use for now to smuggle monitoring context around.
+     * To the logger we mixin both config and  itself, so mc.logger === logger as it is self-referential.
+     * We then expose it as a Monitoring context, so via types we hide the outer logger methods.
+     * To layers that expect just a logger we can pass mc.logger, but this is still a MonitoringContext
+     * so if a deeper layer then converts that logger to a monitoring context it can find the smuggled properties
+     * of the MonitoringContext and get the config provider.
+     */
+    const mc: L & Partial<MonitoringContext<L>> = logger;
+    mc.config = new CachedConfigProvider(...configs);
+    mc.logger = logger;
+    return mc as MonitoringContext<L>;
+}
+
+function isConfigProviderBase(obj: unknown): obj is IConfigProviderBase {
+    const maybeConfig = obj as Partial<IConfigProviderBase> | undefined;
+    return typeof (maybeConfig?.getRawConfig) === "function";
+}

package/src/errorLogging.ts

@@ -78,42 +78,6 @@ export interface IFluidErrorAnnotations {
     props?: ITelemetryProperties;
 }
 
-/** Simplest possible implementation of IFluidErrorBase */
-class SimpleFluidError implements IFluidErrorBase {
-    private readonly telemetryProps: ITelemetryProperties = {};
-
-    readonly errorType: string;
-    readonly fluidErrorCode: string;
-    readonly message: string;
-    readonly stack?: string;
-    readonly name: string = "Error";
-    readonly errorInstanceId: string;
-
-    constructor(
-        errorProps: Omit<IFluidErrorBase,
-            | "getTelemetryProperties"
-            | "addTelemetryProperties"
-            | "errorInstanceId"
-            | "name">,
-    ) {
-        this.errorType = errorProps.errorType;
-        this.fluidErrorCode = errorProps.fluidErrorCode;
-        this.message = errorProps.message;
-        this.stack = errorProps.stack;
-        this.errorInstanceId = uuid();
-
-        this.addTelemetryProperties(errorProps);
-    }
-
-    getTelemetryProperties(): ITelemetryProperties {
-        return this.telemetryProps;
-    }
-
-    addTelemetryProperties(props: ITelemetryProperties) {
-        copyProps(this.telemetryProps, props);
-    }
-}
-
 /** For backwards compatibility with pre-fluidErrorCode valid errors */
 function patchWithErrorCode(
     legacyError: Omit<IFluidErrorBase, "fluidErrorCode">,
@@ -151,7 +115,7 @@ export function normalizeError(
         errorType: "genericError", // Match Container/Driver generic error type
         fluidErrorCode: "",
         message,
-        stack: stack ?? generateStack(),
+        stack,
     });
 
     fluidError.addTelemetryProperties({
@@ -166,17 +130,37 @@ export function normalizeError(
     return fluidError;
 }
 
-export function generateStack(): string | undefined {
-    // Some browsers will populate stack right away, others require throwing Error
-    let stack = new Error("<<generated stack>>").stack;
-    if (!stack) {
-        try {
-            throw new Error("<<generated stack>>");
-        } catch (e) {
-            stack = e.stack;
-        }
+let stackPopulatedOnCreation: boolean | undefined;
+
+/**
+ * The purpose of this function is to provide ability to capture stack context quickly.
+ * Accessing new Error().stack is slow, and the slowest part is accessing stack property itself.
+ * There are scenarios where we generate error with stack, but error is handled in most cases and
+ * stack property is not accessed.
+ * 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.
+ */
+ export function generateErrorWithStack(): Error {
+    const err = new Error("<<generated stack>>");
+
+    if (stackPopulatedOnCreation === undefined) {
+        stackPopulatedOnCreation = (err.stack !== undefined);
     }
-    return stack;
+
+    if (stackPopulatedOnCreation) {
+        return err;
+    }
+
+    try {
+        throw err;
+    } catch (e) {
+        return e as Error;
+    }
+}
+
+export function generateStack(): string | undefined {
+    return generateErrorWithStack().stack;
 }
 
 /**
@@ -199,12 +183,7 @@ export function generateStack(): string | undefined {
     const newError = newErrorFn(message);
 
     if (stack !== undefined) {
-        // supposedly setting stack on an Error can throw.
-        try {
-            Object.assign(newError, { stack });
-        } catch (errorSettingStack) {
-            newError.addTelemetryProperties({ stack2: stack });
-        }
+        overwriteStack(newError, stack);
     }
 
     if (hasErrorInstanceId(innerError)) {
@@ -233,6 +212,15 @@ export function wrapErrorAndLog<T extends IFluidErrorBase>(
     return newError;
 }
 
+function overwriteStack(error: IFluidErrorBase, stack: string) {
+    // supposedly setting stack on an Error can throw.
+    try {
+        Object.assign(error, { stack });
+    } catch (errorSettingStack) {
+        error.addTelemetryProperties({ stack2: stack });
+    }
+}
+
 /**
  * Type guard to identify if a particular value (loosely) appears to be a tagged telemetry property
  */
@@ -322,3 +310,24 @@ 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">,
+    ) {
+        super(errorProps.message);
+        this.errorType = errorProps.errorType;
+        this.fluidErrorCode = errorProps.fluidErrorCode;
+        if (errorProps.stack !== undefined) {
+            overwriteStack(this, errorProps.stack);
+        }
+    }
+}

package/src/index.ts

@@ -11,3 +11,12 @@ export * from "./logger";
 export * from "./mockLogger";
 export * from "./thresholdCounter";
 export * from "./utils";
+export {
+    MonitoringContext,
+    IConfigProviderBase,
+    sessionStorageConfigProvider,
+    mixinMonitoringContext,
+    IConfigProvider,
+    ConfigTypes,
+    loggerToMonitoringContext,
+} from "./config";

package/src/logger.ts

@@ -16,6 +16,11 @@ import {
     TelemetryEventCategory,
 } from "@fluidframework/common-definitions";
 import { BaseTelemetryNullLogger, performance } from "@fluidframework/common-utils";
+import {
+    CachedConfigProvider,
+    loggerIsMonitoringContext,
+    mixinMonitoringContext,
+} from "./config";
 import {
     isILoggingError,
     extractLogSafeErrorProperties,
@@ -313,9 +318,17 @@ export class ChildLogger extends TelemetryLogger {
 
     private constructor(
         protected readonly baseLogger: ITelemetryBaseLogger,
-        namespace?: string,
-        properties?: ITelemetryLoggerPropertyBags) {
+        namespace: string | undefined,
+        properties: ITelemetryLoggerPropertyBags | undefined,
+    ) {
         super(namespace, properties);
+
+        // propagate the monitoring context
+        if(loggerIsMonitoringContext(baseLogger)) {
+            mixinMonitoringContext(
+                this,
+                new CachedConfigProvider(baseLogger.config));
+        }
     }
 
     /**

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/telemetry-utils";
-export const pkgVersion = "0.52.1";
+export const pkgVersion = "0.54.0";