@fluidframework/telemetry-utils 2.0.0-dev.5.3.2.178189 → 2.0.0-dev.6.4.0.191258

package/dist/logger.js

@@ -3,20 +3,10 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-var __rest = (this && this.__rest) || function (s, e) {
-    var t = {};
-    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
-        t[p] = s[p];
-    if (s != null && typeof Object.getOwnPropertySymbols === "function")
-        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
-            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
-                t[p[i]] = s[p[i]];
-        }
-    return t;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertToBasePropertyType = exports.TelemetryNullLogger = exports.BaseTelemetryNullLogger = exports.TelemetryUTLogger = exports.PerformanceEvent = exports.MultiSinkLogger = exports.ChildLogger = exports.TaggedLoggerAdapter = exports.TelemetryLogger = exports.TelemetryDataTag = void 0;
-const common_utils_1 = require("@fluidframework/common-utils");
+exports.tagCodeArtifacts = exports.tagData = exports.convertToBasePropertyType = exports.TelemetryNullLogger = exports.PerformanceEvent = exports.MultiSinkLogger = exports.createMultiSinkLogger = exports.ChildLogger = exports.createChildLogger = exports.TaggedLoggerAdapter = exports.TelemetryLogger = exports.eventNamespaceSeparator = exports.formatTick = exports.numberFromString = exports.TelemetryDataTag = void 0;
+const core_interfaces_1 = require("@fluidframework/core-interfaces");
+const client_utils_1 = require("@fluid-internal/client-utils");
 const config_1 = require("./config");
 const errorLogging_1 = require("./errorLogging");
 /**
@@ -25,11 +15,35 @@ const errorLogging_1 = require("./errorLogging");
  */
 var TelemetryDataTag;
 (function (TelemetryDataTag) {
-    /** Data containing terms or IDs from code packages that may have been dynamically loaded */
+    /**
+     * Data containing terms or IDs from code packages that may have been dynamically loaded
+     */
     TelemetryDataTag["CodeArtifact"] = "CodeArtifact";
-    /** Personal data of a variety of classifications that pertains to the user */
+    /**
+     * Personal data of a variety of classifications that pertains to the user
+     */
     TelemetryDataTag["UserData"] = "UserData";
 })(TelemetryDataTag = exports.TelemetryDataTag || (exports.TelemetryDataTag = {}));
+/**
+ * Attempts to parse number from string.
+ * If fails,returns original string.
+ * Used to make telemetry data typed (and support math operations, like comparison),
+ * in places where we do expect numbers (like contentsize/duration property in http header)
+ */
+// eslint-disable-next-line @rushstack/no-new-null
+function numberFromString(str) {
+    if (str === undefined || str === null) {
+        return undefined;
+    }
+    const num = Number(str);
+    return Number.isNaN(num) ? str : num;
+}
+exports.numberFromString = numberFromString;
+function formatTick(tick) {
+    return Math.floor(tick);
+}
+exports.formatTick = formatTick;
+exports.eventNamespaceSeparator = ":";
 /**
  * TelemetryLogger class contains various helper telemetry methods,
  * encoding in one place schemas for various types of Fluid telemetry events.
@@ -40,22 +54,6 @@ class TelemetryLogger {
         this.namespace = namespace;
         this.properties = properties;
     }
-    static formatTick(tick) {
-        return Math.floor(tick);
-    }
-    /**
-     * Attempts to parse number from string.
-     * If fails,returns original string.
-     * Used to make telemetry data typed (and support math operations, like comparison),
-     * in places where we do expect numbers (like contentsize/duration property in http header)
-     */
-    static numberFromString(str) {
-        if (str === undefined || str === null) {
-            return undefined;
-        }
-        const num = Number(str);
-        return Number.isNaN(num) ? str : num;
-    }
     static sanitizePkgName(name) {
         return name.replace("@", "").replace("/", "-");
     }
@@ -93,27 +91,29 @@ class TelemetryLogger {
      *
      * @param event - the event to send
      * @param error - optional error object to log
+     * @param logLevel - optional level of the log. It category of event is set as error,
+     * then the logLevel will be upgraded to be an error.
      */
-    sendTelemetryEvent(event, error) {
-        var _a;
-        this.sendTelemetryEventCore(Object.assign(Object.assign({}, event), { category: (_a = event.category) !== null && _a !== void 0 ? _a : "generic" }), error);
+    sendTelemetryEvent(event, error, logLevel = core_interfaces_1.LogLevel.default) {
+        this.sendTelemetryEventCore({ ...event, category: event.category ?? "generic" }, error, event.category === "error" ? core_interfaces_1.LogLevel.error : logLevel);
     }
     /**
      * Send a telemetry event with the logger
      *
      * @param event - the event to send
      * @param error - optional error object to log
+     * @param logLevel - optional level of the log.
      */
-    sendTelemetryEventCore(event, error) {
+    sendTelemetryEventCore(event, error, logLevel) {
         const newEvent = convertToBaseEvent(event);
         if (error !== undefined) {
             TelemetryLogger.prepareErrorObject(newEvent, error, false);
         }
         // Will include Nan & Infinity, but probably we do not care
         if (typeof newEvent.duration === "number") {
-            newEvent.duration = TelemetryLogger.formatTick(newEvent.duration);
+            newEvent.duration = formatTick(newEvent.duration);
         }
-        this.send(newEvent);
+        this.send(newEvent, logLevel);
     }
     /**
      * Send an error telemetry event with the logger
@@ -122,28 +122,41 @@ class TelemetryLogger {
      * @param error - optional error object to log
      */
     sendErrorEvent(event, error) {
-        this.sendTelemetryEventCore(Object.assign(Object.assign({ 
+        this.sendTelemetryEventCore({
             // ensure the error field has some value,
             // this can and will be overridden by event, or error
-            error: event.eventName }, event), { category: "error" }), error);
+            error: event.eventName,
+            ...event,
+            category: "error",
+        }, error, core_interfaces_1.LogLevel.error);
     }
     /**
      * Send a performance telemetry event with the logger
      *
      * @param event - Event to send
      * @param error - optional error object to log
+     * @param logLevel - optional level of the log. It category of event is set as error,
+     * then the logLevel will be upgraded to be an error.
      */
-    sendPerformanceEvent(event, error) {
-        var _a;
-        const perfEvent = Object.assign(Object.assign({}, event), { category: (_a = event.category) !== null && _a !== void 0 ? _a : "performance" });
-        this.sendTelemetryEventCore(perfEvent, error);
+    sendPerformanceEvent(event, error, logLevel = core_interfaces_1.LogLevel.default) {
+        const perfEvent = {
+            ...event,
+            category: event.category ?? "performance",
+        };
+        this.sendTelemetryEventCore(perfEvent, error, perfEvent.category === "error" ? core_interfaces_1.LogLevel.error : logLevel);
     }
     prepareEvent(event) {
         const includeErrorProps = event.category === "error" || event.error !== undefined;
-        const newEvent = Object.assign({}, event);
+        const newEvent = {
+            ...event,
+        };
         if (this.namespace !== undefined) {
             newEvent.eventName = `${this.namespace}${TelemetryLogger.eventNamespaceSeparator}${newEvent.eventName}`;
         }
+        return this.extendProperties(newEvent, includeErrorProps);
+    }
+    extendProperties(toExtend, includeErrorProps) {
+        const eventLike = toExtend;
         if (this.properties) {
             const properties = [];
             properties.push(this.properties.all);
@@ -153,24 +166,24 @@ class TelemetryLogger {
             for (const props of properties) {
                 if (props !== undefined) {
                     for (const key of Object.keys(props)) {
-                        if (event[key] !== undefined) {
+                        if (eventLike[key] !== undefined) {
                             continue;
                         }
                         const getterOrValue = props[key];
                         // If this throws, hopefully it is handled elsewhere
                         const value = typeof getterOrValue === "function" ? getterOrValue() : getterOrValue;
                         if (value !== undefined) {
-                            newEvent[key] = value;
+                            eventLike[key] = value;
                         }
                     }
                 }
             }
         }
-        return newEvent;
+        return toExtend;
     }
 }
 exports.TelemetryLogger = TelemetryLogger;
-TelemetryLogger.eventNamespaceSeparator = ":";
+TelemetryLogger.eventNamespaceSeparator = exports.eventNamespaceSeparator;
 /**
  * @deprecated 0.56, remove TaggedLoggerAdapter once its usage is removed from
  * container-runtime. Issue: #8191
@@ -180,6 +193,9 @@ class TaggedLoggerAdapter {
     constructor(logger) {
         this.logger = logger;
     }
+    /**
+     * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseLogger.send}
+     */
     send(eventWithTagsMaybe) {
         const newEvent = {
             category: eventWithTagsMaybe.category,
@@ -217,6 +233,17 @@ class TaggedLoggerAdapter {
     }
 }
 exports.TaggedLoggerAdapter = TaggedLoggerAdapter;
+/**
+ * Create a child logger based on the provided props object
+ * @param props - logger is the base logger the child will log to after it's processing, namespace will be prefixed to all event names, properties are default properties that will be applied events.
+ *
+ * @remarks
+ * Passing in no props object (i.e. undefined) will return a logger that is effectively a no-op.
+ */
+function createChildLogger(props) {
+    return ChildLogger.create(props?.logger, props?.namespace, props?.properties);
+}
+exports.createChildLogger = createChildLogger;
 /**
  * ChildLogger class contains various helper telemetry methods,
  * encoding in one place schemas for various types of Fluid telemetry events.
@@ -246,10 +273,16 @@ class ChildLogger extends TelemetryLogger {
             for (const extendedProps of [baseLogger.properties, properties]) {
                 if (extendedProps !== undefined) {
                     if (extendedProps.all !== undefined) {
-                        combinedProperties.all = Object.assign(Object.assign({}, combinedProperties.all), extendedProps.all);
+                        combinedProperties.all = {
+                            ...combinedProperties.all,
+                            ...extendedProps.all,
+                        };
                     }
                     if (extendedProps.error !== undefined) {
-                        combinedProperties.error = Object.assign(Object.assign({}, combinedProperties.error), extendedProps.error);
+                        combinedProperties.error = {
+                            ...combinedProperties.error,
+                            ...extendedProps.error,
+                        };
                     }
                 }
             }
@@ -258,20 +291,45 @@ class ChildLogger extends TelemetryLogger {
                 : namespace === undefined
                     ? baseLogger.namespace
                     : `${baseLogger.namespace}${TelemetryLogger.eventNamespaceSeparator}${namespace}`;
-            return new ChildLogger(baseLogger.baseLogger, combinedNamespace, combinedProperties);
+            const child = new ChildLogger(baseLogger.baseLogger, combinedNamespace, combinedProperties);
+            if (!(0, config_1.loggerIsMonitoringContext)(child) && (0, config_1.loggerIsMonitoringContext)(baseLogger)) {
+                (0, config_1.mixinMonitoringContext)(child, baseLogger.config);
+            }
+            return child;
         }
-        return new ChildLogger(baseLogger ? baseLogger : new BaseTelemetryNullLogger(), namespace, properties);
+        return new ChildLogger(baseLogger ? baseLogger : { send() { } }, namespace, properties);
+    }
+    get minLogLevel() {
+        return this.baseLogger.minLogLevel;
+    }
+    shouldFilterOutEvent(event, logLevel) {
+        const eventLogLevel = logLevel ?? core_interfaces_1.LogLevel.default;
+        const configLogLevel = this.baseLogger.minLogLevel ?? core_interfaces_1.LogLevel.default;
+        // Filter out in case event log level is below what is wanted in config.
+        return eventLogLevel < configLogLevel;
     }
     /**
      * Send an event with the logger
      *
      * @param event - the event to send
      */
-    send(event) {
-        this.baseLogger.send(this.prepareEvent(event));
+    send(event, logLevel) {
+        if (this.shouldFilterOutEvent(event, logLevel)) {
+            return;
+        }
+        this.baseLogger.send(this.prepareEvent(event), logLevel);
     }
 }
 exports.ChildLogger = ChildLogger;
+/**
+ * Create a logger which logs to multiple other loggers based on the provided props object
+ * @param props - loggers are the base loggers that will logged to after it's processing, namespace will be prefixed to all event names, properties are default properties that will be applied events.
+ * tryInheritProperties will attempted to copy those loggers properties to this loggers if they are of a known type e.g. one from this package
+ */
+function createMultiSinkLogger(props) {
+    return new MultiSinkLogger(props.namespace, props.properties, props.loggers?.filter((l) => l !== undefined), props.tryInheritProperties);
+}
+exports.createMultiSinkLogger = createMultiSinkLogger;
 /**
  * Multi-sink logger
  * Takes multiple ITelemetryBaseLogger objects (sinks) and logs all events into each sink
@@ -281,10 +339,41 @@ class MultiSinkLogger extends TelemetryLogger {
      * Create multiple sink logger (i.e. logger that sends events to multiple sinks)
      * @param namespace - Telemetry event name prefix to add to all events
      * @param properties - Base properties to add to all events
+     * @param loggers - The list of loggers to use as sinks
+     * @param tryInheritProperties - Will attempted to copy those loggers properties to this loggers if they are of a known type e.g. one from this package
      */
-    constructor(namespace, properties) {
-        super(namespace, properties);
-        this.loggers = [];
+    constructor(namespace, properties, loggers = [], tryInheritProperties) {
+        let realProperties = properties !== undefined ? { ...properties } : undefined;
+        if (tryInheritProperties === true) {
+            const merge = (realProperties ?? (realProperties = {}));
+            loggers
+                .filter((l) => l instanceof TelemetryLogger)
+                .map((l) => l.properties ?? {})
+                // eslint-disable-next-line unicorn/no-array-for-each
+                .forEach((cv) => {
+                // eslint-disable-next-line unicorn/no-array-for-each
+                Object.keys(cv).forEach((k) => {
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                    merge[k] = { ...cv[k], ...merge?.[k] };
+                });
+            });
+        }
+        super(namespace, realProperties);
+        this.loggers = loggers;
+        this._minLogLevelOfAllLoggers = core_interfaces_1.LogLevel.default;
+        this.calculateMinLogLevel();
+    }
+    get minLogLevel() {
+        return this._minLogLevelOfAllLoggers;
+    }
+    calculateMinLogLevel() {
+        if (this.loggers.length > 0) {
+            const logLevels = [];
+            for (const logger of this.loggers) {
+                logLevels.push(logger.minLogLevel ?? core_interfaces_1.LogLevel.default);
+            }
+            this._minLogLevelOfAllLoggers = Math.min(...logLevels);
+        }
     }
     /**
      * Add logger to send all events to
@@ -293,6 +382,8 @@ class MultiSinkLogger extends TelemetryLogger {
     addLogger(logger) {
         if (logger !== undefined && logger !== null) {
             this.loggers.push(logger);
+            // Update in case the logLevel of added logger is less than the current.
+            this.calculateMinLogLevel();
         }
     }
     /**
@@ -302,9 +393,9 @@ class MultiSinkLogger extends TelemetryLogger {
      */
     send(event) {
         const newEvent = this.prepareEvent(event);
-        this.loggers.forEach((logger) => {
+        for (const logger of this.loggers) {
             logger.send(newEvent);
-        });
+        }
     }
 }
 exports.MultiSinkLogger = MultiSinkLogger;
@@ -313,17 +404,17 @@ exports.MultiSinkLogger = MultiSinkLogger;
  */
 class PerformanceEvent {
     constructor(logger, event, markers = { end: true, cancel: "generic" }, recordHeapSize = false) {
-        var _a;
         this.logger = logger;
         this.markers = markers;
         this.recordHeapSize = recordHeapSize;
-        this.startTime = common_utils_1.performance.now();
+        this.startTime = client_utils_1.performance.now();
         this.startMemoryCollection = 0;
-        this.event = Object.assign({}, event);
+        this.event = { ...event };
         if (this.markers.start) {
             this.reportEvent("start");
         }
-        if (typeof window === "object" && window != null && ((_a = window.performance) === null || _a === void 0 ? void 0 : _a.mark)) {
+        // eslint-disable-next-line unicorn/no-null
+        if (typeof window === "object" && window != null && window.performance?.mark) {
             this.startMark = `${event.eventName}-start`;
             window.performance.mark(this.startMark);
         }
@@ -356,7 +447,7 @@ class PerformanceEvent {
         }
     }
     get duration() {
-        return common_utils_1.performance.now() - this.startTime;
+        return client_utils_1.performance.now() - this.startTime;
     }
     reportProgress(props, eventNameSuffix = "update") {
         this.reportEvent(eventNameSuffix, props);
@@ -384,7 +475,7 @@ class PerformanceEvent {
     }
     cancel(props, error) {
         if (this.markers.cancel !== undefined) {
-            this.reportEvent("cancel", Object.assign({ category: this.markers.cancel }, props), error);
+            this.reportEvent("cancel", { category: this.markers.cancel, ...props }, error);
         }
         this.event = undefined;
     }
@@ -392,19 +483,19 @@ class PerformanceEvent {
      * Report the event, if it hasn't already been reported.
      */
     reportEvent(eventNameSuffix, props, error) {
-        var _a, _b, _c, _d;
         // There are strange sequences involving multiple Promise chains
         // where the event can be cancelled and then later a callback is invoked
         // and the caller attempts to end directly, e.g. issue #3936. Just return.
         if (!this.event) {
             return;
         }
-        const event = Object.assign(Object.assign({}, this.event), props);
+        const event = { ...this.event, ...props };
         event.eventName = `${event.eventName}_${eventNameSuffix}`;
         if (eventNameSuffix !== "start") {
             event.duration = this.duration;
             if (this.startMemoryCollection) {
-                const currentMemory = (_b = (_a = common_utils_1.performance) === null || _a === void 0 ? void 0 : _a.memory) === null || _b === void 0 ? void 0 : _b.usedJSHeapSize;
+                const currentMemory = client_utils_1.performance?.memory
+                    ?.usedJSHeapSize;
                 const differenceInKBytes = Math.floor((currentMemory - this.startMemoryCollection) / 1024);
                 if (differenceInKBytes > 0) {
                     event.usedJSHeapSize = differenceInKBytes;
@@ -412,64 +503,18 @@ class PerformanceEvent {
             }
         }
         else if (this.recordHeapSize) {
-            this.startMemoryCollection = (_d = (_c = common_utils_1.performance) === null || _c === void 0 ? void 0 : _c.memory) === null || _d === void 0 ? void 0 : _d.usedJSHeapSize;
+            this.startMemoryCollection = client_utils_1.performance?.memory?.usedJSHeapSize;
         }
         this.logger.sendPerformanceEvent(event, error);
     }
 }
 exports.PerformanceEvent = PerformanceEvent;
 /**
- * Logger that is useful for UT
- * It can be used in places where logger instance is required, but events should be not send over.
- */
-class TelemetryUTLogger {
-    send(event) { }
-    sendTelemetryEvent(event, error) { }
-    sendErrorEvent(event, error) {
-        this.reportError("errorEvent in UT logger!", event, error);
-    }
-    sendPerformanceEvent(event, error) { }
-    logGenericError(eventName, error) {
-        this.reportError(`genericError in UT logger!`, { eventName }, error);
-    }
-    logException(event, exception) {
-        this.reportError("exception in UT logger!", event, exception);
-    }
-    debugAssert(condition, event) {
-        this.reportError("debugAssert in UT logger!");
-    }
-    shipAssert(condition, event) {
-        this.reportError("shipAssert in UT logger!");
-    }
-    reportError(message, event, err) {
-        const error = new Error(message);
-        error.error = error;
-        error.event = event;
-        // report to console as exception can be eaten
-        console.error(message);
-        console.error(error);
-        throw error;
-    }
-}
-exports.TelemetryUTLogger = TelemetryUTLogger;
-/**
- * Null logger
- * It can be used in places where logger instance is required, but events should be not send over.
- */
-class BaseTelemetryNullLogger {
-    /**
-     * Send an event with the logger
-     *
-     * @param event - the event to send
-     */
-    send(event) {
-        return;
-    }
-}
-exports.BaseTelemetryNullLogger = BaseTelemetryNullLogger;
-/**
- * Null logger
- * It can be used in places where logger instance is required, but events should be not send over.
+ * Null logger that no-ops for all telemetry events passed to it.
+ * @deprecated - This will be removed in a future release.
+ * For internal use within the FluidFramework codebase, use {@link createChildLogger} with no arguments instead.
+ * For external consumers we recommend writing a trivial implementation of {@link @fluidframework/core-interfaces#ITelemetryBaseLogger}
+ * where the send() method does nothing and using that.
  */
 class TelemetryNullLogger {
     send(event) { }
@@ -483,8 +528,7 @@ exports.TelemetryNullLogger = TelemetryNullLogger;
  * In the case of an invalid property type, the value will be converted to an error string.
  * @param event - Event with fields you want to stringify.
  */
-function convertToBaseEvent(_a) {
-    var { category, eventName } = _a, props = __rest(_a, ["category", "eventName"]);
+function convertToBaseEvent({ category, eventName, ...props }) {
     const newEvent = { category, eventName };
     for (const key of Object.keys(props)) {
         newEvent[key] = convertToBasePropertyType(props[key]);
@@ -494,8 +538,8 @@ function convertToBaseEvent(_a) {
 /**
  * Takes in value, and does one of 4 things.
  * if value is of primitive type - returns the original value.
- * If the value is an array of primitives - returns a stringified version of the array.
- * If the value is an object of type ITaggedTelemetryPropertyType - returns the object
+ * If the value is a flat array or object - returns a stringified version of the array/object.
+ * If the value is an object of type Tagged<TelemetryEventPropertyType> - returns the object
  * with its values recursively converted to base property Type.
  * If none of these cases are reached - returns an error string
  * @param x - value passed in to convert to a base property type
@@ -525,4 +569,29 @@ function convertToBasePropertyTypeUntagged(x) {
             return `INVALID PROPERTY (typed as ${typeof x})`;
     }
 }
+const tagData = (tag, values) => 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+Object.entries(values)
+    .filter((e) => e[1] !== undefined)
+    // eslint-disable-next-line unicorn/no-array-reduce, unicorn/prefer-object-from-entries
+    .reduce((pv, cv) => {
+    const [key, value] = cv;
+    if (typeof value === "function") {
+        // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+        pv[key] = () => {
+            return { tag, value: value() };
+        };
+    }
+    else {
+        pv[key] = { tag, value };
+    }
+    return pv;
+}, {});
+exports.tagData = tagData;
+/**
+ * Helper function to tag telemetry properties as CodeArtifacts. It supports properties of type
+ * TelemetryBaseEventPropertyType as well as getters that return TelemetryBaseEventPropertyType.
+ */
+const tagCodeArtifacts = (values) => (0, exports.tagData)(TelemetryDataTag.CodeArtifact, values);
+exports.tagCodeArtifacts = tagCodeArtifacts;
 //# sourceMappingURL=logger.js.map