@fluidframework/telemetry-utils 2.0.0-internal.7.3.0 → 2.0.0-internal.7.4.1

package/src/logger.ts

@@ -40,9 +40,13 @@ export interface Memory {
 export interface PerformanceWithMemory extends IsomorphicPerformance {
 	readonly memory: Memory;
 }
+
 /**
  * Broad classifications to be applied to individual properties as they're prepared to be logged to telemetry.
- * Please do not modify existing entries for backwards compatibility.
+ *
+ * @privateRemarks Please do not modify existing entries, to maintain backwards compatibility.
+ *
+ * @internal
  */
 export enum TelemetryDataTag {
 	/**
@@ -55,11 +59,21 @@ export enum TelemetryDataTag {
 	UserData = "UserData",
 }
 
+/**
+ * @internal
+ */
 export type TelemetryEventPropertyTypes = ITelemetryBaseProperties[string];
 
+/**
+ * @internal
+ */
 export interface ITelemetryLoggerPropertyBag {
 	[index: string]: TelemetryEventPropertyTypes | (() => TelemetryEventPropertyTypes);
 }
+
+/**
+ * @internal
+ */
 export interface ITelemetryLoggerPropertyBags {
 	all?: ITelemetryLoggerPropertyBag;
 	error?: ITelemetryLoggerPropertyBag;
@@ -67,9 +81,13 @@ export interface ITelemetryLoggerPropertyBags {
 
 /**
  * Attempts to parse number from string.
- * If fails,returns original string.
+ * If it fails, it will return the original string.
+ *
+ * @remarks
  * Used to make telemetry data typed (and support math operations, like comparison),
- * in places where we do expect numbers (like contentsize/duration property in http header)
+ * in places where we do expect numbers (like contentsize/duration property in http header).
+ *
+ * @internal
  */
 // eslint-disable-next-line @rushstack/no-new-null
 export function numberFromString(str: string | null | undefined): string | number | undefined {
@@ -80,10 +98,19 @@ export function numberFromString(str: string | null | undefined): string | numbe
 	return Number.isNaN(num) ? str : num;
 }
 
+// TODO: add docs
+// eslint-disable-next-line jsdoc/require-description
+/**
+ * @internal
+ */
 export function formatTick(tick: number): number {
 	return Math.floor(tick);
 }
 
+/**
+ * String used to concatenate the namespace of parent loggers and their child loggers.
+ * @internal
+ */
 export const eventNamespaceSeparator = ":" as const;
 
 /**
@@ -92,6 +119,9 @@ export const eventNamespaceSeparator = ":" as const;
  * Creates sub-logger that appends properties to all events
  */
 export abstract class TelemetryLogger implements ITelemetryLoggerExt {
+	/**
+	 * {@inheritDoc eventNamespaceSeparator}
+	 */
 	public static readonly eventNamespaceSeparator = eventNamespaceSeparator;
 
 	public static sanitizePkgName(name: string): string {
@@ -286,6 +316,8 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
  * @deprecated 0.56, remove TaggedLoggerAdapter once its usage is removed from
  * container-runtime. Issue: #8191
  * TaggedLoggerAdapter class can add tag handling to your logger.
+ *
+ * @internal
  */
 export class TaggedLoggerAdapter implements ITelemetryBaseLogger {
 	public constructor(private readonly logger: ITelemetryBaseLogger) {}
@@ -336,11 +368,14 @@ export class TaggedLoggerAdapter implements ITelemetryBaseLogger {
 }
 
 /**
- * Create a child logger based on the provided props object
- * @param props - logger is the base logger the child will log to after it's processing, namespace will be prefixed to all event names, properties are default properties that will be applied events.
+ * Create a child logger based on the provided props object.
  *
  * @remarks
  * Passing in no props object (i.e. undefined) will return a logger that is effectively a no-op.
+ *
+ * @param props - logger is the base logger the child will log to after it's processing, namespace will be prefixed to all event names, properties are default properties that will be applied events.
+ *
+ * @internal
  */
 export function createChildLogger(props?: {
 	logger?: ITelemetryBaseLogger;
@@ -353,7 +388,7 @@ export function createChildLogger(props?: {
 /**
  * ChildLogger class contains various helper telemetry methods,
  * encoding in one place schemas for various types of Fluid telemetry events.
- * Creates sub-logger that appends properties to all events
+ * Creates sub-logger that appends properties to all events.
  */
 export class ChildLogger extends TelemetryLogger {
 	/**
@@ -449,16 +484,38 @@ export class ChildLogger extends TelemetryLogger {
 }
 
 /**
- * Create a logger which logs to multiple other loggers based on the provided props object
- * @param props - loggers are the base loggers that will logged to after it's processing, namespace will be prefixed to all event names, properties are default properties that will be applied events.
- * tryInheritProperties will attempted to copy those loggers properties to this loggers if they are of a known type e.g. one from this package
+ * Input properties for {@link createMultiSinkLogger}.
+ *
+ * @internal
  */
-export function createMultiSinkLogger(props: {
+export interface MultiSinkLoggerProperties {
+	/**
+	 * Will be prefixed to all event names.
+	 */
 	namespace?: string;
+
+	/**
+	 * Default properties that will be applied to all events flowing through this logger.
+	 */
 	properties?: ITelemetryLoggerPropertyBags;
+
+	/**
+	 * The base loggers that this logger will forward the logs to, after it processes them.
+	 */
 	loggers?: (ITelemetryBaseLogger | undefined)[];
+
+	/**
+	 * If true, the logger will attempt to copy the custom properties (if they are of a known type, i.e. one from this package) of all the base loggers passed to it, to apply them itself to logs that flow through.
+	 */
 	tryInheritProperties?: true;
-}): ITelemetryLoggerExt {
+}
+
+/**
+ * Create a logger which logs to multiple other loggers based on the provided props object.
+ *
+ * @internal
+ */
+export function createMultiSinkLogger(props: MultiSinkLoggerProperties): ITelemetryLoggerExt {
 	return new MultiSinkLogger(
 		props.namespace,
 		props.properties,
@@ -551,10 +608,15 @@ export class MultiSinkLogger extends TelemetryLogger {
 }
 
 /**
- * Describes what events PerformanceEvent should log
- * By default, all events are logged, but client can override this behavior
- * For example, there is rarely a need to record start event, as we really after
+ * Describes what events {@link PerformanceEvent} should log.
+ *
+ * @remarks
+ * By default, all events are logged, but the client can override this behavior.
+ *
+ * For example, there is rarely a need to record a start event, as we're really after
  * success / failure tracking, including duration (on success).
+ *
+ * @internal
  */
 export interface IPerformanceEventMarkers {
 	start?: true;
@@ -563,7 +625,9 @@ export interface IPerformanceEventMarkers {
 }
 
 /**
- * Helper class to log performance events
+ * Helper class to log performance events.
+ *
+ * @internal
  */
 export class PerformanceEvent {
 	/**
@@ -780,10 +844,13 @@ export class PerformanceEvent {
 
 /**
  * Null logger that no-ops for all telemetry events passed to it.
+ *
  * @deprecated This will be removed in a future release.
  * For internal use within the FluidFramework codebase, use {@link createChildLogger} with no arguments instead.
  * For external consumers we recommend writing a trivial implementation of {@link @fluidframework/core-interfaces#ITelemetryBaseLogger}
  * where the send() method does nothing and using that.
+ *
+ * @internal
  */
 export class TelemetryNullLogger implements ITelemetryLoggerExt {
 	public send(event: ITelemetryBaseEvent): void {}
@@ -853,6 +920,28 @@ function convertToBasePropertyTypeUntagged(
 	}
 }
 
+/**
+ * Tags all given `values` with the same `tag`.
+ *
+ * @param tag - The tag with which all `values` will be annotated.
+ * @param values - The values to be tagged.
+ *
+ * @remarks
+ * It supports properties of type {@link @fluidframework/core-interfaces#TelemetryBaseEventPropertyType},
+ * as well as callbacks that return that type.
+ *
+ * @example Sample usage
+ * ```typescript
+ * {
+ * 	// ...Other properties being added to a telemetry event
+ * 	...tagData("someTag", {foo: 1, bar: 2}),
+ * 	// ...
+ * }
+ * ```
+ * This will result in `foo` and `bar` added to the event with their values tagged.
+ *
+ * @internal
+ */
 export const tagData = <
 	T extends TelemetryDataTag,
 	V extends Record<
@@ -895,8 +984,27 @@ export const tagData = <
 		}, {}) as ReturnType<typeof tagData>;
 
 /**
- * Helper function to tag telemetry properties as CodeArtifacts. It supports properties of type
- * TelemetryBaseEventPropertyType as well as getters that return TelemetryBaseEventPropertyType.
+ * Tags all provided `values` as {@link TelemetryDataTag.CodeArtifact}.
+ *
+ * @param values - The values to be tagged.
+ *
+ * @remarks
+ * It supports properties of type {@link @fluidframework/core-interfaces#TelemetryBaseEventPropertyType},
+ * as well as callbacks that return that type.
+ *
+ * @example Sample usage
+ * ```typescript
+ * {
+ * 	// ...Other properties being added to a telemetry event
+ * 	...tagCodeArtifacts("someTag", {foo: 1, bar: 2}),
+ * 	// ...
+ * }
+ * ```
+ * This will result in `foo` and `bar` added to the event with their values tagged as {@link TelemetryDataTag.CodeArtifact}.
+ *
+ * @see {@link tagData}
+ *
+ * @internal
  */
 export const tagCodeArtifacts = <
 	T extends Record<

package/src/mockLogger.ts

@@ -15,6 +15,8 @@ import { createChildLogger } from "./logger";
 /**
  * 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.
+ *
+ * @internal
  */
 export class MockLogger implements ITelemetryBaseLogger {
 	events: ITelemetryBaseEvent[] = [];

package/src/sampledTelemetryHelper.ts

@@ -49,9 +49,13 @@ interface Measurements {
 /**
  * Helper class that executes a specified code block and writes an
  * {@link @fluidframework/core-interfaces#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.
+ * 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.
+ *
+ * @internal
  */
 export class SampledTelemetryHelper implements IDisposable {
 	disposed: boolean = false;

package/src/telemetryTypes.ts

@@ -9,14 +9,22 @@ import { ITelemetryBaseLogger, LogLevel, Tagged } from "@fluidframework/core-int
  * The categories FF uses when instrumenting the code.
  *
  * generic - Informational log event
+ *
  * error - Error log event, ideally 0 of these are logged during a session
+ *
  * performance - Includes duration, and often has _start, _end, or _cancel suffixes for activity tracking
+ * @alpha
  */
 export type TelemetryEventCategory = "generic" | "error" | "performance";
 
 /**
  * Property types that can be logged.
- * Includes extra types beyond TelemetryBaseEventPropertyType, which must be converted before sending to a base logger
+ *
+ * @remarks
+ * Includes extra types beyond {@link @fluidframework/core-interfaces#TelemetryBaseEventPropertyType}, which must be
+ * converted before sending to a base logger.
+ *
+ * @alpha
  */
 export type TelemetryEventPropertyTypeExt =
 	| string
@@ -34,7 +42,8 @@ export type TelemetryEventPropertyTypeExt =
  * to mark pieces of information that should be organized or handled differently by loggers in various first or third
  * party scenarios. For example, tags are used to mark personal information that should not be stored in logs.
  *
- * @deprecated Use Tagged<TelemetryEventPropertyTypeExt>
+ * @deprecated Use {@link @fluidframework/core-interfaces#Tagged}\<{@link TelemetryEventPropertyTypeExt}\>
+ * @internal
  */
 export interface ITaggedTelemetryPropertyTypeExt {
 	value: TelemetryEventPropertyTypeExt;
@@ -43,6 +52,8 @@ export interface ITaggedTelemetryPropertyTypeExt {
 
 /**
  * JSON-serializable properties, which will be logged with telemetry.
+ *
+ * @alpha
  */
 export interface ITelemetryPropertiesExt {
 	[index: string]: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>;
@@ -50,9 +61,11 @@ export interface ITelemetryPropertiesExt {
 
 /**
  * Interface for logging telemetry statements.
- * Can contain any number of properties that get serialized as json payload.
+ * @remarks May contain any number of properties that get serialized as json payload.
  * @param category - category of the event, like "error", "performance", "generic", etc.
  * @param eventName - name of the event.
+ *
+ * @internal
  */
 export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
 	category: string;
@@ -61,7 +74,8 @@ export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
 
 /**
  * Informational (non-error) telemetry event
- * Maps to category = "generic"
+ * @remarks Maps to category = "generic"
+ * @alpha
  */
 export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
 	eventName: string;
@@ -70,7 +84,8 @@ export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
 
 /**
  * Error telemetry event.
- * Maps to category = "error"
+ * @remarks Maps to category = "error"
+ * @alpha
  */
 export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
 	eventName: string;
@@ -78,16 +93,20 @@ export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
 
 /**
  * Performance telemetry event.
- * Maps to category = "performance"
+ * @remarks Maps to category = "performance"
+ * @alpha
  */
 export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
 	duration?: number; // Duration of event (optional)
 }
 
 /**
- * An extended TelemetryLogger interface which allows for more lenient event types.
+ * An extended {@link @fluidframework/core-interfaces#ITelemetryBaseLogger} which allows for more lenient event types.
+ *
+ * @remarks
  * This interface is meant to be used internally within the Fluid Framework,
- * and ITelemetryBaseLogger should be used when loggers are passed between layers.
+ * and `ITelemetryBaseLogger` should be used when loggers are passed between layers.
+ * @alpha
  */
 export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
 	/**

package/src/thresholdCounter.ts

@@ -6,8 +6,9 @@
 import { ITelemetryLoggerExt } from "./telemetryTypes";
 
 /**
- * Utility counter which will send event only if the provided value
- * is above a configured threshold
+ * Utility counter which will send event only if the provided value is above a configured threshold.
+ *
+ * @internal
  */
 export class ThresholdCounter {
 	public constructor(

package/src/utils.ts

@@ -16,6 +16,12 @@ import { ITelemetryGenericEventExt, ITelemetryLoggerExt } from "./telemetryTypes
  * @param logger - The logger to log with
  * @param event - The string or event to log
  * @returns The outcome of the condition
+ *
+ * @internal
+ *
+ * @deprecated
+ * This API will be removed in a future release.
+ * No replacement API is intended, but reproducing its behavior should be trivial for anyone who needs it.
  */
 export function logIfFalse(
 	condition: unknown,