@fluidframework/telemetry-utils 2.0.0-dev.6.4.0.192049 → 2.0.0-dev.7.2.0.204906

package/lib/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACzB,SAAkB,EAClB,MAA4B,EAC5B,KAAsC;IAEtC,IAAI,SAAS,EAAE;QACd,OAAO,IAAI,CAAC;KACZ;IACD,MAAM,QAAQ,GACb,OAAO,KAAK,KAAK,QAAQ;QACxB,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE;QACzC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;IACpC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtB,OAAO,KAAK,CAAC;AACd,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\nimport {\n\tITelemetryBaseEvent,\n\tITelemetryBaseLogger,\n\tITelemetryGenericEvent,\n} from \"@fluidframework/core-interfaces\";\n\n/**\n * Like assert, but logs only if the condition is false, rather than throwing\n * @param condition - The condition to attest too\n * @param logger - The logger to log with\n * @param event - The string or event to log\n * @returns The outcome of the condition\n */\nexport function logIfFalse(\n\tcondition: unknown,\n\tlogger: ITelemetryBaseLogger,\n\tevent: string | ITelemetryGenericEvent,\n): condition is true {\n\tif (condition) {\n\t\treturn true;\n\t}\n\tconst newEvent: ITelemetryBaseEvent =\n\t\ttypeof event === \"string\"\n\t\t\t? { eventName: event, category: \"error\" }\n\t\t\t: { category: \"error\", ...event };\n\tlogger.send(newEvent);\n\treturn false;\n}\n"]}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAGrD;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACzB,SAAkB,EAClB,MAA4B,EAC5B,KAAsC;IAEtC,IAAI,SAAS,EAAE;QACd,OAAO,IAAI,CAAC;KACZ;IACD,MAAM,QAAQ,GACb,OAAO,KAAK,KAAK,QAAQ;QACxB,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE;QACzC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;IACpC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtB,OAAO,KAAK,CAAC;AACd,CAAC;AA+BD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAClC,MAA2B,EAC3B,YAA4B;IAE5B,MAAM,iBAAiB,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAC5D,MAAM,kBAAkB,GACvB,iBAAiB,CAAC,MAAM,CAAC,UAAU,CAAC,iCAAiC,CAAC,IAAI,KAAK,CAAC;IAEjF,MAAM,aAAa,GAAG;QACrB,IAAI,EAAE,CAAC,KAA0B,EAAQ,EAAE;YAC1C,2DAA2D;YAC3D,gIAAgI;YAChI,2LAA2L;YAC3L,IAAI,kBAAkB,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,MAAM,EAAE,EAAE;gBAC9E,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;aACnB;QACF,CAAC;QACD,kBAAkB,EAAE,CAAC,KAAgC,EAAQ,EAAE;YAC9D,IAAI,kBAAkB,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,MAAM,EAAE,EAAE;gBAC9E,MAAM,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;aACjC;QACF,CAAC;QACD,cAAc,EAAE,CAAC,KAAgC,EAAQ,EAAE;YAC1D,IAAI,kBAAkB,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,MAAM,EAAE,EAAE;gBAC9E,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;aAC7B;QACF,CAAC;QACD,oBAAoB,EAAE,CAAC,KAAgC,EAAQ,EAAE;YAChE,IAAI,kBAAkB,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,MAAM,EAAE,EAAE;gBAC9E,MAAM,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;aACnC;QACF,CAAC;QACD,kBAAkB;KAClB,CAAC;IAEF,OAAO,aAAa,CAAC;AACtB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\nimport {\n\tITelemetryBaseEvent,\n\tITelemetryBaseLogger,\n\tITelemetryGenericEvent,\n} from \"@fluidframework/core-interfaces\";\nimport { loggerToMonitoringContext } from \"./config\";\nimport { ITelemetryGenericEventExt, ITelemetryLoggerExt } from \"./telemetryTypes\";\n\n/**\n * Like assert, but logs only if the condition is false, rather than throwing\n * @param condition - The condition to attest too\n * @param logger - The logger to log with\n * @param event - The string or event to log\n * @returns The outcome of the condition\n */\nexport function logIfFalse(\n\tcondition: unknown,\n\tlogger: ITelemetryBaseLogger,\n\tevent: string | ITelemetryGenericEvent,\n): condition is true {\n\tif (condition) {\n\t\treturn true;\n\t}\n\tconst newEvent: ITelemetryBaseEvent =\n\t\ttypeof event === \"string\"\n\t\t\t? { eventName: event, category: \"error\" }\n\t\t\t: { category: \"error\", ...event };\n\tlogger.send(newEvent);\n\treturn false;\n}\n\n/**\n * An object that contains a callback used in conjunction with the {@link createSampledLogger} utility function to provide custom logic for sampling events.\n *\n * @internal\n */\nexport interface IEventSampler {\n\t/**\n\t * @returns true if the event should be sampled or false if not\n\t */\n\tsample: () => boolean | undefined;\n}\n\n/**\n * A telemetry logger that has sampling capabilities\n *\n * @internal\n */\nexport interface ISampledTelemetryLogger extends ITelemetryLoggerExt {\n\t/**\n\t * Indicates if the feature flag to disable sampling is set.\n\t *\n\t * @remarks Exposed to enable some advanced scenarios where the code using the sampled logger\n\t * could take advantage of skipping the execution of some logic when it can determine\n\t * it won't be necessary because the telemetry event that needs it wouldn't be\n\t * emitted anyway.\n\t */\n\tisSamplingDisabled: boolean;\n}\n\n/**\n * Wraps around an existing logger matching the {@link ITelemetryLoggerExt} interface and provides the ability to only log a subset of events using a sampling strategy provided by an ${@link IEventSampler}.\n * You can chose to not provide an event sampler which is effectively a no-op, meaning that it will be treated as if the sampler always returns true.\n *\n * @remarks\n * The sampling functionality uses the Fluid telemetry logging configuration along with the optionally provided event sampling callback to determine whether an event should\n * be logged or not.\n *\n * Configuration object parameters:\n * 'Fluid.Telemetry.DisableSampling': if this config value is set to true, all events will be unsampled and therefore logged.\n * Otherwise only a sample will be logged according to the provided event sampler callback.\n *\n * Note that the same sampler is used for all APIs of the returned logger. If you want separate events flowing through the returned logger to be sampled separately, the {@link IEventSampler} you provide should track them separately.\n *\n * @internal\n */\nexport function createSampledLogger(\n\tlogger: ITelemetryLoggerExt,\n\teventSampler?: IEventSampler,\n): ISampledTelemetryLogger {\n\tconst monitoringContext = loggerToMonitoringContext(logger);\n\tconst isSamplingDisabled =\n\t\tmonitoringContext.config.getBoolean(\"Fluid.Telemetry.DisableSampling\") ?? false;\n\n\tconst sampledLogger = {\n\t\tsend: (event: ITelemetryBaseEvent): void => {\n\t\t\t// The sampler uses the following logic for sending events:\n\t\t\t// 1. If isSamplingDisabled is true, then this means events should be unsampled. Therefore we send the event without any checks.\n\t\t\t// 2. If isSamplingDisabled is false, then event should be sampled using the event sampler, if the sampler is not defined just send all events, other use the eventSampler.sample() method.\n\t\t\tif (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {\n\t\t\t\tlogger.send(event);\n\t\t\t}\n\t\t},\n\t\tsendTelemetryEvent: (event: ITelemetryGenericEventExt): void => {\n\t\t\tif (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {\n\t\t\t\tlogger.sendTelemetryEvent(event);\n\t\t\t}\n\t\t},\n\t\tsendErrorEvent: (event: ITelemetryGenericEventExt): void => {\n\t\t\tif (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {\n\t\t\t\tlogger.sendErrorEvent(event);\n\t\t\t}\n\t\t},\n\t\tsendPerformanceEvent: (event: ITelemetryGenericEventExt): void => {\n\t\t\tif (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {\n\t\t\t\tlogger.sendPerformanceEvent(event);\n\t\t\t}\n\t\t},\n\t\tisSamplingDisabled,\n\t};\n\n\treturn sampledLogger;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/telemetry-utils",
-  "version": "2.0.0-dev.6.4.0.192049",
+  "version": "2.0.0-dev.7.2.0.204906",
   "description": "Collection of telemetry relates utilities for Fluid",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -39,39 +39,38 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "2.0.0-dev.6.4.0.192049",
-    "@fluidframework/core-interfaces": "2.0.0-dev.6.4.0.192049",
-    "@fluidframework/core-utils": "2.0.0-dev.6.4.0.192049",
-    "@fluidframework/protocol-definitions": "^1.1.0",
-    "debug": "^4.1.1",
+    "@fluid-internal/client-utils": "2.0.0-dev.7.2.0.204906",
+    "@fluidframework/core-interfaces": "2.0.0-dev.7.2.0.204906",
+    "@fluidframework/core-utils": "2.0.0-dev.7.2.0.204906",
+    "@fluidframework/protocol-definitions": "^3.0.0",
+    "debug": "^4.3.4",
     "events": "^3.1.0",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
-    "@fluid-tools/build-cli": "^0.22.0",
-    "@fluidframework/build-common": "^2.0.0",
-    "@fluidframework/build-tools": "^0.22.0",
-    "@fluidframework/eslint-config-fluid": "^2.1.0",
-    "@fluidframework/mocha-test-setup": "2.0.0-dev.6.4.0.192049",
-    "@fluidframework/telemetry-utils-previous": "npm:@fluidframework/telemetry-utils@2.0.0-internal.6.3.0",
-    "@microsoft/api-extractor": "^7.34.4",
+    "@fluid-tools/build-cli": "0.26.0-203096",
+    "@fluidframework/build-common": "^2.0.2",
+    "@fluidframework/build-tools": "0.26.0-203096",
+    "@fluidframework/eslint-config-fluid": "^3.0.0",
+    "@fluidframework/mocha-test-setup": "2.0.0-dev.7.2.0.204906",
+    "@fluidframework/telemetry-utils-previous": "npm:@fluidframework/telemetry-utils@2.0.0-internal.7.1.0",
+    "@microsoft/api-extractor": "^7.37.0",
     "@types/debug": "^4.1.5",
     "@types/events": "^3.0.0",
     "@types/mocha": "^9.1.1",
     "@types/node": "^16.18.38",
     "@types/uuid": "^9.0.2",
     "c8": "^7.7.1",
-    "copyfiles": "^2.4.1",
     "cross-env": "^7.0.3",
-    "eslint": "~8.6.0",
+    "eslint": "~8.50.0",
     "mocha": "^10.2.0",
     "mocha-json-output-reporter": "^2.0.1",
     "mocha-multi-reporters": "^1.5.1",
     "moment": "^2.21.0",
-    "prettier": "~2.6.2",
+    "prettier": "~3.0.3",
     "rimraf": "^4.4.0",
     "sinon": "^7.4.2",
-    "typescript": "~4.5.5"
+    "typescript": "~5.1.6"
   },
   "typeValidation": {
     "broken": {}
@@ -80,11 +79,11 @@
     "build": "fluid-build . --task build",
     "build:commonjs": "fluid-build . --task commonjs",
     "build:compile": "fluid-build . --task compile",
-    "build:docs": "api-extractor run --local --typescript-compiler-folder ../../../node_modules/typescript && copyfiles -u 1 ./_api-extractor-temp/doc-models/* ../../../_api-extractor-temp/",
+    "build:docs": "api-extractor run --local",
     "build:esnext": "tsc --project ./tsconfig.esnext.json",
     "build:test": "tsc --project ./src/test/tsconfig.json",
     "bump-version": "npm version minor --no-push --no-git-tag-version && npm run build:genver",
-    "ci:build:docs": "api-extractor run --typescript-compiler-folder ../../../node_modules/typescript && copyfiles -u 1 ./_api-extractor-temp/* ../../../_api-extractor-temp/",
+    "ci:build:docs": "api-extractor run",
     "clean": "rimraf --glob 'dist' 'lib' '*.tsbuildinfo' '*.build.log' '_api-extractor-temp' 'nyc'",
     "eslint": "eslint --format stylish src",
     "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",

package/src/config.ts

@@ -77,10 +77,12 @@ function isPrimitiveType(type: string): type is PrimitiveTypeStrings {
 	switch (type) {
 		case "boolean":
 		case "number":
-		case "string":
+		case "string": {
 			return true;
-		default:
+		}
+		default: {
 			return false;
+		}
 	}
 }
 

package/src/error.ts

@@ -23,6 +23,8 @@ import { IFluidErrorBase } from "./fluidErrorBase";
 
 /**
  * Generic wrapper for an unrecognized/uncategorized error object
+ *
+ * @internal
  */
 export class GenericError extends LoggingError implements IGenericError, IFluidErrorBase {
 	readonly errorType = FluidErrorTypes.genericError;
@@ -33,9 +35,13 @@ export class GenericError extends LoggingError implements IGenericError, IFluidE
 	 * @param error - inner error object
 	 * @param props - Telemetry props to include when the error is logged
 	 */
-	// TODO: Use `unknown` instead (API breaking change because error is not just an input parameter, but a public member of the class)
-	// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
-	constructor(message: string, public readonly error?: any, props?: ITelemetryBaseProperties) {
+	constructor(
+		message: string,
+		// TODO: Use `unknown` instead (API breaking change because error is not just an input parameter, but a public member of the class)
+		// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+		public readonly error?: any,
+		props?: ITelemetryBaseProperties,
+	) {
 		// Don't try to log the inner error
 		super(message, props, new Set(["error"]));
 	}
@@ -43,6 +49,8 @@ export class GenericError extends LoggingError implements IGenericError, IFluidE
 
 /**
  * Error indicating an API is being used improperly resulting in an invalid operation.
+ *
+ * @internal
  */
 export class UsageError extends LoggingError implements IUsageError, IFluidErrorBase {
 	readonly errorType = FluidErrorTypes.usageError;
@@ -55,6 +63,8 @@ export class UsageError extends LoggingError implements IUsageError, IFluidError
 /**
  * DataCorruptionError indicates that we encountered definitive evidence that the data at rest
  * backing this container is corrupted, and this container would never be expected to load properly again
+ *
+ * @internal
  */
 export class DataCorruptionError extends LoggingError implements IErrorBase, IFluidErrorBase {
 	readonly errorType = FluidErrorTypes.dataCorruptionError;
@@ -73,6 +83,8 @@ export class DataCorruptionError extends LoggingError implements IErrorBase, IFl
  * The error will often originate in the dataStore or DDS implementation that is responding to incoming changes.
  * This differs from {@link DataCorruptionError} in that this may be a transient error that will not repro in another
  * client or session.
+ *
+ * @internal
  */
 export class DataProcessingError extends LoggingError implements IErrorBase, IFluidErrorBase {
 	/**

package/src/errorLogging.ts

@@ -27,6 +27,8 @@ const isRegularObject = (value: unknown): boolean => {
 
 /**
  * Inspect the given error for common "safe" props and return them.
+ *
+ * @internal
  */
 export function extractLogSafeErrorProperties(
 	error: unknown,
@@ -95,6 +97,8 @@ function copyProps(
 
 /**
  * Metadata to annotate an error object when annotating or normalizing it
+ *
+ * @internal
  */
 export interface IFluidErrorAnnotations {
 	/**
@@ -121,6 +125,8 @@ function patchLegacyError(
  * @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 function normalizeError(
 	error: unknown,
@@ -190,6 +196,8 @@ let stackPopulatedOnCreation: boolean | undefined;
  * 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 function generateErrorWithStack(): Error {
 	const err = new Error("<<generated stack>>");
@@ -209,6 +217,12 @@ export 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 function generateStack(): string | undefined {
 	return generateErrorWithStack().stack;
 }
@@ -219,6 +233,8 @@ export 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 function wrapError<T extends LoggingError>(
 	innerError: unknown,
@@ -258,6 +274,8 @@ export function wrapError<T extends LoggingError>(
  * 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 function wrapErrorAndLog<T extends LoggingError>(
 	innerError: unknown,
@@ -304,6 +322,8 @@ export function overwriteStack(error: IFluidErrorBase | LoggingError, stack: str
  * True for any error object that is an (optionally normalized) external error
  * 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 function isExternalError(error: unknown): boolean {
 	// LoggingErrors are an internal FF error type. However, an external error can be converted
@@ -351,12 +371,15 @@ function isTelemetryEventPropertyValue(x: unknown): x is TelemetryBaseEventPrope
 		case "string":
 		case "number":
 		case "boolean":
-		case "undefined":
+		case "undefined": {
 			return true;
-		default:
+		}
+		default: {
 			return false;
+		}
 	}
 }
+
 /**
  * Walk an object's enumerable properties to find those fit for telemetry.
  */
@@ -371,14 +394,12 @@ function getValidTelemetryProps(obj: object, keysToOmit: Set<string>): ITelemetr
 			| Tagged<TelemetryEventPropertyTypeExt>;
 
 		// ensure only valid props get logged, since props of logging error could be in any shape
-		if (isTaggedTelemetryPropertyValue(val)) {
-			props[key] = {
-				value: filterValidTelemetryProps(val.value, key),
-				tag: val.tag,
-			};
-		} else {
-			props[key] = filterValidTelemetryProps(val, key);
-		}
+		props[key] = isTaggedTelemetryPropertyValue(val)
+			? {
+					value: filterValidTelemetryProps(val.value, key),
+					tag: val.tag,
+			  }
+			: filterValidTelemetryProps(val, key);
 	}
 	return props;
 }
@@ -389,6 +410,8 @@ function getValidTelemetryProps(obj: object, keysToOmit: Set<string>): ITelemetr
  * 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 */
@@ -412,6 +435,8 @@ export const getCircularReplacer = (): ((key: string, value: unknown) => any) =>
  * 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 class LoggingError
 	extends Error
@@ -494,8 +519,16 @@ export class LoggingError
 
 /**
  * The Error class used when normalizing an external error
+ *
+ * @internal
  */
 export const NORMALIZED_ERROR_TYPE = "genericError";
+
+/**
+ * Subclass of LoggingError returned by normalizeError
+ *
+ * @internal
+ */
 class NormalizedLoggingError extends LoggingError {
 	// errorType "genericError" is used as a default value throughout the code.
 	// Note that this matches ContainerErrorType/DriverErrorType's genericError

package/src/events.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+// False positive: this is an import from the `events` package, not from Node.
+// eslint-disable-next-line unicorn/prefer-node-protocol
 import { EventEmitter } from "events";
 import { ITelemetryLoggerExt } from "./telemetryTypes";
 

package/src/index.ts

@@ -68,7 +68,7 @@ export {
 export { MockLogger } from "./mockLogger";
 export { ThresholdCounter } from "./thresholdCounter";
 export { SampledTelemetryHelper } from "./sampledTelemetryHelper";
-export { logIfFalse } from "./utils";
+export { logIfFalse, createSampledLogger, IEventSampler, ISampledTelemetryLogger } from "./utils";
 export {
 	TelemetryEventPropertyTypeExt,
 	ITelemetryEventExt,

package/src/logger.ts

@@ -305,26 +305,30 @@ export class TaggedLoggerAdapter implements ITelemetryBaseLogger {
 					? taggableProp
 					: { value: taggableProp, tag: undefined };
 			switch (tag) {
-				case undefined:
+				case undefined: {
 					// No tag means we can log plainly
 					newEvent[key] = value;
 					break;
+				}
 				case "PackageData": // For back-compat
-				case TelemetryDataTag.CodeArtifact:
+				case TelemetryDataTag.CodeArtifact: {
 					// For Microsoft applications, CodeArtifact is safe for now
 					// (we don't load 3P code in 1P apps)
 					newEvent[key] = value;
 					break;
-				case TelemetryDataTag.UserData:
+				}
+				case TelemetryDataTag.UserData: {
 					// Strip out anything tagged explicitly as UserData.
 					// Alternate strategy would be to hash these props
 					newEvent[key] = "REDACTED (UserData)";
 					break;
-				default:
+				}
+				default: {
 					// If we encounter a tag we don't recognize
 					// then we must assume we should scrub.
 					newEvent[key] = "REDACTED (unknown tag)";
 					break;
+				}
 			}
 		}
 		this.logger.send(newEvent);
@@ -404,11 +408,7 @@ export class ChildLogger extends TelemetryLogger {
 			return child;
 		}
 
-		return new ChildLogger(
-			baseLogger ? baseLogger : { send(): void {} },
-			namespace,
-			properties,
-		);
+		return new ChildLogger(baseLogger ?? { send(): void {} }, namespace, properties);
 	}
 
 	private constructor(
@@ -489,7 +489,7 @@ export class MultiSinkLogger extends TelemetryLogger {
 		loggers: ITelemetryBaseLogger[] = [],
 		tryInheritProperties?: true,
 	) {
-		let realProperties = properties !== undefined ? { ...properties } : undefined;
+		let realProperties = properties === undefined ? undefined : { ...properties };
 		if (tryInheritProperties === true) {
 			const merge = (realProperties ??= {});
 			loggers
@@ -566,22 +566,55 @@ export interface IPerformanceEventMarkers {
  * Helper class to log performance events
  */
 export class PerformanceEvent {
+	/**
+	 * Creates an instance of {@link PerformanceEvent} and starts measurements
+	 * @param logger - the logger to be used for publishing events
+	 * @param event - the logging event details which will be published with the performance measurements
+	 * @param markers - See {@link IPerformanceEventMarkers}
+	 * @param recordHeapSize - whether or not to also record memory performance
+	 * @param emitLogs - should this instance emit logs. If set to false, logs will not be emitted to the logger,
+	 * but measurements will still be performed and any specified markers will be generated.
+	 * @returns An instance of {@link PerformanceEvent}
+	 */
 	public static start(
 		logger: ITelemetryLoggerExt,
 		event: ITelemetryGenericEvent,
 		markers?: IPerformanceEventMarkers,
 		recordHeapSize: boolean = false,
+		emitLogs: boolean = true,
 	): PerformanceEvent {
-		return new PerformanceEvent(logger, event, markers, recordHeapSize);
+		return new PerformanceEvent(logger, event, markers, recordHeapSize, emitLogs);
 	}
 
+	/**
+	 * Measure a synchronous task
+	 * @param logger - the logger to be used for publishing events
+	 * @param event - the logging event details which will be published with the performance measurements
+	 * @param callback - the task to be executed and measured
+	 * @param markers - See {@link IPerformanceEventMarkers}
+	 * @param sampleThreshold - events with the same name and category will be sent to the logger
+	 * only when we hit this many executions of the task. If unspecified, all events will be sent.
+	 * @returns The results of the executed task
+	 *
+	 * @remarks Note that if the "same" event (category + eventName) would be emitted by different
+	 * tasks (`callback`), `sampleThreshold` is still applied only based on the event's category + eventName,
+	 * so executing either of the tasks will increase the internal counter and they
+	 * effectively "share" the sampling rate for the event.
+	 */
 	public static timedExec<T>(
 		logger: ITelemetryLoggerExt,
 		event: ITelemetryGenericEvent,
 		callback: (event: PerformanceEvent) => T,
 		markers?: IPerformanceEventMarkers,
+		sampleThreshold: number = 1,
 	): T {
-		const perfEvent = PerformanceEvent.start(logger, event, markers);
+		const perfEvent = PerformanceEvent.start(
+			logger,
+			event,
+			markers,
+			undefined, // recordHeapSize
+			PerformanceEvent.shouldReport(event, sampleThreshold),
+		);
 		try {
 			const ret = callback(perfEvent);
 			perfEvent.autoEnd();
@@ -592,14 +625,37 @@ export class PerformanceEvent {
 		}
 	}
 
+	/**
+	 * Measure an asynchronous task
+	 * @param logger - the logger to be used for publishing events
+	 * @param event - the logging event details which will be published with the performance measurements
+	 * @param callback - the task to be executed and measured
+	 * @param markers - See {@link IPerformanceEventMarkers}
+	 * @param recordHeapSize - whether or not to also record memory performance
+	 * @param sampleThreshold - events with the same name and category will be sent to the logger
+	 * only when we hit this many executions of the task. If unspecified, all events will be sent.
+	 * @returns The results of the executed task
+	 *
+	 * @remarks Note that if the "same" event (category + eventName) would be emitted by different
+	 * tasks (`callback`), `sampleThreshold` is still applied only based on the event's category + eventName,
+	 * so executing either of the tasks will increase the internal counter and they
+	 * effectively "share" the sampling rate for the event.
+	 */
 	public static async timedExecAsync<T>(
 		logger: ITelemetryLoggerExt,
 		event: ITelemetryGenericEvent,
 		callback: (event: PerformanceEvent) => Promise<T>,
 		markers?: IPerformanceEventMarkers,
 		recordHeapSize?: boolean,
+		sampleThreshold: number = 1,
 	): Promise<T> {
-		const perfEvent = PerformanceEvent.start(logger, event, markers, recordHeapSize);
+		const perfEvent = PerformanceEvent.start(
+			logger,
+			event,
+			markers,
+			recordHeapSize,
+			PerformanceEvent.shouldReport(event, sampleThreshold),
+		);
 		try {
 			const ret = await callback(perfEvent);
 			perfEvent.autoEnd();
@@ -624,14 +680,14 @@ export class PerformanceEvent {
 		event: ITelemetryGenericEvent,
 		private readonly markers: IPerformanceEventMarkers = { end: true, cancel: "generic" },
 		private readonly recordHeapSize: boolean = false,
+		private readonly emitLogs: boolean = true,
 	) {
 		this.event = { ...event };
 		if (this.markers.start) {
 			this.reportEvent("start");
 		}
 
-		// eslint-disable-next-line unicorn/no-null
-		if (typeof window === "object" && window != null && window.performance?.mark) {
+		if (typeof window === "object" && window?.performance?.mark) {
 			this.startMark = `${event.eventName}-start`;
 			window.performance.mark(this.startMark);
 		}
@@ -687,6 +743,10 @@ export class PerformanceEvent {
 			return;
 		}
 
+		if (!this.emitLogs) {
+			return;
+		}
+
 		const event: ITelemetryPerformanceEvent = { ...this.event, ...props };
 		event.eventName = `${event.eventName}_${eventNameSuffix}`;
 		if (eventNameSuffix !== "start") {
@@ -702,18 +762,25 @@ export class PerformanceEvent {
 				}
 			}
 		} else if (this.recordHeapSize) {
-			this.startMemoryCollection = (
-				performance as PerformanceWithMemory
-			)?.memory?.usedJSHeapSize;
+			this.startMemoryCollection = (performance as PerformanceWithMemory)?.memory
+				?.usedJSHeapSize;
 		}
 
 		this.logger.sendPerformanceEvent(event, error);
 	}
+
+	private static readonly eventHits = new Map<string, number>();
+	private static shouldReport(event: ITelemetryGenericEvent, sampleThreshold: number): boolean {
+		const eventKey = `.${event.category}.${event.eventName}`;
+		const hitCount = PerformanceEvent.eventHits.get(eventKey) ?? 0;
+		PerformanceEvent.eventHits.set(eventKey, hitCount >= sampleThreshold ? 1 : hitCount + 1);
+		return hitCount % sampleThreshold === 0;
+	}
 }
 
 /**
  * Null logger that no-ops for all telemetry events passed to it.
- * @deprecated - This will be removed in a future release.
+ * @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.
@@ -769,17 +836,20 @@ function convertToBasePropertyTypeUntagged(
 		case "string":
 		case "number":
 		case "boolean":
-		case "undefined":
+		case "undefined": {
 			return x;
-		case "object":
+		}
+		case "object": {
 			// We assume this is an array or flat object based on the input types
 			return JSON.stringify(x);
-		default:
+		}
+		default: {
 			// should never reach this case based on the input types
 			console.error(
 				`convertToBasePropertyTypeUntagged: INVALID PROPERTY (typed as ${typeof x})`,
 			);
 			return `INVALID PROPERTY (typed as ${typeof x})`;
+		}
 	}
 }
 
@@ -811,6 +881,8 @@ export const tagData = <
 		// eslint-disable-next-line unicorn/no-array-reduce, unicorn/prefer-object-from-entries
 		.reduce((pv, cv) => {
 			const [key, value] = cv;
+			// The ternary form is less legible in this case.
+			// eslint-disable-next-line unicorn/prefer-ternary
 			if (typeof value === "function") {
 				// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 				pv[key] = () => {

package/src/utils.ts

@@ -7,6 +7,8 @@ import {
 	ITelemetryBaseLogger,
 	ITelemetryGenericEvent,
 } from "@fluidframework/core-interfaces";
+import { loggerToMonitoringContext } from "./config";
+import { ITelemetryGenericEventExt, ITelemetryLoggerExt } from "./telemetryTypes";
 
 /**
  * Like assert, but logs only if the condition is false, rather than throwing
@@ -30,3 +32,86 @@ export function logIfFalse(
 	logger.send(newEvent);
 	return false;
 }
+
+/**
+ * An object that contains a callback used in conjunction with the {@link createSampledLogger} utility function to provide custom logic for sampling events.
+ *
+ * @internal
+ */
+export interface IEventSampler {
+	/**
+	 * @returns true if the event should be sampled or false if not
+	 */
+	sample: () => boolean | undefined;
+}
+
+/**
+ * A telemetry logger that has sampling capabilities
+ *
+ * @internal
+ */
+export interface ISampledTelemetryLogger extends ITelemetryLoggerExt {
+	/**
+	 * Indicates if the feature flag to disable sampling is set.
+	 *
+	 * @remarks Exposed to enable some advanced scenarios where the code using the sampled logger
+	 * could take advantage of skipping the execution of some logic when it can determine
+	 * it won't be necessary because the telemetry event that needs it wouldn't be
+	 * emitted anyway.
+	 */
+	isSamplingDisabled: boolean;
+}
+
+/**
+ * Wraps around an existing logger matching the {@link ITelemetryLoggerExt} interface and provides the ability to only log a subset of events using a sampling strategy provided by an ${@link IEventSampler}.
+ * You can chose to not provide an event sampler which is effectively a no-op, meaning that it will be treated as if the sampler always returns true.
+ *
+ * @remarks
+ * The sampling functionality uses the Fluid telemetry logging configuration along with the optionally provided event sampling callback to determine whether an event should
+ * be logged or not.
+ *
+ * Configuration object parameters:
+ * 'Fluid.Telemetry.DisableSampling': if this config value is set to true, all events will be unsampled and therefore logged.
+ * Otherwise only a sample will be logged according to the provided event sampler callback.
+ *
+ * Note that the same sampler is used for all APIs of the returned logger. If you want separate events flowing through the returned logger to be sampled separately, the {@link IEventSampler} you provide should track them separately.
+ *
+ * @internal
+ */
+export function createSampledLogger(
+	logger: ITelemetryLoggerExt,
+	eventSampler?: IEventSampler,
+): ISampledTelemetryLogger {
+	const monitoringContext = loggerToMonitoringContext(logger);
+	const isSamplingDisabled =
+		monitoringContext.config.getBoolean("Fluid.Telemetry.DisableSampling") ?? false;
+
+	const sampledLogger = {
+		send: (event: ITelemetryBaseEvent): void => {
+			// The sampler uses the following logic for sending events:
+			// 1. If isSamplingDisabled is true, then this means events should be unsampled. Therefore we send the event without any checks.
+			// 2. If isSamplingDisabled is false, then event should be sampled using the event sampler, if the sampler is not defined just send all events, other use the eventSampler.sample() method.
+			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				logger.send(event);
+			}
+		},
+		sendTelemetryEvent: (event: ITelemetryGenericEventExt): void => {
+			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				logger.sendTelemetryEvent(event);
+			}
+		},
+		sendErrorEvent: (event: ITelemetryGenericEventExt): void => {
+			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				logger.sendErrorEvent(event);
+			}
+		},
+		sendPerformanceEvent: (event: ITelemetryGenericEventExt): void => {
+			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				logger.sendPerformanceEvent(event);
+			}
+		},
+		isSamplingDisabled,
+	};
+
+	return sampledLogger;
+}