@fluidframework/telemetry-utils 2.0.0-dev.7.4.0.215930 → 2.0.0-dev.7.4.0.217212

package/lib/telemetry-utils-untrimmed.d.ts

@@ -2,6 +2,7 @@
 
 import { EventEmitter } from 'events';
 import { EventEmitterEventType } from '@fluid-internal/client-utils';
+import { IConfigProviderBase as IConfigProviderBase_2 } from '@fluidframework/core-interfaces';
 import { IDisposable } from '@fluidframework/core-interfaces';
 import { IErrorBase } from '@fluidframework/core-interfaces';
 import { IEvent } from '@fluidframework/core-interfaces';
@@ -23,16 +24,28 @@ import { TelemetryBaseEventPropertyType } from '@fluidframework/core-interfaces'
 import { TelemetryEventPropertyType } from '@fluidframework/core-interfaces';
 import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
+/**
+ * Types supported by {@link IConfigProviderBase}.
+ * @deprecated Use ConfigTypes from fluidFramework/core-interfaces
+ *
+ * @internal
+ */
 export declare type ConfigTypes = string | number | boolean | number[] | string[] | boolean[] | undefined;
 
+/**
+ * @internal
+ */
 export declare const connectedEventName = "connected";
 
 /**
- * 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 declare function createChildLogger(props?: {
     logger?: ITelemetryBaseLogger;
@@ -40,19 +53,20 @@ export declare function createChildLogger(props?: {
     properties?: ITelemetryLoggerPropertyBags;
 }): ITelemetryLoggerExt;
 
+/**
+ * Creates a child logger with a {@link MonitoringContext}.
+ *
+ * @see {@link loggerToMonitoringContext}
+ * @internal
+ */
 export declare function createChildMonitoringContext(props: Parameters<typeof createChildLogger>[0]): MonitoringContext;
 
 /**
- * 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
+ * Create a logger which logs to multiple other loggers based on the provided props object.
+ *
+ * @internal
  */
-export declare function createMultiSinkLogger(props: {
-    namespace?: string;
-    properties?: ITelemetryLoggerPropertyBags;
-    loggers?: (ITelemetryBaseLogger | undefined)[];
-    tryInheritProperties?: true;
-}): ITelemetryLoggerExt;
+export declare function createMultiSinkLogger(props: MultiSinkLoggerProperties): ITelemetryLoggerExt;
 
 /**
  * Wraps around an existing logger matching the {@link ITelemetryLoggerExt} interface and provides the ability to only log a subset of events using a sampling strategy provided by an ${@link IEventSampler}.
@@ -127,12 +141,23 @@ export declare class DataProcessingError extends LoggingError implements IErrorB
     static wrapIfUnrecognized(originalError: unknown, dataProcessingCodepath: string, messageLike?: Partial<Pick<ISequencedDocumentMessage, "clientId" | "sequenceNumber" | "clientSequenceNumber" | "referenceSequenceNumber" | "minimumSequenceNumber" | "timestamp">>): IFluidErrorBase;
 }
 
+/**
+ * @internal
+ */
 export declare const disconnectedEventName = "disconnected";
 
 /**
  * Event Emitter helper class
+ *
+ * @remarks
  * Any exceptions thrown by listeners will be caught and raised through "error" event.
  * Any exception thrown by "error" listeners will propagate to the caller.
+ *
+ * @internal
+ *
+ * @privateRemarks
+ * This probably doesn't belong in this package, as it is not telemetry-specific, and is really only intended for internal fluid-framework use.
+ * We should consider moving it to the `core-utils` package.
  */
 export declare class EventEmitterWithErrorHandling<TEvent extends IEvent = IEvent> extends TypedEventEmitter<TEvent> {
     private readonly errorHandler;
@@ -140,6 +165,10 @@ export declare class EventEmitterWithErrorHandling<TEvent extends IEvent = IEven
     emit(event: EventEmitterEventType, ...args: unknown[]): boolean;
 }
 
+/**
+ * String used to concatenate the namespace of parent loggers and their child loggers.
+ * @internal
+ */
 export declare const eventNamespaceSeparator: ":";
 
 /**
@@ -157,6 +186,8 @@ export declare function extractLogSafeErrorProperties(error: unknown, sanitizeSt
  * Extracts specific properties from the provided message that we know are safe to log.
  *
  * @param messageLike - Message to include info about via telemetry props.
+ *
+ * @internal
  */
 export declare const extractSafePropertiesFromMessage: (messageLike: Partial<Pick<ISequencedDocumentMessage, "clientId" | "sequenceNumber" | "clientSequenceNumber" | "referenceSequenceNumber" | "minimumSequenceNumber" | "timestamp">>) => {
     messageClientId: string | undefined;
@@ -167,6 +198,9 @@ export declare const extractSafePropertiesFromMessage: (messageLike: Partial<Pic
     messageTimestamp: number | undefined;
 };
 
+/**
+ * @internal
+ */
 export declare function formatTick(tick: number): number;
 
 /**
@@ -220,15 +254,19 @@ export declare const getCircularReplacer: () => (key: string, value: unknown) =>
 
 /**
  * Type guard for error data containing the {@link IFluidErrorBase.errorInstanceId} property.
+ *
+ * @internal
  */
 export declare const hasErrorInstanceId: (x: unknown) => x is {
     errorInstanceId: string;
 };
 
 /**
- * Explicitly typed interface for reading configurations
+ * Explicitly typed interface for reading configurations.
+ *
+ * @internal
  */
-export declare interface IConfigProvider extends IConfigProviderBase {
+export declare interface IConfigProvider extends IConfigProviderBase_2 {
     getBoolean(name: string): boolean | undefined;
     getNumber(name: string): number | undefined;
     getString(name: string): string | undefined;
@@ -238,7 +276,11 @@ export declare interface IConfigProvider extends IConfigProviderBase {
 }
 
 /**
- * Base interface for providing configurations to enable/disable/control features
+ * Base interface for providing configurations to enable/disable/control features.
+ *
+ * @deprecated Use IConfigProviderBase from fluidFramework/core-interfaces
+ *
+ * @internal
  */
 export declare interface IConfigProviderBase {
     getRawConfig(name: string): ConfigTypes;
@@ -278,6 +320,8 @@ export declare interface IFluidErrorAnnotations {
  * It features the members of {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error}
  * made readonly, as well as  {@link IFluidErrorBase.errorType} and {@link IFluidErrorBase.errorInstanceId}.
  * It also features getters and setters for telemetry props to be included when the error is logged.
+ *
+ * @internal
  */
 export declare interface IFluidErrorBase extends Error {
     /**
@@ -325,10 +369,15 @@ export declare interface IFluidErrorBase extends Error {
 }
 
 /**
- * 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 declare interface IPerformanceEventMarkers {
     start?: true;
@@ -364,21 +413,30 @@ export declare function isExternalError(error: unknown): boolean;
 
 /**
  * Type guard for {@link IFluidErrorBase}.
+ *
+ * @internal
  */
 export declare function isFluidError(error: unknown): error is IFluidErrorBase;
 
 /**
- * type guard for ILoggingError interface
+ * Type-guard for {@link @fluidframework/core-interfaces#ILoggingError}.
+ *
+ * @internal
  */
 export declare const isILoggingError: (x: unknown) => x is ILoggingError;
 
 /**
- * Type guard to identify if a particular telemetry property appears to be a tagged telemetry property
+ * Type guard to identify if a particular telemetry property appears to be a
+ * {@link @fluidframework/core-interfaces#Tagged} telemetry property.
+ *
+ * @internal
  */
 export declare function isTaggedTelemetryPropertyValue(x: Tagged<TelemetryEventPropertyTypeExt> | TelemetryEventPropertyTypeExt): x is Tagged<TelemetryEventPropertyTypeExt>;
 
 /**
  * Type guard for old standard of valid/known errors.
+ *
+ * @internal
  */
 export declare function isValidLegacyError(error: unknown): error is Omit<IFluidErrorBase, "errorInstanceId">;
 
@@ -387,7 +445,8 @@ export declare function isValidLegacyError(error: unknown): error is Omit<IFluid
  * 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 declare interface ITaggedTelemetryPropertyTypeExt {
     value: TelemetryEventPropertyTypeExt;
@@ -396,7 +455,9 @@ export declare interface ITaggedTelemetryPropertyTypeExt {
 
 /**
  * Error telemetry event.
- * Maps to category = "error"
+ * @remarks Maps to category = "error"
+ *
+ * @internal
  */
 export declare interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
     eventName: string;
@@ -404,9 +465,11 @@ export declare interface ITelemetryErrorEventExt extends 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 declare interface ITelemetryEventExt extends ITelemetryPropertiesExt {
     category: string;
@@ -415,7 +478,9 @@ export declare interface ITelemetryEventExt extends ITelemetryPropertiesExt {
 
 /**
  * Informational (non-error) telemetry event
- * Maps to category = "generic"
+ * @remarks Maps to category = "generic"
+ *
+ * @internal
  */
 export declare interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
     eventName: string;
@@ -423,9 +488,13 @@ export declare interface ITelemetryGenericEventExt extends ITelemetryPropertiesE
 }
 
 /**
- * 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.
+ *
+ * @internal
  */
 export declare interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
     /**
@@ -450,10 +519,16 @@ export declare interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
     sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.default): void;
 }
 
+/**
+ * @internal
+ */
 export declare interface ITelemetryLoggerPropertyBag {
     [index: string]: TelemetryEventPropertyTypes | (() => TelemetryEventPropertyTypes);
 }
 
+/**
+ * @internal
+ */
 export declare interface ITelemetryLoggerPropertyBags {
     all?: ITelemetryLoggerPropertyBag;
     error?: ITelemetryLoggerPropertyBag;
@@ -461,7 +536,9 @@ export declare interface ITelemetryLoggerPropertyBags {
 
 /**
  * Performance telemetry event.
- * Maps to category = "performance"
+ * @remarks Maps to category = "performance"
+ *
+ * @internal
  */
 export declare interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
     duration?: number;
@@ -469,11 +546,18 @@ export declare interface ITelemetryPerformanceEventExt extends ITelemetryGeneric
 
 /**
  * JSON-serializable properties, which will be logged with telemetry.
+ *
+ * @internal
  */
 export declare interface ITelemetryPropertiesExt {
     [index: string]: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>;
 }
 
+/**
+ * Creates a {@link MonitoringContext} from the provided logger, if it isn't already one.
+ *
+ * @internal
+ */
 export declare function loggerToMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLoggerExt>(logger: L): MonitoringContext<L>;
 
 /**
@@ -523,14 +607,33 @@ export declare class LoggingError extends Error implements ILoggingError, Omit<I
  * @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 declare function logIfFalse(condition: unknown, logger: ITelemetryBaseLogger, event: string | ITelemetryGenericEvent): condition is true;
 
-export declare function mixinMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLoggerExt>(logger: L, ...configs: (IConfigProviderBase | undefined)[]): MonitoringContext<L>;
+/**
+ * Creates a {@link MonitoringContext} from the provided logger.
+ *
+ * @remarks
+ * Assumes that the provided logger is not itself already a {@link MonitoringContext}, and will throw an error if it is.
+ * If you are unsure, use {@link loggerToMonitoringContext} instead.
+ *
+ * @throws If the provided logger is already a {@link MonitoringContext}.
+ *
+ * @internal
+ */
+export declare function mixinMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLoggerExt>(logger: L, ...configs: (IConfigProviderBase_2 | undefined)[]): MonitoringContext<L>;
 
 /**
  * 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 declare class MockLogger implements ITelemetryBaseLogger {
     readonly minLogLevel?: LogLevel | undefined;
@@ -591,13 +694,39 @@ export declare class MockLogger implements ITelemetryBaseLogger {
 }
 
 /**
- * A type containing both a telemetry logger and a configuration provider
+ * A type containing both a telemetry logger and a configuration provider.
+ *
+ * @internal
  */
 export declare interface MonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLoggerExt> {
     config: IConfigProvider;
     logger: L;
 }
 
+/**
+ * Input properties for {@link createMultiSinkLogger}.
+ *
+ * @internal
+ */
+export declare 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;
+}
+
 /**
  * The Error class used when normalizing an external error
  *
@@ -617,9 +746,13 @@ export declare function normalizeError(error: unknown, annotations?: IFluidError
 
 /**
  * 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
  */
 export declare function numberFromString(str: string | null | undefined): string | number | undefined;
 
@@ -634,7 +767,9 @@ export declare function numberFromString(str: string | null | undefined): string
 export declare function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string): void;
 
 /**
- * Helper class to log performance events
+ * Helper class to log performance events.
+ *
+ * @internal
  */
 export declare class PerformanceEvent {
     private readonly logger;
@@ -711,17 +846,26 @@ export declare class PerformanceEvent {
  * @param connected - A boolean tracking whether the connection was in a connected state or not
  * @param clientId - The connected/disconnected clientId
  * @param disconnectedReason - The reason for the connection to be disconnected (Used for telemetry purposes only)
+ *
+ * @internal
  */
 export declare function raiseConnectedEvent(logger: ITelemetryLoggerExt, emitter: EventEmitter, connected: boolean, clientId?: string, disconnectedReason?: string): void;
 
+/**
+ * @internal
+ */
 export declare function safeRaiseEvent(emitter: EventEmitter, logger: ITelemetryLoggerExt, event: string, ...args: unknown[]): void;
 
 /**
  * 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 declare class SampledTelemetryHelper implements IDisposable {
     private readonly eventBase;
@@ -769,12 +913,33 @@ export declare class SampledTelemetryHelper implements IDisposable {
  * Creates a base configuration provider based on `sessionStorage`
  *
  * @returns A lazy initialized base configuration provider with `sessionStorage` as the underlying config store
+ *
+ * @internal
  */
-export declare const sessionStorageConfigProvider: Lazy<IConfigProviderBase>;
+export declare const sessionStorageConfigProvider: Lazy<IConfigProviderBase_2>;
 
 /**
- * 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 declare const tagCodeArtifacts: <T extends Record<string, TelemetryEventPropertyType | (() => TelemetryBaseEventPropertyType)>>(values: T) => { [P in keyof T]: (T[P] extends () => TelemetryBaseEventPropertyType ? () => {
         value: ReturnType<T[P]>;
@@ -784,6 +949,28 @@ export declare const tagCodeArtifacts: <T extends Record<string, TelemetryEventP
         tag: TelemetryDataTag.CodeArtifact;
     }) | (T[P] extends undefined ? undefined : never); };
 
+/**
+ * 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 declare const tagData: <T extends TelemetryDataTag, V extends Record<string, TelemetryEventPropertyType | (() => TelemetryBaseEventPropertyType)>>(tag: T, values: V) => { [P in keyof V]: (V[P] extends () => TelemetryBaseEventPropertyType ? () => {
         value: ReturnType<V[P]>;
         tag: T;
@@ -796,6 +983,8 @@ export declare const tagData: <T extends TelemetryDataTag, V extends Record<stri
  * @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 declare class TaggedLoggerAdapter implements ITelemetryBaseLogger {
     private readonly logger;
@@ -808,7 +997,10 @@ export declare class TaggedLoggerAdapter implements ITelemetryBaseLogger {
 
 /**
  * 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 declare enum TelemetryDataTag {
     /**
@@ -825,28 +1017,43 @@ export declare enum TelemetryDataTag {
  * 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
+ *
+ * @internal
  */
 export declare 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.
+ *
+ * @internal
  */
 export declare type TelemetryEventPropertyTypeExt = string | number | 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)[];
 };
 
+/**
+ * @internal
+ */
 export declare type TelemetryEventPropertyTypes = ITelemetryBaseProperties[string];
 
 /**
  * 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 declare class TelemetryNullLogger implements ITelemetryLoggerExt {
     send(event: ITelemetryBaseEvent): void;
@@ -856,8 +1063,9 @@ export declare class TelemetryNullLogger implements ITelemetryLoggerExt {
 }
 
 /**
- * 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 declare class ThresholdCounter {
     private readonly threshold;

package/lib/telemetryTypes.d.ts

@@ -7,13 +7,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
+ *
+ * @internal
  */
 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.
+ *
+ * @internal
  */
 export type TelemetryEventPropertyTypeExt = string | number | boolean | undefined | (string | number | boolean)[] | {
     [key: string]: // Flat objects can have the same properties as the event itself
@@ -24,7 +33,8 @@ export type TelemetryEventPropertyTypeExt = string | number | boolean | undefine
  * 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;
@@ -32,15 +42,19 @@ export interface ITaggedTelemetryPropertyTypeExt {
 }
 /**
  * JSON-serializable properties, which will be logged with telemetry.
+ *
+ * @internal
  */
 export interface ITelemetryPropertiesExt {
     [index: string]: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>;
 }
 /**
  * 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;
@@ -48,7 +62,9 @@ export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
 }
 /**
  * Informational (non-error) telemetry event
- * Maps to category = "generic"
+ * @remarks Maps to category = "generic"
+ *
+ * @internal
  */
 export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
     eventName: string;
@@ -56,22 +72,30 @@ export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
 }
 /**
  * Error telemetry event.
- * Maps to category = "error"
+ * @remarks Maps to category = "error"
+ *
+ * @internal
  */
 export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
     eventName: string;
 }
 /**
  * Performance telemetry event.
- * Maps to category = "performance"
+ * @remarks Maps to category = "performance"
+ *
+ * @internal
  */
 export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
     duration?: number;
 }
 /**
- * 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.
+ *
+ * @internal
  */
 export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
     /**