@fluidframework/telemetry-utils 1.2.6 → 1.3.0-100520

package/dist/index.d.ts

@@ -11,5 +11,6 @@ export * from "./logger";
 export * from "./mockLogger";
 export * from "./thresholdCounter";
 export * from "./utils";
+export * from "./sampledTelemetryHelper";
 export { MonitoringContext, IConfigProviderBase, sessionStorageConfigProvider, mixinMonitoringContext, IConfigProvider, ConfigTypes, loggerToMonitoringContext, } from "./config";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iCAAiC,CAAC;AAChD,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,OAAO,EACH,iBAAiB,EACjB,mBAAmB,EACnB,4BAA4B,EAC5B,sBAAsB,EACtB,eAAe,EACf,WAAW,EACX,yBAAyB,GAC5B,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iCAAiC,CAAC;AAChD,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,0BAA0B,CAAC;AACzC,OAAO,EACH,iBAAiB,EACjB,mBAAmB,EACnB,4BAA4B,EAC5B,sBAAsB,EACtB,eAAe,EACf,WAAW,EACX,yBAAyB,GAC5B,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -24,6 +24,7 @@ __exportStar(require("./logger"), exports);
 __exportStar(require("./mockLogger"), exports);
 __exportStar(require("./thresholdCounter"), exports);
 __exportStar(require("./utils"), exports);
+__exportStar(require("./sampledTelemetryHelper"), exports);
 var config_1 = require("./config");
 Object.defineProperty(exports, "sessionStorageConfigProvider", { enumerable: true, get: function () { return config_1.sessionStorageConfigProvider; } });
 Object.defineProperty(exports, "mixinMonitoringContext", { enumerable: true, get: function () { return config_1.mixinMonitoringContext; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA;;;GAGG;AACH,gDAA8B;AAC9B,iDAA+B;AAC/B,kEAAgD;AAChD,2CAAyB;AACzB,mDAAiC;AACjC,2CAAyB;AACzB,+CAA6B;AAC7B,qDAAmC;AACnC,0CAAwB;AACxB,mCAQkB;AALd,sHAAA,4BAA4B,OAAA;AAC5B,gHAAA,sBAAsB,OAAA;AAGtB,mHAAA,yBAAyB,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\nexport * from \"./debugLogger\";\nexport * from \"./errorLogging\";\nexport * from \"./eventEmitterWithErrorHandling\";\nexport * from \"./events\";\nexport * from \"./fluidErrorBase\";\nexport * from \"./logger\";\nexport * from \"./mockLogger\";\nexport * from \"./thresholdCounter\";\nexport * from \"./utils\";\nexport {\n    MonitoringContext,\n    IConfigProviderBase,\n    sessionStorageConfigProvider,\n    mixinMonitoringContext,\n    IConfigProvider,\n    ConfigTypes,\n    loggerToMonitoringContext,\n} from \"./config\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA;;;GAGG;AACH,gDAA8B;AAC9B,iDAA+B;AAC/B,kEAAgD;AAChD,2CAAyB;AACzB,mDAAiC;AACjC,2CAAyB;AACzB,+CAA6B;AAC7B,qDAAmC;AACnC,0CAAwB;AACxB,2DAAyC;AACzC,mCAQkB;AALd,sHAAA,4BAA4B,OAAA;AAC5B,gHAAA,sBAAsB,OAAA;AAGtB,mHAAA,yBAAyB,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\nexport * from \"./debugLogger\";\nexport * from \"./errorLogging\";\nexport * from \"./eventEmitterWithErrorHandling\";\nexport * from \"./events\";\nexport * from \"./fluidErrorBase\";\nexport * from \"./logger\";\nexport * from \"./mockLogger\";\nexport * from \"./thresholdCounter\";\nexport * from \"./utils\";\nexport * from \"./sampledTelemetryHelper\";\nexport {\n    MonitoringContext,\n    IConfigProviderBase,\n    sessionStorageConfigProvider,\n    mixinMonitoringContext,\n    IConfigProvider,\n    ConfigTypes,\n    loggerToMonitoringContext,\n} from \"./config\";\n"]}

package/dist/packageVersion.d.ts

@@ -5,5 +5,5 @@
  * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY
  */
 export declare const pkgName = "@fluidframework/telemetry-utils";
-export declare const pkgVersion = "1.2.6";
+export declare const pkgVersion = "1.3.0-100520";
 //# sourceMappingURL=packageVersion.d.ts.map

package/dist/packageVersion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"packageVersion.d.ts","sourceRoot":"","sources":["../src/packageVersion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,OAAO,oCAAoC,CAAC;AACzD,eAAO,MAAM,UAAU,UAAU,CAAC"}
+{"version":3,"file":"packageVersion.d.ts","sourceRoot":"","sources":["../src/packageVersion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,OAAO,oCAAoC,CAAC;AACzD,eAAO,MAAM,UAAU,iBAAiB,CAAC"}

package/dist/packageVersion.js

@@ -8,5 +8,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pkgVersion = exports.pkgName = void 0;
 exports.pkgName = "@fluidframework/telemetry-utils";
-exports.pkgVersion = "1.2.6";
+exports.pkgVersion = "1.3.0-100520";
 //# sourceMappingURL=packageVersion.js.map

package/dist/packageVersion.js.map

@@ -1 +1 @@
-{"version":3,"file":"packageVersion.js","sourceRoot":"","sources":["../src/packageVersion.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEU,QAAA,OAAO,GAAG,iCAAiC,CAAC;AAC5C,QAAA,UAAU,GAAG,OAAO,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n *\n * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY\n */\n\nexport const pkgName = \"@fluidframework/telemetry-utils\";\nexport const pkgVersion = \"1.2.6\";\n"]}
+{"version":3,"file":"packageVersion.js","sourceRoot":"","sources":["../src/packageVersion.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEU,QAAA,OAAO,GAAG,iCAAiC,CAAC;AAC5C,QAAA,UAAU,GAAG,cAAc,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n *\n * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY\n */\n\nexport const pkgName = \"@fluidframework/telemetry-utils\";\nexport const pkgVersion = \"1.3.0-100520\";\n"]}

package/dist/sampledTelemetryHelper.d.ts

@@ -0,0 +1,53 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IDisposable, ITelemetryGenericEvent, ITelemetryLogger, ITelemetryProperties } from "@fluidframework/common-definitions";
+/**
+ * Helper class that executes a specified code block and writes an
+ * {@link @fluidframework/common-definitions#ITelemetryPerformanceEvent} to a specified logger every time a specified
+ * number of executions is reached (or when the class is disposed). The `duration` field in the telemetry event is
+ * the duration of the latest execution (sample) of the specified function. See the documentation of the
+ * `includeAggregateMetrics` parameter for additional details that can be included.
+ */
+export declare class SampledTelemetryHelper implements IDisposable {
+    private readonly eventBase;
+    private readonly logger;
+    private readonly sampleThreshold;
+    private readonly includeAggregateMetrics;
+    private readonly perBucketProperties;
+    disposed: boolean;
+    private readonly measurementsMap;
+    /**
+     * @param eventBase -
+     * Custom properties to include in the telemetry performance event when it is written.
+     * @param logger -
+     * The logger to use to write the telemetry performance event.
+     * @param sampleThreshold -
+     * Telemetry performance events will be generated every time we hit this many executions of the code block.
+     * @param includeAggregateMetrics -
+     * If set to `true`, the telemetry performance event will include aggregated metrics (total duration, min duration,
+     * max duration) for all the executions in between generated events.
+     * @param perBucketProperties -
+     * Map of strings that represent different buckets (which can be specified when calling the 'measure' method), to
+     * properties which should be added to the telemetry event for that bucket. If a bucket being measured does not
+     * have an entry in this map, no additional properties will be added to its telemetry events. The following keys are
+     * reserved for use by this class: "duration", "count", "totalDuration", "minDuration", "maxDuration". If any of
+     * them is specified as a key in one of the ITelemetryProperties objects in this map, that key-value pair will be
+     * ignored.
+     */
+    constructor(eventBase: ITelemetryGenericEvent, logger: ITelemetryLogger, sampleThreshold: number, includeAggregateMetrics?: boolean, perBucketProperties?: Map<string, ITelemetryProperties>);
+    /**
+     * @param codeToMeasure -
+     * The code to be executed and measured.
+     * @param bucket -
+     * A key to track executions of the code block separately. Each different value of this parameter has a separate
+     * set of executions and metrics tracked by the class. If no such distinction needs to be made, do not provide a
+     * value.
+     * @returns Whatever the passed-in code block returns.
+     */
+    measure<T>(codeToMeasure: () => T, bucket?: string): T;
+    private flushBucket;
+    dispose(error?: Error | undefined): void;
+}
+//# sourceMappingURL=sampledTelemetryHelper.d.ts.map

package/dist/sampledTelemetryHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampledTelemetryHelper.d.ts","sourceRoot":"","sources":["../src/sampledTelemetryHelper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACH,WAAW,EACX,sBAAsB,EACtB,gBAAgB,EAEhB,oBAAoB,EACvB,MAAM,oCAAoC,CAAC;AAkC5C;;;;;;GAMG;AACF,qBAAa,sBAAuB,YAAW,WAAW;IAwBnD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,uBAAuB;IACxC,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IA3BxC,QAAQ,EAAE,OAAO,CAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;IAEnE;;;;;;;;;;;;;;;;;OAiBG;gBAEkB,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,gBAAgB,EACxB,eAAe,EAAE,MAAM,EACvB,uBAAuB,GAAE,OAAe,EACxC,mBAAmB,oCAA0C;IAGlF;;;;;;;;OAQG;IACI,OAAO,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,MAAM,GAAE,MAAW,GAAG,CAAC;IA0BjE,OAAO,CAAC,WAAW;IAoBZ,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI;CAGlD"}

package/dist/sampledTelemetryHelper.js

@@ -0,0 +1,92 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SampledTelemetryHelper = void 0;
+const common_utils_1 = require("@fluidframework/common-utils");
+/**
+ * Helper class that executes a specified code block and writes an
+ * {@link @fluidframework/common-definitions#ITelemetryPerformanceEvent} to a specified logger every time a specified
+ * number of executions is reached (or when the class is disposed). The `duration` field in the telemetry event is
+ * the duration of the latest execution (sample) of the specified function. See the documentation of the
+ * `includeAggregateMetrics` parameter for additional details that can be included.
+ */
+class SampledTelemetryHelper {
+    /**
+     * @param eventBase -
+     * Custom properties to include in the telemetry performance event when it is written.
+     * @param logger -
+     * The logger to use to write the telemetry performance event.
+     * @param sampleThreshold -
+     * Telemetry performance events will be generated every time we hit this many executions of the code block.
+     * @param includeAggregateMetrics -
+     * If set to `true`, the telemetry performance event will include aggregated metrics (total duration, min duration,
+     * max duration) for all the executions in between generated events.
+     * @param perBucketProperties -
+     * Map of strings that represent different buckets (which can be specified when calling the 'measure' method), to
+     * properties which should be added to the telemetry event for that bucket. If a bucket being measured does not
+     * have an entry in this map, no additional properties will be added to its telemetry events. The following keys are
+     * reserved for use by this class: "duration", "count", "totalDuration", "minDuration", "maxDuration". If any of
+     * them is specified as a key in one of the ITelemetryProperties objects in this map, that key-value pair will be
+     * ignored.
+     */
+    constructor(eventBase, logger, sampleThreshold, includeAggregateMetrics = false, perBucketProperties = new Map()) {
+        this.eventBase = eventBase;
+        this.logger = logger;
+        this.sampleThreshold = sampleThreshold;
+        this.includeAggregateMetrics = includeAggregateMetrics;
+        this.perBucketProperties = perBucketProperties;
+        this.disposed = false;
+        this.measurementsMap = new Map();
+    }
+    /**
+     * @param codeToMeasure -
+     * The code to be executed and measured.
+     * @param bucket -
+     * A key to track executions of the code block separately. Each different value of this parameter has a separate
+     * set of executions and metrics tracked by the class. If no such distinction needs to be made, do not provide a
+     * value.
+     * @returns Whatever the passed-in code block returns.
+     */
+    measure(codeToMeasure, bucket = "") {
+        var _a, _b, _c;
+        const start = common_utils_1.performance.now();
+        const returnValue = codeToMeasure();
+        const duration = common_utils_1.performance.now() - start;
+        let m = this.measurementsMap.get(bucket);
+        if (m === undefined) {
+            m = { count: 0, duration: -1 };
+            this.measurementsMap.set(bucket, m);
+        }
+        m.count++;
+        m.duration = duration;
+        if (this.includeAggregateMetrics) {
+            m.totalDuration = ((_a = m.totalDuration) !== null && _a !== void 0 ? _a : 0) + duration;
+            m.minDuration = Math.min((_b = m.minDuration) !== null && _b !== void 0 ? _b : duration, duration);
+            m.maxDuration = Math.max((_c = m.maxDuration) !== null && _c !== void 0 ? _c : 0, duration);
+        }
+        if (m.count >= this.sampleThreshold) {
+            this.flushBucket(bucket);
+        }
+        return returnValue;
+    }
+    flushBucket(bucket) {
+        const measurements = this.measurementsMap.get(bucket);
+        if (measurements === undefined) {
+            return;
+        }
+        if (measurements.count !== 0) {
+            const bucketProperties = this.perBucketProperties.get(bucket);
+            const telemetryEvent = Object.assign(Object.assign(Object.assign({}, this.eventBase), bucketProperties), measurements);
+            this.logger.sendPerformanceEvent(telemetryEvent);
+            this.measurementsMap.delete(bucket);
+        }
+    }
+    dispose(error) {
+        this.measurementsMap.forEach((_, k) => this.flushBucket(k));
+    }
+}
+exports.SampledTelemetryHelper = SampledTelemetryHelper;
+//# sourceMappingURL=sampledTelemetryHelper.js.map

package/dist/sampledTelemetryHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampledTelemetryHelper.js","sourceRoot":"","sources":["../src/sampledTelemetryHelper.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AASH,+DAA2D;AAiC3D;;;;;;GAMG;AACF,MAAa,sBAAsB;IAKhC;;;;;;;;;;;;;;;;;OAiBG;IACH,YACqB,SAAiC,EACjC,MAAwB,EACxB,eAAuB,EACvB,0BAAmC,KAAK,EACxC,sBAAsB,IAAI,GAAG,EAAgC;QAJ7D,cAAS,GAAT,SAAS,CAAwB;QACjC,WAAM,GAAN,MAAM,CAAkB;QACxB,oBAAe,GAAf,eAAe,CAAQ;QACvB,4BAAuB,GAAvB,uBAAuB,CAAiB;QACxC,wBAAmB,GAAnB,mBAAmB,CAA0C;QA3BlF,aAAQ,GAAY,KAAK,CAAC;QAET,oBAAe,GAAG,IAAI,GAAG,EAAwB,CAAC;IA0BnE,CAAC;IAED;;;;;;;;OAQG;IACI,OAAO,CAAI,aAAsB,EAAE,SAAiB,EAAE;;QACzD,MAAM,KAAK,GAAG,0BAAW,CAAC,GAAG,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,aAAa,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,0BAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QAE3C,IAAI,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,SAAS,EAAE;YACjB,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;SACvC;QACD,CAAC,CAAC,KAAK,EAAE,CAAC;QACV,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAEtB,IAAI,IAAI,CAAC,uBAAuB,EAAE;YAC9B,CAAC,CAAC,aAAa,GAAG,CAAC,MAAA,CAAC,CAAC,aAAa,mCAAI,CAAC,CAAC,GAAG,QAAQ,CAAC;YACpD,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,MAAA,CAAC,CAAC,WAAW,mCAAI,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC9D,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,MAAA,CAAC,CAAC,WAAW,mCAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;SAC1D;QAED,IAAI,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,eAAe,EAAE;YACjC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;SAC5B;QAED,OAAO,WAAW,CAAC;IACvB,CAAC;IAEO,WAAW,CAAC,MAAc;QAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtD,IAAI,YAAY,KAAK,SAAS,EAAE;YAC5B,OAAO;SACV;QAED,IAAI,YAAY,CAAC,KAAK,KAAK,CAAC,EAAE;YAC1B,MAAM,gBAAgB,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAE9D,MAAM,cAAc,iDACb,IAAI,CAAC,SAAS,GACd,gBAAgB,GAChB,YAAY,CAClB,CAAC;YAEF,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,cAAc,CAAC,CAAC;YACjD,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;SACvC;IACL,CAAC;IAEM,OAAO,CAAC,KAAyB;QACpC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;CACJ;AAzFA,wDAyFA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport {\n    IDisposable,\n    ITelemetryGenericEvent,\n    ITelemetryLogger,\n    ITelemetryPerformanceEvent,\n    ITelemetryProperties,\n} from \"@fluidframework/common-definitions\";\nimport { performance } from \"@fluidframework/common-utils\";\n\ninterface Measurements {\n    // The names of the properties in this interface are the ones that will get stamped in the\n    // telemetry event, changes should be considered carefully. The optional properties should\n    // only be populated if 'includeAggregateMetrics' is true.\n\n    /**\n     * The duration of the latest execution.\n     */\n    duration: number;\n\n    /**\n     * The number of executions since the last time an event was generated.\n     */\n    count: number;\n\n    /**\n     * Total duration across all the executions since the last event was generated.\n     */\n    totalDuration?: number;\n\n    /**\n     * Min duration across all the executions since the last event was generated.\n     */\n    minDuration?: number;\n\n    /**\n     * Max duration across all the executions since the last event was generated.\n     */\n    maxDuration?: number;\n}\n\n/**\n * Helper class that executes a specified code block and writes an\n * {@link @fluidframework/common-definitions#ITelemetryPerformanceEvent} to a specified logger every time a specified\n * number of executions is reached (or when the class is disposed). The `duration` field in the telemetry event is\n * the duration of the latest execution (sample) of the specified function. See the documentation of the\n * `includeAggregateMetrics` parameter for additional details that can be included.\n */\n export class SampledTelemetryHelper implements IDisposable {\n    disposed: boolean = false;\n\n    private readonly measurementsMap = new Map<string, Measurements>();\n\n    /**\n     * @param eventBase -\n     * Custom properties to include in the telemetry performance event when it is written.\n     * @param logger -\n     * The logger to use to write the telemetry performance event.\n     * @param sampleThreshold -\n     * Telemetry performance events will be generated every time we hit this many executions of the code block.\n     * @param includeAggregateMetrics -\n     * If set to `true`, the telemetry performance event will include aggregated metrics (total duration, min duration,\n     * max duration) for all the executions in between generated events.\n     * @param perBucketProperties -\n     * Map of strings that represent different buckets (which can be specified when calling the 'measure' method), to\n     * properties which should be added to the telemetry event for that bucket. If a bucket being measured does not\n     * have an entry in this map, no additional properties will be added to its telemetry events. The following keys are\n     * reserved for use by this class: \"duration\", \"count\", \"totalDuration\", \"minDuration\", \"maxDuration\". If any of\n     * them is specified as a key in one of the ITelemetryProperties objects in this map, that key-value pair will be\n     * ignored.\n     */\n    public constructor(\n        private readonly eventBase: ITelemetryGenericEvent,\n        private readonly logger: ITelemetryLogger,\n        private readonly sampleThreshold: number,\n        private readonly includeAggregateMetrics: boolean = false,\n        private readonly perBucketProperties = new Map<string, ITelemetryProperties>()) {\n    }\n\n    /**\n     * @param codeToMeasure -\n     * The code to be executed and measured.\n     * @param bucket -\n     * A key to track executions of the code block separately. Each different value of this parameter has a separate\n     * set of executions and metrics tracked by the class. If no such distinction needs to be made, do not provide a\n     * value.\n     * @returns Whatever the passed-in code block returns.\n     */\n    public measure<T>(codeToMeasure: () => T, bucket: string = \"\"): T {\n        const start = performance.now();\n        const returnValue = codeToMeasure();\n        const duration = performance.now() - start;\n\n        let m = this.measurementsMap.get(bucket);\n        if (m === undefined) {\n            m = { count: 0, duration: -1 };\n            this.measurementsMap.set(bucket, m);\n        }\n        m.count++;\n        m.duration = duration;\n\n        if (this.includeAggregateMetrics) {\n            m.totalDuration = (m.totalDuration ?? 0) + duration;\n            m.minDuration = Math.min(m.minDuration ?? duration, duration);\n            m.maxDuration = Math.max(m.maxDuration ?? 0, duration);\n        }\n\n        if (m.count >= this.sampleThreshold) {\n            this.flushBucket(bucket);\n        }\n\n        return returnValue;\n    }\n\n    private flushBucket(bucket: string) {\n        const measurements = this.measurementsMap.get(bucket);\n        if (measurements === undefined) {\n            return;\n        }\n\n        if (measurements.count !== 0) {\n            const bucketProperties = this.perBucketProperties.get(bucket);\n\n            const telemetryEvent: ITelemetryPerformanceEvent = {\n                ...this.eventBase,\n                ...bucketProperties, // If the bucket doesn't exist and this is undefined, things work as expected\n                ...measurements,\n            };\n\n            this.logger.sendPerformanceEvent(telemetryEvent);\n            this.measurementsMap.delete(bucket);\n        }\n    }\n\n    public dispose(error?: Error | undefined): void {\n        this.measurementsMap.forEach((_, k) => this.flushBucket(k));\n    }\n}\n"]}

package/lib/index.d.ts

@@ -11,5 +11,6 @@ export * from "./logger";
 export * from "./mockLogger";
 export * from "./thresholdCounter";
 export * from "./utils";
+export * from "./sampledTelemetryHelper";
 export { MonitoringContext, IConfigProviderBase, sessionStorageConfigProvider, mixinMonitoringContext, IConfigProvider, ConfigTypes, loggerToMonitoringContext, } from "./config";
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iCAAiC,CAAC;AAChD,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,OAAO,EACH,iBAAiB,EACjB,mBAAmB,EACnB,4BAA4B,EAC5B,sBAAsB,EACtB,eAAe,EACf,WAAW,EACX,yBAAyB,GAC5B,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iCAAiC,CAAC;AAChD,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,0BAA0B,CAAC;AACzC,OAAO,EACH,iBAAiB,EACjB,mBAAmB,EACnB,4BAA4B,EAC5B,sBAAsB,EACtB,eAAe,EACf,WAAW,EACX,yBAAyB,GAC5B,MAAM,UAAU,CAAC"}

package/lib/index.js

@@ -11,5 +11,6 @@ export * from "./logger";
 export * from "./mockLogger";
 export * from "./thresholdCounter";
 export * from "./utils";
+export * from "./sampledTelemetryHelper";
 export { sessionStorageConfigProvider, mixinMonitoringContext, loggerToMonitoringContext, } from "./config";
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iCAAiC,CAAC;AAChD,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,OAAO,EAGH,4BAA4B,EAC5B,sBAAsB,EAGtB,yBAAyB,GAC5B,MAAM,UAAU,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\nexport * from \"./debugLogger\";\nexport * from \"./errorLogging\";\nexport * from \"./eventEmitterWithErrorHandling\";\nexport * from \"./events\";\nexport * from \"./fluidErrorBase\";\nexport * from \"./logger\";\nexport * from \"./mockLogger\";\nexport * from \"./thresholdCounter\";\nexport * from \"./utils\";\nexport {\n    MonitoringContext,\n    IConfigProviderBase,\n    sessionStorageConfigProvider,\n    mixinMonitoringContext,\n    IConfigProvider,\n    ConfigTypes,\n    loggerToMonitoringContext,\n} from \"./config\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iCAAiC,CAAC;AAChD,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,0BAA0B,CAAC;AACzC,OAAO,EAGH,4BAA4B,EAC5B,sBAAsB,EAGtB,yBAAyB,GAC5B,MAAM,UAAU,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\nexport * from \"./debugLogger\";\nexport * from \"./errorLogging\";\nexport * from \"./eventEmitterWithErrorHandling\";\nexport * from \"./events\";\nexport * from \"./fluidErrorBase\";\nexport * from \"./logger\";\nexport * from \"./mockLogger\";\nexport * from \"./thresholdCounter\";\nexport * from \"./utils\";\nexport * from \"./sampledTelemetryHelper\";\nexport {\n    MonitoringContext,\n    IConfigProviderBase,\n    sessionStorageConfigProvider,\n    mixinMonitoringContext,\n    IConfigProvider,\n    ConfigTypes,\n    loggerToMonitoringContext,\n} from \"./config\";\n"]}

package/lib/packageVersion.d.ts

@@ -5,5 +5,5 @@
  * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY
  */
 export declare const pkgName = "@fluidframework/telemetry-utils";
-export declare const pkgVersion = "1.2.6";
+export declare const pkgVersion = "1.3.0-100520";
 //# sourceMappingURL=packageVersion.d.ts.map

package/lib/packageVersion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"packageVersion.d.ts","sourceRoot":"","sources":["../src/packageVersion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,OAAO,oCAAoC,CAAC;AACzD,eAAO,MAAM,UAAU,UAAU,CAAC"}
+{"version":3,"file":"packageVersion.d.ts","sourceRoot":"","sources":["../src/packageVersion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,OAAO,oCAAoC,CAAC;AACzD,eAAO,MAAM,UAAU,iBAAiB,CAAC"}

package/lib/packageVersion.js

@@ -5,5 +5,5 @@
  * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY
  */
 export const pkgName = "@fluidframework/telemetry-utils";
-export const pkgVersion = "1.2.6";
+export const pkgVersion = "1.3.0-100520";
 //# sourceMappingURL=packageVersion.js.map

package/lib/packageVersion.js.map

@@ -1 +1 @@
-{"version":3,"file":"packageVersion.js","sourceRoot":"","sources":["../src/packageVersion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,iCAAiC,CAAC;AACzD,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n *\n * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY\n */\n\nexport const pkgName = \"@fluidframework/telemetry-utils\";\nexport const pkgVersion = \"1.2.6\";\n"]}
+{"version":3,"file":"packageVersion.js","sourceRoot":"","sources":["../src/packageVersion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,iCAAiC,CAAC;AACzD,MAAM,CAAC,MAAM,UAAU,GAAG,cAAc,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n *\n * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY\n */\n\nexport const pkgName = \"@fluidframework/telemetry-utils\";\nexport const pkgVersion = \"1.3.0-100520\";\n"]}

package/lib/sampledTelemetryHelper.d.ts

@@ -0,0 +1,53 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IDisposable, ITelemetryGenericEvent, ITelemetryLogger, ITelemetryProperties } from "@fluidframework/common-definitions";
+/**
+ * Helper class that executes a specified code block and writes an
+ * {@link @fluidframework/common-definitions#ITelemetryPerformanceEvent} to a specified logger every time a specified
+ * number of executions is reached (or when the class is disposed). The `duration` field in the telemetry event is
+ * the duration of the latest execution (sample) of the specified function. See the documentation of the
+ * `includeAggregateMetrics` parameter for additional details that can be included.
+ */
+export declare class SampledTelemetryHelper implements IDisposable {
+    private readonly eventBase;
+    private readonly logger;
+    private readonly sampleThreshold;
+    private readonly includeAggregateMetrics;
+    private readonly perBucketProperties;
+    disposed: boolean;
+    private readonly measurementsMap;
+    /**
+     * @param eventBase -
+     * Custom properties to include in the telemetry performance event when it is written.
+     * @param logger -
+     * The logger to use to write the telemetry performance event.
+     * @param sampleThreshold -
+     * Telemetry performance events will be generated every time we hit this many executions of the code block.
+     * @param includeAggregateMetrics -
+     * If set to `true`, the telemetry performance event will include aggregated metrics (total duration, min duration,
+     * max duration) for all the executions in between generated events.
+     * @param perBucketProperties -
+     * Map of strings that represent different buckets (which can be specified when calling the 'measure' method), to
+     * properties which should be added to the telemetry event for that bucket. If a bucket being measured does not
+     * have an entry in this map, no additional properties will be added to its telemetry events. The following keys are
+     * reserved for use by this class: "duration", "count", "totalDuration", "minDuration", "maxDuration". If any of
+     * them is specified as a key in one of the ITelemetryProperties objects in this map, that key-value pair will be
+     * ignored.
+     */
+    constructor(eventBase: ITelemetryGenericEvent, logger: ITelemetryLogger, sampleThreshold: number, includeAggregateMetrics?: boolean, perBucketProperties?: Map<string, ITelemetryProperties>);
+    /**
+     * @param codeToMeasure -
+     * The code to be executed and measured.
+     * @param bucket -
+     * A key to track executions of the code block separately. Each different value of this parameter has a separate
+     * set of executions and metrics tracked by the class. If no such distinction needs to be made, do not provide a
+     * value.
+     * @returns Whatever the passed-in code block returns.
+     */
+    measure<T>(codeToMeasure: () => T, bucket?: string): T;
+    private flushBucket;
+    dispose(error?: Error | undefined): void;
+}
+//# sourceMappingURL=sampledTelemetryHelper.d.ts.map

package/lib/sampledTelemetryHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampledTelemetryHelper.d.ts","sourceRoot":"","sources":["../src/sampledTelemetryHelper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACH,WAAW,EACX,sBAAsB,EACtB,gBAAgB,EAEhB,oBAAoB,EACvB,MAAM,oCAAoC,CAAC;AAkC5C;;;;;;GAMG;AACF,qBAAa,sBAAuB,YAAW,WAAW;IAwBnD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,uBAAuB;IACxC,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IA3BxC,QAAQ,EAAE,OAAO,CAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;IAEnE;;;;;;;;;;;;;;;;;OAiBG;gBAEkB,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,gBAAgB,EACxB,eAAe,EAAE,MAAM,EACvB,uBAAuB,GAAE,OAAe,EACxC,mBAAmB,oCAA0C;IAGlF;;;;;;;;OAQG;IACI,OAAO,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,MAAM,GAAE,MAAW,GAAG,CAAC;IA0BjE,OAAO,CAAC,WAAW;IAoBZ,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI;CAGlD"}

package/lib/sampledTelemetryHelper.js

@@ -0,0 +1,88 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { performance } from "@fluidframework/common-utils";
+/**
+ * Helper class that executes a specified code block and writes an
+ * {@link @fluidframework/common-definitions#ITelemetryPerformanceEvent} to a specified logger every time a specified
+ * number of executions is reached (or when the class is disposed). The `duration` field in the telemetry event is
+ * the duration of the latest execution (sample) of the specified function. See the documentation of the
+ * `includeAggregateMetrics` parameter for additional details that can be included.
+ */
+export class SampledTelemetryHelper {
+    /**
+     * @param eventBase -
+     * Custom properties to include in the telemetry performance event when it is written.
+     * @param logger -
+     * The logger to use to write the telemetry performance event.
+     * @param sampleThreshold -
+     * Telemetry performance events will be generated every time we hit this many executions of the code block.
+     * @param includeAggregateMetrics -
+     * If set to `true`, the telemetry performance event will include aggregated metrics (total duration, min duration,
+     * max duration) for all the executions in between generated events.
+     * @param perBucketProperties -
+     * Map of strings that represent different buckets (which can be specified when calling the 'measure' method), to
+     * properties which should be added to the telemetry event for that bucket. If a bucket being measured does not
+     * have an entry in this map, no additional properties will be added to its telemetry events. The following keys are
+     * reserved for use by this class: "duration", "count", "totalDuration", "minDuration", "maxDuration". If any of
+     * them is specified as a key in one of the ITelemetryProperties objects in this map, that key-value pair will be
+     * ignored.
+     */
+    constructor(eventBase, logger, sampleThreshold, includeAggregateMetrics = false, perBucketProperties = new Map()) {
+        this.eventBase = eventBase;
+        this.logger = logger;
+        this.sampleThreshold = sampleThreshold;
+        this.includeAggregateMetrics = includeAggregateMetrics;
+        this.perBucketProperties = perBucketProperties;
+        this.disposed = false;
+        this.measurementsMap = new Map();
+    }
+    /**
+     * @param codeToMeasure -
+     * The code to be executed and measured.
+     * @param bucket -
+     * A key to track executions of the code block separately. Each different value of this parameter has a separate
+     * set of executions and metrics tracked by the class. If no such distinction needs to be made, do not provide a
+     * value.
+     * @returns Whatever the passed-in code block returns.
+     */
+    measure(codeToMeasure, bucket = "") {
+        var _a, _b, _c;
+        const start = performance.now();
+        const returnValue = codeToMeasure();
+        const duration = performance.now() - start;
+        let m = this.measurementsMap.get(bucket);
+        if (m === undefined) {
+            m = { count: 0, duration: -1 };
+            this.measurementsMap.set(bucket, m);
+        }
+        m.count++;
+        m.duration = duration;
+        if (this.includeAggregateMetrics) {
+            m.totalDuration = ((_a = m.totalDuration) !== null && _a !== void 0 ? _a : 0) + duration;
+            m.minDuration = Math.min((_b = m.minDuration) !== null && _b !== void 0 ? _b : duration, duration);
+            m.maxDuration = Math.max((_c = m.maxDuration) !== null && _c !== void 0 ? _c : 0, duration);
+        }
+        if (m.count >= this.sampleThreshold) {
+            this.flushBucket(bucket);
+        }
+        return returnValue;
+    }
+    flushBucket(bucket) {
+        const measurements = this.measurementsMap.get(bucket);
+        if (measurements === undefined) {
+            return;
+        }
+        if (measurements.count !== 0) {
+            const bucketProperties = this.perBucketProperties.get(bucket);
+            const telemetryEvent = Object.assign(Object.assign(Object.assign({}, this.eventBase), bucketProperties), measurements);
+            this.logger.sendPerformanceEvent(telemetryEvent);
+            this.measurementsMap.delete(bucket);
+        }
+    }
+    dispose(error) {
+        this.measurementsMap.forEach((_, k) => this.flushBucket(k));
+    }
+}
+//# sourceMappingURL=sampledTelemetryHelper.js.map

package/lib/sampledTelemetryHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampledTelemetryHelper.js","sourceRoot":"","sources":["../src/sampledTelemetryHelper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAiC3D;;;;;;GAMG;AACF,MAAM,OAAO,sBAAsB;IAKhC;;;;;;;;;;;;;;;;;OAiBG;IACH,YACqB,SAAiC,EACjC,MAAwB,EACxB,eAAuB,EACvB,0BAAmC,KAAK,EACxC,sBAAsB,IAAI,GAAG,EAAgC;QAJ7D,cAAS,GAAT,SAAS,CAAwB;QACjC,WAAM,GAAN,MAAM,CAAkB;QACxB,oBAAe,GAAf,eAAe,CAAQ;QACvB,4BAAuB,GAAvB,uBAAuB,CAAiB;QACxC,wBAAmB,GAAnB,mBAAmB,CAA0C;QA3BlF,aAAQ,GAAY,KAAK,CAAC;QAET,oBAAe,GAAG,IAAI,GAAG,EAAwB,CAAC;IA0BnE,CAAC;IAED;;;;;;;;OAQG;IACI,OAAO,CAAI,aAAsB,EAAE,SAAiB,EAAE;;QACzD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,aAAa,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QAE3C,IAAI,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,SAAS,EAAE;YACjB,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;SACvC;QACD,CAAC,CAAC,KAAK,EAAE,CAAC;QACV,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAEtB,IAAI,IAAI,CAAC,uBAAuB,EAAE;YAC9B,CAAC,CAAC,aAAa,GAAG,CAAC,MAAA,CAAC,CAAC,aAAa,mCAAI,CAAC,CAAC,GAAG,QAAQ,CAAC;YACpD,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,MAAA,CAAC,CAAC,WAAW,mCAAI,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC9D,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,MAAA,CAAC,CAAC,WAAW,mCAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;SAC1D;QAED,IAAI,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,eAAe,EAAE;YACjC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;SAC5B;QAED,OAAO,WAAW,CAAC;IACvB,CAAC;IAEO,WAAW,CAAC,MAAc;QAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtD,IAAI,YAAY,KAAK,SAAS,EAAE;YAC5B,OAAO;SACV;QAED,IAAI,YAAY,CAAC,KAAK,KAAK,CAAC,EAAE;YAC1B,MAAM,gBAAgB,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAE9D,MAAM,cAAc,iDACb,IAAI,CAAC,SAAS,GACd,gBAAgB,GAChB,YAAY,CAClB,CAAC;YAEF,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,cAAc,CAAC,CAAC;YACjD,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;SACvC;IACL,CAAC;IAEM,OAAO,CAAC,KAAyB;QACpC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;CACJ","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport {\n    IDisposable,\n    ITelemetryGenericEvent,\n    ITelemetryLogger,\n    ITelemetryPerformanceEvent,\n    ITelemetryProperties,\n} from \"@fluidframework/common-definitions\";\nimport { performance } from \"@fluidframework/common-utils\";\n\ninterface Measurements {\n    // The names of the properties in this interface are the ones that will get stamped in the\n    // telemetry event, changes should be considered carefully. The optional properties should\n    // only be populated if 'includeAggregateMetrics' is true.\n\n    /**\n     * The duration of the latest execution.\n     */\n    duration: number;\n\n    /**\n     * The number of executions since the last time an event was generated.\n     */\n    count: number;\n\n    /**\n     * Total duration across all the executions since the last event was generated.\n     */\n    totalDuration?: number;\n\n    /**\n     * Min duration across all the executions since the last event was generated.\n     */\n    minDuration?: number;\n\n    /**\n     * Max duration across all the executions since the last event was generated.\n     */\n    maxDuration?: number;\n}\n\n/**\n * Helper class that executes a specified code block and writes an\n * {@link @fluidframework/common-definitions#ITelemetryPerformanceEvent} to a specified logger every time a specified\n * number of executions is reached (or when the class is disposed). The `duration` field in the telemetry event is\n * the duration of the latest execution (sample) of the specified function. See the documentation of the\n * `includeAggregateMetrics` parameter for additional details that can be included.\n */\n export class SampledTelemetryHelper implements IDisposable {\n    disposed: boolean = false;\n\n    private readonly measurementsMap = new Map<string, Measurements>();\n\n    /**\n     * @param eventBase -\n     * Custom properties to include in the telemetry performance event when it is written.\n     * @param logger -\n     * The logger to use to write the telemetry performance event.\n     * @param sampleThreshold -\n     * Telemetry performance events will be generated every time we hit this many executions of the code block.\n     * @param includeAggregateMetrics -\n     * If set to `true`, the telemetry performance event will include aggregated metrics (total duration, min duration,\n     * max duration) for all the executions in between generated events.\n     * @param perBucketProperties -\n     * Map of strings that represent different buckets (which can be specified when calling the 'measure' method), to\n     * properties which should be added to the telemetry event for that bucket. If a bucket being measured does not\n     * have an entry in this map, no additional properties will be added to its telemetry events. The following keys are\n     * reserved for use by this class: \"duration\", \"count\", \"totalDuration\", \"minDuration\", \"maxDuration\". If any of\n     * them is specified as a key in one of the ITelemetryProperties objects in this map, that key-value pair will be\n     * ignored.\n     */\n    public constructor(\n        private readonly eventBase: ITelemetryGenericEvent,\n        private readonly logger: ITelemetryLogger,\n        private readonly sampleThreshold: number,\n        private readonly includeAggregateMetrics: boolean = false,\n        private readonly perBucketProperties = new Map<string, ITelemetryProperties>()) {\n    }\n\n    /**\n     * @param codeToMeasure -\n     * The code to be executed and measured.\n     * @param bucket -\n     * A key to track executions of the code block separately. Each different value of this parameter has a separate\n     * set of executions and metrics tracked by the class. If no such distinction needs to be made, do not provide a\n     * value.\n     * @returns Whatever the passed-in code block returns.\n     */\n    public measure<T>(codeToMeasure: () => T, bucket: string = \"\"): T {\n        const start = performance.now();\n        const returnValue = codeToMeasure();\n        const duration = performance.now() - start;\n\n        let m = this.measurementsMap.get(bucket);\n        if (m === undefined) {\n            m = { count: 0, duration: -1 };\n            this.measurementsMap.set(bucket, m);\n        }\n        m.count++;\n        m.duration = duration;\n\n        if (this.includeAggregateMetrics) {\n            m.totalDuration = (m.totalDuration ?? 0) + duration;\n            m.minDuration = Math.min(m.minDuration ?? duration, duration);\n            m.maxDuration = Math.max(m.maxDuration ?? 0, duration);\n        }\n\n        if (m.count >= this.sampleThreshold) {\n            this.flushBucket(bucket);\n        }\n\n        return returnValue;\n    }\n\n    private flushBucket(bucket: string) {\n        const measurements = this.measurementsMap.get(bucket);\n        if (measurements === undefined) {\n            return;\n        }\n\n        if (measurements.count !== 0) {\n            const bucketProperties = this.perBucketProperties.get(bucket);\n\n            const telemetryEvent: ITelemetryPerformanceEvent = {\n                ...this.eventBase,\n                ...bucketProperties, // If the bucket doesn't exist and this is undefined, things work as expected\n                ...measurements,\n            };\n\n            this.logger.sendPerformanceEvent(telemetryEvent);\n            this.measurementsMap.delete(bucket);\n        }\n    }\n\n    public dispose(error?: Error | undefined): void {\n        this.measurementsMap.forEach((_, k) => this.flushBucket(k));\n    }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/telemetry-utils",
-  "version": "1.2.6",
+  "version": "1.3.0-100520",
   "description": "Collection of telemetry relates utilities for Fluid",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -74,8 +74,8 @@
     "@fluidframework/build-common": "^0.24.0",
     "@fluidframework/build-tools": "^0.2.74327",
     "@fluidframework/eslint-config-fluid": "^0.28.2000",
-    "@fluidframework/mocha-test-setup": "^1.2.6",
-    "@fluidframework/telemetry-utils-previous": "npm:@fluidframework/telemetry-utils@1.2.1",
+    "@fluidframework/mocha-test-setup": "1.3.0-100520",
+    "@fluidframework/telemetry-utils-previous": "npm:@fluidframework/telemetry-utils@^1.2.0",
     "@microsoft/api-extractor": "^7.22.2",
     "@rushstack/eslint-config": "^2.5.1",
     "@types/debug": "^4.1.5",
@@ -93,7 +93,7 @@
     "typescript": "~4.5.5"
   },
   "typeValidation": {
-    "version": "1.2.2",
+    "version": "1.3.0",
     "broken": {}
   }
 }

package/src/index.ts

@@ -11,6 +11,7 @@ export * from "./logger";
 export * from "./mockLogger";
 export * from "./thresholdCounter";
 export * from "./utils";
+export * from "./sampledTelemetryHelper";
 export {
     MonitoringContext,
     IConfigProviderBase,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/telemetry-utils";
-export const pkgVersion = "1.2.6";
+export const pkgVersion = "1.3.0-100520";

package/src/sampledTelemetryHelper.ts

@@ -0,0 +1,142 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    IDisposable,
+    ITelemetryGenericEvent,
+    ITelemetryLogger,
+    ITelemetryPerformanceEvent,
+    ITelemetryProperties,
+} from "@fluidframework/common-definitions";
+import { performance } from "@fluidframework/common-utils";
+
+interface Measurements {
+    // The names of the properties in this interface are the ones that will get stamped in the
+    // telemetry event, changes should be considered carefully. The optional properties should
+    // only be populated if 'includeAggregateMetrics' is true.
+
+    /**
+     * The duration of the latest execution.
+     */
+    duration: number;
+
+    /**
+     * The number of executions since the last time an event was generated.
+     */
+    count: number;
+
+    /**
+     * Total duration across all the executions since the last event was generated.
+     */
+    totalDuration?: number;
+
+    /**
+     * Min duration across all the executions since the last event was generated.
+     */
+    minDuration?: number;
+
+    /**
+     * Max duration across all the executions since the last event was generated.
+     */
+    maxDuration?: number;
+}
+
+/**
+ * Helper class that executes a specified code block and writes an
+ * {@link @fluidframework/common-definitions#ITelemetryPerformanceEvent} to a specified logger every time a specified
+ * number of executions is reached (or when the class is disposed). The `duration` field in the telemetry event is
+ * the duration of the latest execution (sample) of the specified function. See the documentation of the
+ * `includeAggregateMetrics` parameter for additional details that can be included.
+ */
+ export class SampledTelemetryHelper implements IDisposable {
+    disposed: boolean = false;
+
+    private readonly measurementsMap = new Map<string, Measurements>();
+
+    /**
+     * @param eventBase -
+     * Custom properties to include in the telemetry performance event when it is written.
+     * @param logger -
+     * The logger to use to write the telemetry performance event.
+     * @param sampleThreshold -
+     * Telemetry performance events will be generated every time we hit this many executions of the code block.
+     * @param includeAggregateMetrics -
+     * If set to `true`, the telemetry performance event will include aggregated metrics (total duration, min duration,
+     * max duration) for all the executions in between generated events.
+     * @param perBucketProperties -
+     * Map of strings that represent different buckets (which can be specified when calling the 'measure' method), to
+     * properties which should be added to the telemetry event for that bucket. If a bucket being measured does not
+     * have an entry in this map, no additional properties will be added to its telemetry events. The following keys are
+     * reserved for use by this class: "duration", "count", "totalDuration", "minDuration", "maxDuration". If any of
+     * them is specified as a key in one of the ITelemetryProperties objects in this map, that key-value pair will be
+     * ignored.
+     */
+    public constructor(
+        private readonly eventBase: ITelemetryGenericEvent,
+        private readonly logger: ITelemetryLogger,
+        private readonly sampleThreshold: number,
+        private readonly includeAggregateMetrics: boolean = false,
+        private readonly perBucketProperties = new Map<string, ITelemetryProperties>()) {
+    }
+
+    /**
+     * @param codeToMeasure -
+     * The code to be executed and measured.
+     * @param bucket -
+     * A key to track executions of the code block separately. Each different value of this parameter has a separate
+     * set of executions and metrics tracked by the class. If no such distinction needs to be made, do not provide a
+     * value.
+     * @returns Whatever the passed-in code block returns.
+     */
+    public measure<T>(codeToMeasure: () => T, bucket: string = ""): T {
+        const start = performance.now();
+        const returnValue = codeToMeasure();
+        const duration = performance.now() - start;
+
+        let m = this.measurementsMap.get(bucket);
+        if (m === undefined) {
+            m = { count: 0, duration: -1 };
+            this.measurementsMap.set(bucket, m);
+        }
+        m.count++;
+        m.duration = duration;
+
+        if (this.includeAggregateMetrics) {
+            m.totalDuration = (m.totalDuration ?? 0) + duration;
+            m.minDuration = Math.min(m.minDuration ?? duration, duration);
+            m.maxDuration = Math.max(m.maxDuration ?? 0, duration);
+        }
+
+        if (m.count >= this.sampleThreshold) {
+            this.flushBucket(bucket);
+        }
+
+        return returnValue;
+    }
+
+    private flushBucket(bucket: string) {
+        const measurements = this.measurementsMap.get(bucket);
+        if (measurements === undefined) {
+            return;
+        }
+
+        if (measurements.count !== 0) {
+            const bucketProperties = this.perBucketProperties.get(bucket);
+
+            const telemetryEvent: ITelemetryPerformanceEvent = {
+                ...this.eventBase,
+                ...bucketProperties, // If the bucket doesn't exist and this is undefined, things work as expected
+                ...measurements,
+            };
+
+            this.logger.sendPerformanceEvent(telemetryEvent);
+            this.measurementsMap.delete(bucket);
+        }
+    }
+
+    public dispose(error?: Error | undefined): void {
+        this.measurementsMap.forEach((_, k) => this.flushBucket(k));
+    }
+}