@fluidframework/telemetry-utils 2.0.0-internal.6.2.0 → 2.0.0-internal.6.3.0

package/src/errorLogging.ts

@@ -5,9 +5,9 @@
 
 import {
 	ILoggingError,
-	ITaggedTelemetryPropertyType,
-	ITelemetryProperties,
-	TelemetryEventPropertyType,
+	ITelemetryBaseProperties,
+	TelemetryBaseEventPropertyType,
+	Tagged,
 } from "@fluidframework/core-interfaces";
 import { v4 as uuid } from "uuid";
 import {
@@ -16,11 +16,7 @@ import {
 	isFluidError,
 	isValidLegacyError,
 } from "./fluidErrorBase";
-import {
-	ITaggedTelemetryPropertyTypeExt,
-	ITelemetryLoggerExt,
-	TelemetryEventPropertyTypeExt,
-} from "./telemetryTypes";
+import { ITelemetryLoggerExt, TelemetryEventPropertyTypeExt } from "./telemetryTypes";
 
 /**
  * Determines if the provided value is an object but neither null nor an array.
@@ -87,8 +83,8 @@ export const isILoggingError = (x: unknown): x is ILoggingError =>
  * Copy props from source onto target, but do not overwrite an existing prop that matches
  */
 function copyProps(
-	target: ITelemetryProperties | LoggingError,
-	source: ITelemetryProperties,
+	target: ITelemetryBaseProperties | LoggingError,
+	source: ITelemetryBaseProperties,
 ): void {
 	for (const key of Object.keys(source)) {
 		if (target[key] === undefined) {
@@ -104,7 +100,7 @@ export interface IFluidErrorAnnotations {
 	/**
 	 * Telemetry props to log with the error
 	 */
-	props?: ITelemetryProperties;
+	props?: ITelemetryBaseProperties;
 }
 
 /**
@@ -319,9 +315,9 @@ export function isExternalError(error: unknown): boolean {
  * Type guard to identify if a particular telemetry property appears to be a tagged telemetry property
  */
 export function isTaggedTelemetryPropertyValue(
-	x: ITaggedTelemetryPropertyTypeExt | TelemetryEventPropertyTypeExt,
-): x is ITaggedTelemetryPropertyType | ITaggedTelemetryPropertyTypeExt {
-	return typeof (x as Partial<ITaggedTelemetryPropertyTypeExt>)?.tag === "string";
+	x: Tagged<TelemetryEventPropertyTypeExt> | TelemetryEventPropertyTypeExt,
+): x is Tagged<TelemetryEventPropertyTypeExt> {
+	return typeof (x as Partial<Tagged<unknown>>)?.tag === "string";
 }
 
 /**
@@ -330,7 +326,7 @@ export function isTaggedTelemetryPropertyValue(
  * @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: unknown, key: string): TelemetryEventPropertyType {
+function filterValidTelemetryProps(x: unknown, key: string): TelemetryBaseEventPropertyType {
 	if (Array.isArray(x) && x.every((val) => isTelemetryEventPropertyValue(val))) {
 		return JSON.stringify(x);
 	}
@@ -343,7 +339,7 @@ function filterValidTelemetryProps(x: unknown, key: string): TelemetryEventPrope
 }
 
 // checking type of x, returns false if x is null
-function isTelemetryEventPropertyValue(x: unknown): x is TelemetryEventPropertyType {
+function isTelemetryEventPropertyValue(x: unknown): x is TelemetryBaseEventPropertyType {
 	switch (typeof x) {
 		case "string":
 		case "number":
@@ -357,13 +353,15 @@ function isTelemetryEventPropertyValue(x: unknown): x is TelemetryEventPropertyT
 /**
  * Walk an object's enumerable properties to find those fit for telemetry.
  */
-function getValidTelemetryProps(obj: object, keysToOmit: Set<string>): ITelemetryProperties {
-	const props: ITelemetryProperties = {};
+function getValidTelemetryProps(obj: object, keysToOmit: Set<string>): ITelemetryBaseProperties {
+	const props: ITelemetryBaseProperties = {};
 	for (const key of Object.keys(obj)) {
 		if (keysToOmit.has(key)) {
 			continue;
 		}
-		const val = obj[key] as ITaggedTelemetryPropertyTypeExt | TelemetryEventPropertyTypeExt;
+		const val = obj[key] as
+			| TelemetryEventPropertyTypeExt
+			| Tagged<TelemetryEventPropertyTypeExt>;
 
 		// ensure only valid props get logged, since props of logging error could be in any shape
 		if (isTaggedTelemetryPropertyValue(val)) {
@@ -435,7 +433,7 @@ export class LoggingError
 	 */
 	constructor(
 		message: string,
-		props?: ITelemetryProperties,
+		props?: ITelemetryBaseProperties,
 		private readonly omitPropsFromLogging: Set<string> = new Set(),
 	) {
 		super(message);
@@ -468,14 +466,14 @@ export class LoggingError
 	/**
 	 * Add additional properties to be logged
 	 */
-	public addTelemetryProperties(props: ITelemetryProperties): void {
+	public addTelemetryProperties(props: ITelemetryBaseProperties): void {
 		copyProps(this, props);
 	}
 
 	/**
 	 * Get all properties fit to be logged to telemetry for this error
 	 */
-	public getTelemetryProperties(): ITelemetryProperties {
+	public getTelemetryProperties(): ITelemetryBaseProperties {
 		const taggableProps = getValidTelemetryProps(this, this.omitPropsFromLogging);
 		// Include non-enumerable props that are not returned by getValidTelemetryProps
 		return {

package/src/eventEmitterWithErrorHandling.ts

@@ -2,8 +2,8 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
+import { TypedEventEmitter, EventEmitterEventType } from "@fluid-internal/client-utils";
 import { IEvent } from "@fluidframework/core-interfaces";
-import { TypedEventEmitter, EventEmitterEventType } from "@fluidframework/common-utils";
 
 /**
  * Event Emitter helper class

package/src/index.ts

@@ -77,4 +77,5 @@ export {
 	ITelemetryLoggerExt,
 	ITaggedTelemetryPropertyTypeExt,
 	ITelemetryPropertiesExt,
+	TelemetryEventCategory,
 } from "./telemetryTypes";

package/src/logger.ts

@@ -10,12 +10,12 @@ import {
 	ITelemetryGenericEvent,
 	ITelemetryPerformanceEvent,
 	ITelemetryProperties,
-	TelemetryEventPropertyType,
-	ITaggedTelemetryPropertyType,
-	TelemetryEventCategory,
+	TelemetryBaseEventPropertyType as TelemetryEventPropertyType,
 	LogLevel,
+	Tagged,
+	ITelemetryBaseProperties,
 } from "@fluidframework/core-interfaces";
-import { IsomorphicPerformance, performance } from "@fluidframework/common-utils";
+import { IsomorphicPerformance, performance } from "@fluid-internal/client-utils";
 import { CachedConfigProvider, loggerIsMonitoringContext, mixinMonitoringContext } from "./config";
 import {
 	isILoggingError,
@@ -24,13 +24,12 @@ import {
 	isTaggedTelemetryPropertyValue,
 } from "./errorLogging";
 import {
-	ITaggedTelemetryPropertyTypeExt,
 	ITelemetryEventExt,
 	ITelemetryGenericEventExt,
 	ITelemetryLoggerExt,
 	ITelemetryPerformanceEventExt,
-	ITelemetryPropertiesExt,
 	TelemetryEventPropertyTypeExt,
+	TelemetryEventCategory,
 } from "./telemetryTypes";
 
 export interface Memory {
@@ -55,7 +54,7 @@ export enum TelemetryDataTag {
 	UserData = "UserData",
 }
 
-export type TelemetryEventPropertyTypes = TelemetryEventPropertyType | ITaggedTelemetryPropertyType;
+export type TelemetryEventPropertyTypes = ITelemetryBaseProperties[string];
 
 export interface ITelemetryLoggerPropertyBag {
 	[index: string]: TelemetryEventPropertyTypes | (() => TelemetryEventPropertyTypes);
@@ -160,7 +159,7 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 	public sendTelemetryEvent(
 		event: ITelemetryGenericEventExt,
 		error?: unknown,
-		logLevel: LogLevel.verbose | LogLevel.default = LogLevel.default,
+		logLevel: typeof LogLevel.verbose | typeof LogLevel.default = LogLevel.default,
 	): void {
 		this.sendTelemetryEventCore(
 			{ ...event, category: event.category ?? "generic" },
@@ -225,7 +224,7 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 	public sendPerformanceEvent(
 		event: ITelemetryPerformanceEventExt,
 		error?: unknown,
-		logLevel: LogLevel.verbose | LogLevel.default = LogLevel.default,
+		logLevel: typeof LogLevel.verbose | typeof LogLevel.default = LogLevel.default,
 	): void {
 		const perfEvent = {
 			...event,
@@ -424,7 +423,11 @@ export class ChildLogger extends TelemetryLogger {
 		}
 	}
 
-	private shouldFilterOutEvent(event: ITelemetryPropertiesExt, logLevel?: LogLevel): boolean {
+	public get minLogLevel(): LogLevel | undefined {
+		return this.baseLogger.minLogLevel;
+	}
+
+	private shouldFilterOutEvent(event: ITelemetryBaseEvent, logLevel?: LogLevel): boolean {
 		const eventLogLevel = logLevel ?? LogLevel.default;
 		const configLogLevel = this.baseLogger.minLogLevel ?? LogLevel.default;
 		// Filter out in case event log level is below what is wanted in config.
@@ -469,6 +472,9 @@ export function createMultiSinkLogger(props: {
  */
 export class MultiSinkLogger extends TelemetryLogger {
 	protected loggers: ITelemetryBaseLogger[];
+	// This is minimum of minLlogLevel of all loggers.
+	private _minLogLevelOfAllLoggers: LogLevel;
+
 	/**
 	 * Create multiple sink logger (i.e. logger that sends events to multiple sinks)
 	 * @param namespace - Telemetry event name prefix to add to all events
@@ -500,6 +506,22 @@ export class MultiSinkLogger extends TelemetryLogger {
 
 		super(namespace, realProperties);
 		this.loggers = loggers;
+		this._minLogLevelOfAllLoggers = LogLevel.default;
+		this.calculateMinLogLevel();
+	}
+
+	public get minLogLevel(): LogLevel {
+		return this._minLogLevelOfAllLoggers;
+	}
+
+	private calculateMinLogLevel(): void {
+		if (this.loggers.length > 0) {
+			const logLevels: LogLevel[] = [];
+			for (const logger of this.loggers) {
+				logLevels.push(logger.minLogLevel ?? LogLevel.default);
+			}
+			this._minLogLevelOfAllLoggers = Math.min(...logLevels) as LogLevel;
+		}
 	}
 
 	/**
@@ -509,6 +531,8 @@ export class MultiSinkLogger extends TelemetryLogger {
 	public addLogger(logger?: ITelemetryBaseLogger): void {
 		if (logger !== undefined && logger !== null) {
 			this.loggers.push(logger);
+			// Update in case the logLevel of added logger is less than the current.
+			this.calculateMinLogLevel();
 		}
 	}
 
@@ -720,15 +744,15 @@ function convertToBaseEvent({
 /**
  * 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
  */
 export function convertToBasePropertyType(
-	x: TelemetryEventPropertyTypeExt | ITaggedTelemetryPropertyTypeExt,
-): TelemetryEventPropertyType | ITaggedTelemetryPropertyType {
+	x: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>,
+): TelemetryEventPropertyType | Tagged<TelemetryEventPropertyType> {
 	return isTaggedTelemetryPropertyValue(x)
 		? {
 				value: convertToBasePropertyTypeUntagged(x.value),

package/src/mockLogger.ts

@@ -3,8 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryBaseEvent, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
-import { assert } from "@fluidframework/common-utils";
+import {
+	ITelemetryBaseEvent,
+	ITelemetryBaseLogger,
+	LogLevel,
+} from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils";
 import { ITelemetryLoggerExt, ITelemetryPropertiesExt } from "./telemetryTypes";
 import { createChildLogger } from "./logger";
 
@@ -15,6 +19,8 @@ import { createChildLogger } from "./logger";
 export class MockLogger implements ITelemetryBaseLogger {
 	events: ITelemetryBaseEvent[] = [];
 
+	constructor(public readonly minLogLevel?: LogLevel) {}
+
 	clear(): void {
 		this.events = [];
 	}

package/src/sampledTelemetryHelper.ts

@@ -9,7 +9,7 @@ import {
 	ITelemetryProperties,
 	IDisposable,
 } from "@fluidframework/core-interfaces";
-import { performance } from "@fluidframework/common-utils";
+import { performance } from "@fluid-internal/client-utils";
 import { ITelemetryLoggerExt } from "./telemetryTypes";
 
 /**

package/src/telemetryTypes.ts

@@ -3,15 +3,20 @@
  * Licensed under the MIT License.
  */
 
-import {
-	ITelemetryBaseLogger,
-	LogLevel,
-	TelemetryEventCategory,
-} from "@fluidframework/core-interfaces";
+import { ITelemetryBaseLogger, LogLevel, Tagged } from "@fluidframework/core-interfaces";
+
+/**
+ * The categories FF uses when instrumenting the code.
+ *
+ * generic - Informational log event
+ * error - Error log event, ideally 0 of these are logged during a session
+ * performance - Includes duration, and often has _start, _end, or _cancel suffixes for activity tracking
+ */
+export type TelemetryEventCategory = "generic" | "error" | "performance";
 
 /**
  * Property types that can be logged.
- * Includes extra types beyond TelemetryEventPropertyType (which will be deprecated in favor of this one)
+ * Includes extra types beyond TelemetryBaseEventPropertyType, which must be converted before sending to a base logger
  */
 export type TelemetryEventPropertyTypeExt =
 	| string
@@ -28,6 +33,8 @@ export type TelemetryEventPropertyTypeExt =
  * A property to be logged to telemetry containing both the value and a tag. Tags are generic strings that can be used
  * to mark pieces of information that should be organized or handled differently by loggers in various first or third
  * party scenarios. For example, tags are used to mark personal information that should not be stored in logs.
+ *
+ * @deprecated Use Tagged<TelemetryEventPropertyTypeExt>
  */
 export interface ITaggedTelemetryPropertyTypeExt {
 	value: TelemetryEventPropertyTypeExt;
@@ -38,7 +45,7 @@ export interface ITaggedTelemetryPropertyTypeExt {
  * JSON-serializable properties, which will be logged with telemetry.
  */
 export interface ITelemetryPropertiesExt {
-	[index: string]: TelemetryEventPropertyTypeExt | ITaggedTelemetryPropertyTypeExt;
+	[index: string]: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>;
 }
 
 /**
@@ -92,7 +99,7 @@ export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
 	sendTelemetryEvent(
 		event: ITelemetryGenericEventExt,
 		error?: unknown,
-		logLevel?: LogLevel.verbose | LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
 	): void;
 
 	/**
@@ -111,6 +118,6 @@ export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
 	sendPerformanceEvent(
 		event: ITelemetryPerformanceEventExt,
 		error?: unknown,
-		logLevel?: LogLevel.verbose | LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
 	): void;
 }