@fluidframework/telemetry-utils 2.0.0-dev-rc.5.0.0.271717 → 2.0.0-dev-rc.5.0.0.272251

package/src/logger.ts

@@ -5,11 +5,11 @@
 
 import { performance } from "@fluid-internal/client-utils";
 import {
-	ITelemetryBaseEvent,
-	ITelemetryBaseLogger,
+	type ITelemetryBaseEvent,
+	type ITelemetryBaseLogger,
 	LogLevel,
-	Tagged,
-	TelemetryBaseEventPropertyType,
+	type Tagged,
+	type TelemetryBaseEventPropertyType,
 } from "@fluidframework/core-interfaces";
 
 import {
@@ -23,8 +23,8 @@ import {
 	isILoggingError,
 	isTaggedTelemetryPropertyValue,
 } from "./errorLogging.js";
-import {
-	type ITelemetryErrorEventExt,
+import type {
+	ITelemetryErrorEventExt,
 	ITelemetryEventExt,
 	ITelemetryGenericEventExt,
 	ITelemetryLoggerExt,
@@ -60,9 +60,10 @@ export type TelemetryEventPropertyTypes = ITelemetryPropertiesExt[string];
 /**
  * @alpha
  */
-export interface ITelemetryLoggerPropertyBag {
-	[index: string]: TelemetryEventPropertyTypes | (() => TelemetryEventPropertyTypes);
-}
+export type ITelemetryLoggerPropertyBag = Record<
+	string,
+	TelemetryEventPropertyTypes | (() => TelemetryEventPropertyTypes)
+>;
 
 /**
  * @alpha
@@ -533,7 +534,7 @@ export class MultiSinkLogger extends TelemetryLogger {
 	 * @param loggers - The list of loggers to use as sinks
 	 * @param tryInheritProperties - Will attempted to copy those loggers properties to this loggers if they are of a known type e.g. one from this package
 	 */
-	constructor(
+	public constructor(
 		namespace?: string,
 		properties?: ITelemetryLoggerPropertyBags,
 		loggers: ITelemetryBaseLogger[] = [],

package/src/mockLogger.ts

@@ -4,36 +4,51 @@
  */
 
 import {
-	ITelemetryBaseEvent,
-	ITelemetryBaseLogger,
+	type ITelemetryBaseEvent,
+	type ITelemetryBaseLogger,
 	LogLevel,
 } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 
 import { createChildLogger } from "./logger.js";
-import { ITelemetryLoggerExt, ITelemetryPropertiesExt } from "./telemetryTypes.js";
+import type { ITelemetryLoggerExt, ITelemetryPropertiesExt } from "./telemetryTypes.js";
 
 /**
- * The MockLogger records events sent to it, and then can walk back over those events
- * searching for a set of expected events to match against the logged events.
+ * Mock {@link @fluidframework/core-interfaces#ITelemetryBaseLogger} implementation.
+ *
+ * Records events sent to it, and then can walk back over those events, searching for a set of expected events to
+ * match against the logged events.
  *
  * @alpha
  */
 export class MockLogger implements ITelemetryBaseLogger {
-	events: ITelemetryBaseEvent[] = [];
+	// TODO: don't expose mutability to external consumers
+	public events: ITelemetryBaseEvent[] = [];
 
-	constructor(public readonly minLogLevel?: LogLevel) {}
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseLogger.minLogLevel}
+	 */
+	public readonly minLogLevel: LogLevel;
+
+	public constructor(minLogLevel?: LogLevel) {
+		this.minLogLevel = minLogLevel ?? LogLevel.default;
+	}
 
-	clear(): void {
+	public clear(): void {
 		this.events = [];
 	}
 
-	toTelemetryLogger(): ITelemetryLoggerExt {
+	public toTelemetryLogger(): ITelemetryLoggerExt {
 		return createChildLogger({ logger: this });
 	}
 
-	send(event: ITelemetryBaseEvent): void {
-		this.events.push(event);
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseLogger.send}
+	 */
+	public send(event: ITelemetryBaseEvent, logLevel?: LogLevel): void {
+		if (logLevel ?? LogLevel.default >= this.minLogLevel) {
+			this.events.push(event);
+		}
 	}
 
 	/**
@@ -44,7 +59,7 @@ export class MockLogger implements ITelemetryBaseLogger {
 	 * These event objects may be subsets of the logged events.
 	 * Note: category is omitted from the type because it's usually uninteresting and tedious to type.
 	 */
-	matchEvents(
+	public matchEvents(
 		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
 		inlineDetailsProp: boolean = false,
 	): boolean {
@@ -60,7 +75,7 @@ export class MockLogger implements ITelemetryBaseLogger {
 	/**
 	 * Asserts that matchEvents is true, and prints the actual/expected output if not.
 	 */
-	assertMatch(
+	public assertMatch(
 		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
 		message?: string,
 		inlineDetailsProp: boolean = false,
@@ -85,7 +100,7 @@ ${JSON.stringify(actualEvents)}`);
 	 * Note: category is omitted from the type because it's usually uninteresting and tedious to type.
 	 * @returns if any of the expected events is found.
 	 */
-	matchAnyEvent(
+	public matchAnyEvent(
 		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
 		inlineDetailsProp: boolean = false,
 	): boolean {
@@ -99,7 +114,7 @@ ${JSON.stringify(actualEvents)}`);
 	/**
 	 * Asserts that matchAnyEvent is true, and prints the actual/expected output if not.
 	 */
-	assertMatchAny(
+	public assertMatchAny(
 		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
 		message?: string,
 		inlineDetailsProp: boolean = false,
@@ -123,7 +138,7 @@ ${JSON.stringify(actualEvents)}`);
 	 * These event objects may be subsets of the logged events.
 	 * Note: category is omitted from the type because it's usually uninteresting and tedious to type.
 	 */
-	matchEventStrict(
+	public matchEventStrict(
 		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
 		inlineDetailsProp: boolean = false,
 	): boolean {
@@ -136,7 +151,7 @@ ${JSON.stringify(actualEvents)}`);
 	/**
 	 * Asserts that matchEvents is true, and prints the actual/expected output if not
 	 */
-	assertMatchStrict(
+	public assertMatchStrict(
 		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
 		message?: string,
 		inlineDetailsProp: boolean = false,
@@ -155,7 +170,7 @@ ${JSON.stringify(actualEvents)}`);
 	/**
 	 * Asserts that matchAnyEvent is false for the given events, and prints the actual/expected output if not
 	 */
-	assertMatchNone(
+	public assertMatchNone(
 		disallowedEvents: Omit<ITelemetryBaseEvent, "category">[],
 		message?: string,
 		inlineDetailsProp: boolean = false,
@@ -187,7 +202,7 @@ ${JSON.stringify(actualEvents)}`);
 		}
 
 		// Remove the events so far; next call will just compare subsequent events from here
-		this.events = [];
+		this.clear();
 
 		// Return the count of matched events.
 		return iExpectedEvent;
@@ -208,7 +223,6 @@ ${JSON.stringify(actualEvents)}`);
 		if (inlineDetailsProp && details !== undefined) {
 			assert(
 				typeof details === "string",
-				// eslint-disable-next-line unicorn/numeric-separators-style
 				0x6c9 /* Details should a JSON stringified string if inlineDetailsProp is true */,
 			);
 			// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment

package/src/sampledTelemetryHelper.ts

@@ -6,10 +6,10 @@
 import { performance } from "@fluid-internal/client-utils";
 import type { IDisposable, ITelemetryBaseProperties } from "@fluidframework/core-interfaces";
 
-import {
-	type ITelemetryGenericEventExt,
+import type {
+	ITelemetryGenericEventExt,
 	ITelemetryLoggerExt,
-	type ITelemetryPerformanceEventExt,
+	ITelemetryPerformanceEventExt,
 } from "./telemetryTypes.js";
 
 /**
@@ -58,7 +58,14 @@ interface Measurements {
  * @internal
  */
 export class SampledTelemetryHelper implements IDisposable {
-	disposed: boolean = false;
+	private _disposed: boolean = false;
+
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#IDisposable.disposed}
+	 */
+	public get disposed(): boolean {
+		return this._disposed;
+	}
 
 	private readonly measurementsMap = new Map<string, Measurements>();
 
@@ -145,6 +152,9 @@ export class SampledTelemetryHelper implements IDisposable {
 	}
 
 	public dispose(error?: Error | undefined): void {
-		for (const [k] of this.measurementsMap.entries()) this.flushBucket(k);
+		for (const [k] of this.measurementsMap.entries()) {
+			this.flushBucket(k);
+		}
+		this._disposed = true;
 	}
 }

package/src/telemetryTypes.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryBaseLogger, LogLevel, Tagged } from "@fluidframework/core-interfaces";
+import type { ITelemetryBaseLogger, LogLevel, Tagged } from "@fluidframework/core-interfaces";
 
 /**
  * The categories FF uses when instrumenting the code.
@@ -31,10 +31,7 @@ export type TelemetryEventPropertyTypeExt =
 	| boolean
 	| undefined
 	| (string | number | boolean)[]
-	| {
-			[key: string]: // Flat objects can have the same properties as the event itself
-			string | number | boolean | undefined | (string | number | boolean)[];
-	  };
+	| Record<string, string | number | boolean | undefined | (string | number | boolean)[]>;
 
 /**
  * A property to be logged to telemetry containing both the value and a tag. Tags are generic strings that can be used
@@ -53,9 +50,10 @@ export interface ITaggedTelemetryPropertyTypeExt {
  * JSON-serializable properties, which will be logged with telemetry.
  * @alpha
  */
-export interface ITelemetryPropertiesExt {
-	[index: string]: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>;
-}
+export type ITelemetryPropertiesExt = Record<
+	string,
+	TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>
+>;
 
 /**
  * Interface for logging telemetry statements.
@@ -66,7 +64,14 @@ export interface ITelemetryPropertiesExt {
  * @internal
  */
 export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseEvent.category}
+	 */
 	category: string;
+
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseEvent.eventName}
+	 */
 	eventName: string;
 }
 
@@ -76,7 +81,15 @@ export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
  * @alpha
  */
 export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseEvent.eventName}
+	 */
 	eventName: string;
+
+	/**
+	 * Optional event {@link @fluidframework/core-interfaces#ITelemetryBaseEvent.category}.
+	 * @defaultValue "generic"
+	 */
 	category?: TelemetryEventCategory;
 }
 
@@ -86,6 +99,9 @@ export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
  * @alpha
  */
 export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseEvent.eventName}
+	 */
 	eventName: string;
 }
 
@@ -95,7 +111,10 @@ export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
  * @alpha
  */
 export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
-	duration?: number; // Duration of event (optional)
+	/**
+	 * Duration of event (optional)
+	 */
+	duration?: number;
 }
 
 /**
@@ -108,10 +127,10 @@ export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt
  */
 export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
 	/**
-	 * Send information telemetry event
-	 * @param event - Event to send
-	 * @param error - optional error object to log
-	 * @param logLevel - optional level of the log.
+	 * Send an information telemetry event.
+	 * @param event - Event to send.
+	 * @param error - Optional error object to log.
+	 * @param logLevel - Optional level of the log. Default: {@link @fluidframework/core-interfaces#LogLevel.default}.
 	 */
 	sendTelemetryEvent(
 		event: ITelemetryGenericEventExt,
@@ -120,17 +139,17 @@ export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
 	): void;
 
 	/**
-	 * Send error telemetry event
-	 * @param event - Event to send
-	 * @param error - optional error object to log
+	 * Send an error telemetry event.
+	 * @param event - Event to send.
+	 * @param error - Optional error object to log.
 	 */
 	sendErrorEvent(event: ITelemetryErrorEventExt, error?: unknown): void;
 
 	/**
-	 * Send performance telemetry event
+	 * Send a performance telemetry event.
 	 * @param event - Event to send
-	 * @param error - optional error object to log
-	 * @param logLevel - optional level of the log.
+	 * @param error - Optional error object to log.
+	 * @param logLevel - Optional level of the log. Default: {@link @fluidframework/core-interfaces#LogLevel.default}.
 	 */
 	sendPerformanceEvent(
 		event: ITelemetryPerformanceEventExt,

package/src/thresholdCounter.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryLoggerExt } from "./telemetryTypes.js";
+import type { ITelemetryLoggerExt } from "./telemetryTypes.js";
 
 /**
  * Utility counter which will send event only if the provided value is above a configured threshold.

package/src/utils.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryBaseEvent } from "@fluidframework/core-interfaces";
+import type { ITelemetryBaseEvent } from "@fluidframework/core-interfaces";
 
 import { loggerToMonitoringContext } from "./config.js";
-import { ITelemetryGenericEventExt, ITelemetryLoggerExt } from "./telemetryTypes.js";
+import type { ITelemetryGenericEventExt, ITelemetryLoggerExt } from "./telemetryTypes.js";
 
 /**
  * An object that contains a callback used in conjunction with the {@link createSampledLogger} utility function to provide custom logic for sampling events.

package/tsdoc.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+	"extends": ["../../../common/build/build-common/tsdoc-base.json"]
+}