@fluidframework/telemetry-utils 1.2.2 → 2.0.0-internal.1.0.0.81589

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.2",
+  "version": "2.0.0-internal.1.0.0.81589",
   "description": "Collection of telemetry relates utilities for Fluid",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -72,10 +72,10 @@
   },
   "devDependencies": {
     "@fluidframework/build-common": "^0.24.0",
-    "@fluidframework/build-tools": "^0.2.74327",
+    "@fluidframework/build-tools": "^0.3.0-0",
     "@fluidframework/eslint-config-fluid": "^0.28.2000",
-    "@fluidframework/mocha-test-setup": "^1.2.2",
-    "@fluidframework/telemetry-utils-previous": "npm:@fluidframework/telemetry-utils@1.2.1",
+    "@fluidframework/mocha-test-setup": "2.0.0-internal.1.0.0.81589",
+    "@fluidframework/telemetry-utils-previous": "npm:@fluidframework/telemetry-utils@^1.0.0",
     "@microsoft/api-extractor": "^7.22.2",
     "@rushstack/eslint-config": "^2.5.1",
     "@types/debug": "^4.1.5",
@@ -93,7 +93,15 @@
     "typescript": "~4.5.5"
   },
   "typeValidation": {
-    "version": "1.2.2",
-    "broken": {}
+    "version": "2.0.0",
+    "broken": {
+      "RemovedFunctionDeclaration_originatedAsExternalError": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "EnumDeclaration_TelemetryDataTag": {
+        "forwardCompat": false
+      }
+    }
   }
 }

package/src/errorLogging.ts

@@ -8,6 +8,7 @@ import {
     ITaggedTelemetryPropertyType,
     ITelemetryLogger,
     ITelemetryProperties,
+    TelemetryEventPropertyType,
 } from "@fluidframework/common-definitions";
 import { v4 as uuid } from "uuid";
 import {
@@ -262,9 +263,39 @@ export function isExternalError(e: any): boolean {
  * Type guard to identify if a particular value (loosely) appears to be a tagged telemetry property
  */
 export function isTaggedTelemetryPropertyValue(x: any): x is ITaggedTelemetryPropertyType {
-    return (typeof (x?.value) !== "object" && typeof (x?.tag) === "string");
+    return typeof (x?.tag) === "string";
 }
 
+/**
+ * Filter serializable telemetry properties
+ * @param x - any telemetry prop
+ * @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: any, key: string): TelemetryEventPropertyType {
+    if (Array.isArray(x) && x.every((val) => isTelemetryEventPropertyValue(val))) {
+        return JSON.stringify(x);
+    }
+    if (isTelemetryEventPropertyValue(x)) {
+        return x;
+    }
+    // We don't support logging arbitrary objects
+    console.error(`UnSupported Format of Logging Error Property for key ${key}:`, x);
+    return "REDACTED (arbitrary object)";
+}
+
+// checking type of x, returns false if x is null
+function isTelemetryEventPropertyValue(x: any): x is TelemetryEventPropertyType {
+    switch (typeof x) {
+        case "string":
+        case "number":
+        case "boolean":
+        case "undefined":
+            return true;
+        default:
+            return false;
+    }
+}
 /**
  * Walk an object's enumerable properties to find those fit for telemetry.
  */
@@ -275,22 +306,15 @@ function getValidTelemetryProps(obj: any, keysToOmit: Set<string>): ITelemetryPr
             continue;
         }
         const val = obj[key];
-        switch (typeof val) {
-            case "string":
-            case "number":
-            case "boolean":
-            case "undefined":
-                props[key] = val;
-                break;
-            default: {
-                if (isTaggedTelemetryPropertyValue(val)) {
-                    props[key] = val;
-                } else {
-                    // We don't support logging arbitrary objects
-                    props[key] = "REDACTED (arbitrary object)";
-                }
-                break;
-            }
+
+        // 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);
         }
     }
     return props;

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/logger.ts

@@ -32,11 +32,6 @@ import {
  * Please do not modify existing entries for backwards compatibility.
  */
 export enum TelemetryDataTag {
-    /**
-     * Data containing terms from code packages that may have been dynamically loaded
-     * @deprecated 1.0, will be removed in next release (see issue #6603). Use `TelemetryDataTag.CodeArtifact` instead.
-     */
-    PackageData = "PackageData",
     /** Data containing terms or IDs from code packages that may have been dynamically loaded */
     CodeArtifact = "CodeArtifact",
     /** Personal data of a variety of classifications that pertains to the user */
@@ -249,8 +244,9 @@ export abstract class TelemetryLogger implements ITelemetryLogger {
                     // No tag means we can log plainly
                     newEvent[key] = value;
                     break;
-                case TelemetryDataTag.PackageData:
-                    // For Microsoft applications, PackageData is safe for now
+                case "PackageData": // For back-compat
+                case TelemetryDataTag.CodeArtifact:
+                    // For Microsoft applications, CodeArtifact is safe for now
                     // (we don't load 3P code in 1P apps)
                     newEvent[key] = value;
                     break;

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/telemetry-utils";
-export const pkgVersion = "1.2.2";
+export const pkgVersion = "2.0.0-internal.1.0.0.81589";

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));
+    }
+}