@fluidframework/telemetry-utils 2.0.0-internal.8.0.0 → 2.0.0-rc.1.0.0

package/lib/telemetry-utils-alpha.d.mts

@@ -0,0 +1,290 @@
+/// <reference types="node" />
+
+import { EventEmitter } from 'events';
+import { EventEmitterEventType } from '@fluid-internal/client-utils';
+import { IConfigProviderBase } from '@fluidframework/core-interfaces';
+import { IDisposable } from '@fluidframework/core-interfaces';
+import { IErrorBase } from '@fluidframework/core-interfaces';
+import { IEvent } from '@fluidframework/core-interfaces';
+import { IGenericError } from '@fluidframework/core-interfaces';
+import { ILoggingError } from '@fluidframework/core-interfaces';
+import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
+import { ITelemetryBaseEvent } from '@fluidframework/core-interfaces';
+import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
+import { ITelemetryBaseProperties } from '@fluidframework/core-interfaces';
+import { ITelemetryErrorEvent } from '@fluidframework/core-interfaces';
+import { ITelemetryGenericEvent } from '@fluidframework/core-interfaces';
+import { ITelemetryPerformanceEvent } from '@fluidframework/core-interfaces';
+import { ITelemetryProperties } from '@fluidframework/core-interfaces';
+import { IUsageError } from '@fluidframework/core-interfaces';
+import { Lazy } from '@fluidframework/core-utils';
+import { LogLevel } from '@fluidframework/core-interfaces';
+import { Tagged } from '@fluidframework/core-interfaces';
+import { TelemetryBaseEventPropertyType } from '@fluidframework/core-interfaces';
+import { TelemetryEventPropertyType } from '@fluidframework/core-interfaces';
+import { TypedEventEmitter } from '@fluid-internal/client-utils';
+
+/* Excluded from this release type: connectedEventName */
+
+/**
+ * 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.
+ *
+ * @alpha
+ */
+export declare function createChildLogger(props?: {
+    logger?: ITelemetryBaseLogger;
+    namespace?: string;
+    properties?: ITelemetryLoggerPropertyBags;
+}): ITelemetryLoggerExt;
+
+/* Excluded from this release type: createChildMonitoringContext */
+
+/* Excluded from this release type: createMultiSinkLogger */
+
+/* Excluded from this release type: createSampledLogger */
+
+/* Excluded from this release type: DataCorruptionError */
+
+/* Excluded from this release type: DataProcessingError */
+
+/* Excluded from this release type: disconnectedEventName */
+
+/**
+ * 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.
+ * @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.
+ * @public
+ */
+export declare class EventEmitterWithErrorHandling<TEvent extends IEvent = IEvent> extends TypedEventEmitter<TEvent> {
+    private readonly errorHandler;
+    constructor(errorHandler: (eventName: EventEmitterEventType, error: any) => void);
+    emit(event: EventEmitterEventType, ...args: unknown[]): boolean;
+}
+
+/* Excluded from this release type: eventNamespaceSeparator */
+
+/* Excluded from this release type: extractLogSafeErrorProperties */
+
+/* Excluded from this release type: extractSafePropertiesFromMessage */
+
+/* Excluded from this release type: formatTick */
+
+/* Excluded from this release type: generateErrorWithStack */
+
+/* Excluded from this release type: generateStack */
+
+/* Excluded from this release type: GenericError */
+
+/* Excluded from this release type: getCircularReplacer */
+
+/* Excluded from this release type: hasErrorInstanceId */
+
+/* Excluded from this release type: IConfigProvider */
+
+/* Excluded from this release type: IEventSampler */
+
+/* Excluded from this release type: IFluidErrorAnnotations */
+
+/* Excluded from this release type: IFluidErrorBase */
+
+/* Excluded from this release type: IGenericError */
+
+/* Excluded from this release type: ILoggingError */
+
+/* Excluded from this release type: IPerformanceEventMarkers */
+
+/* Excluded from this release type: ISampledTelemetryLogger */
+
+/* Excluded from this release type: isExternalError */
+
+/* Excluded from this release type: isFluidError */
+
+/* Excluded from this release type: isILoggingError */
+
+/* Excluded from this release type: isTaggedTelemetryPropertyValue */
+
+/* Excluded from this release type: isValidLegacyError */
+
+/* Excluded from this release type: ITaggedTelemetryPropertyTypeExt */
+
+/**
+ * Error telemetry event.
+ * @remarks Maps to category = "error"
+ * @public
+ */
+export declare interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
+    eventName: string;
+}
+
+/* Excluded from this release type: ITelemetryEventExt */
+
+/**
+ * Informational (non-error) telemetry event
+ * @remarks Maps to category = "generic"
+ * @public
+ */
+export declare interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
+    eventName: string;
+    category?: TelemetryEventCategory;
+}
+
+/**
+ * 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.
+ * @public
+ */
+export declare 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.
+     */
+    sendTelemetryEvent(event: ITelemetryGenericEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.default): void;
+    /**
+     * Send 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
+     * @param event - Event to send
+     * @param error - optional error object to log
+     * @param logLevel - optional level of the log.
+     */
+    sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.default): void;
+}
+
+/**
+ * @alpha
+ */
+export declare interface ITelemetryLoggerPropertyBag {
+    [index: string]: TelemetryEventPropertyTypes | (() => TelemetryEventPropertyTypes);
+}
+
+/**
+ * @alpha
+ */
+export declare interface ITelemetryLoggerPropertyBags {
+    all?: ITelemetryLoggerPropertyBag;
+    error?: ITelemetryLoggerPropertyBag;
+}
+
+/**
+ * Performance telemetry event.
+ * @remarks Maps to category = "performance"
+ * @public
+ */
+export declare interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
+    duration?: number;
+}
+
+/**
+ * JSON-serializable properties, which will be logged with telemetry.
+ * @public
+ */
+export declare interface ITelemetryPropertiesExt {
+    [index: string]: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>;
+}
+
+/* Excluded from this release type: IUsageError */
+
+/* Excluded from this release type: Lazy */
+
+/* Excluded from this release type: loggerToMonitoringContext */
+
+/* Excluded from this release type: LoggingError */
+
+/* Excluded from this release type: logIfFalse */
+
+/* Excluded from this release type: mixinMonitoringContext */
+
+/* Excluded from this release type: MockLogger */
+
+/* Excluded from this release type: MonitoringContext */
+
+/* Excluded from this release type: MultiSinkLoggerProperties */
+
+/* Excluded from this release type: NORMALIZED_ERROR_TYPE */
+
+/* Excluded from this release type: normalizeError */
+
+/* Excluded from this release type: numberFromString */
+
+/* Excluded from this release type: overwriteStack */
+
+/* Excluded from this release type: PerformanceEvent */
+
+/* Excluded from this release type: raiseConnectedEvent */
+
+/* Excluded from this release type: safeRaiseEvent */
+
+/* Excluded from this release type: SampledTelemetryHelper */
+
+/* Excluded from this release type: sessionStorageConfigProvider */
+
+/* Excluded from this release type: tagCodeArtifacts */
+
+/* Excluded from this release type: tagData */
+
+/* Excluded from this release type: TaggedLoggerAdapter */
+
+/* Excluded from this release type: 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
+ * @public
+ */
+export declare type TelemetryEventCategory = "generic" | "error" | "performance";
+
+/**
+ * Property types that can be logged.
+ *
+ * @remarks
+ * Includes extra types beyond {@link @fluidframework/core-interfaces#TelemetryBaseEventPropertyType}, which must be
+ * converted before sending to a base logger.
+ * @public
+ */
+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)[];
+};
+
+/**
+ * @alpha
+ */
+export declare type TelemetryEventPropertyTypes = ITelemetryBaseProperties[string];
+
+/* Excluded from this release type: TelemetryNullLogger */
+
+/* Excluded from this release type: ThresholdCounter */
+
+/* Excluded from this release type: UsageError */
+
+/* Excluded from this release type: validatePrecondition */
+
+/* Excluded from this release type: wrapError */
+
+/* Excluded from this release type: wrapErrorAndLog */
+
+export { }

package/lib/{telemetry-utils-alpha.d.ts → telemetry-utils-beta.d.mts}

@@ -2,7 +2,7 @@
 
 import { EventEmitter } from 'events';
 import { EventEmitterEventType } from '@fluid-internal/client-utils';
-import { IConfigProviderBase as IConfigProviderBase_2 } from '@fluidframework/core-interfaces';
+import { IConfigProviderBase } from '@fluidframework/core-interfaces';
 import { IDisposable } from '@fluidframework/core-interfaces';
 import { IErrorBase } from '@fluidframework/core-interfaces';
 import { IEvent } from '@fluidframework/core-interfaces';
@@ -24,8 +24,6 @@ import { TelemetryBaseEventPropertyType } from '@fluidframework/core-interfaces'
 import { TelemetryEventPropertyType } from '@fluidframework/core-interfaces';
 import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
-/* Excluded from this release type: ConfigTypes */
-
 /* Excluded from this release type: connectedEventName */
 
 /* Excluded from this release type: createChildLogger */
@@ -51,7 +49,7 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
  * @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.
- * @alpha
+ * @public
  */
 export declare class EventEmitterWithErrorHandling<TEvent extends IEvent = IEvent> extends TypedEventEmitter<TEvent> {
     private readonly errorHandler;
@@ -79,8 +77,6 @@ export declare class EventEmitterWithErrorHandling<TEvent extends IEvent = IEven
 
 /* Excluded from this release type: IConfigProvider */
 
-/* Excluded from this release type: IConfigProviderBase */
-
 /* Excluded from this release type: IEventSampler */
 
 /* Excluded from this release type: IFluidErrorAnnotations */
@@ -110,7 +106,7 @@ export declare class EventEmitterWithErrorHandling<TEvent extends IEvent = IEven
 /**
  * Error telemetry event.
  * @remarks Maps to category = "error"
- * @alpha
+ * @public
  */
 export declare interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
     eventName: string;
@@ -121,7 +117,7 @@ export declare interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt
 /**
  * Informational (non-error) telemetry event
  * @remarks Maps to category = "generic"
- * @alpha
+ * @public
  */
 export declare interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
     eventName: string;
@@ -134,7 +130,7 @@ export declare interface ITelemetryGenericEventExt extends ITelemetryPropertiesE
  * @remarks
  * This interface is meant to be used internally within the Fluid Framework,
  * and `ITelemetryBaseLogger` should be used when loggers are passed between layers.
- * @alpha
+ * @public
  */
 export declare interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
     /**
@@ -166,7 +162,7 @@ export declare interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
 /**
  * Performance telemetry event.
  * @remarks Maps to category = "performance"
- * @alpha
+ * @public
  */
 export declare interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
     duration?: number;
@@ -174,8 +170,7 @@ export declare interface ITelemetryPerformanceEventExt extends ITelemetryGeneric
 
 /**
  * JSON-serializable properties, which will be logged with telemetry.
- *
- * @alpha
+ * @public
  */
 export declare interface ITelemetryPropertiesExt {
     [index: string]: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>;
@@ -235,7 +230,7 @@ export declare interface ITelemetryPropertiesExt {
  * 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
+ * @public
  */
 export declare type TelemetryEventCategory = "generic" | "error" | "performance";
 
@@ -245,8 +240,7 @@ export declare type TelemetryEventCategory = "generic" | "error" | "performance"
  * @remarks
  * Includes extra types beyond {@link @fluidframework/core-interfaces#TelemetryBaseEventPropertyType}, which must be
  * converted before sending to a base logger.
- *
- * @alpha
+ * @public
  */
 export declare type TelemetryEventPropertyTypeExt = string | number | boolean | undefined | (string | number | boolean)[] | {
     [key: string]: // Flat objects can have the same properties as the event itself

package/lib/{telemetry-utils-beta.d.ts → telemetry-utils-public.d.mts}

@@ -2,7 +2,7 @@
 
 import { EventEmitter } from 'events';
 import { EventEmitterEventType } from '@fluid-internal/client-utils';
-import { IConfigProviderBase as IConfigProviderBase_2 } from '@fluidframework/core-interfaces';
+import { IConfigProviderBase } from '@fluidframework/core-interfaces';
 import { IDisposable } from '@fluidframework/core-interfaces';
 import { IErrorBase } from '@fluidframework/core-interfaces';
 import { IEvent } from '@fluidframework/core-interfaces';
@@ -24,8 +24,6 @@ import { TelemetryBaseEventPropertyType } from '@fluidframework/core-interfaces'
 import { TelemetryEventPropertyType } from '@fluidframework/core-interfaces';
 import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
-/* Excluded from this release type: ConfigTypes */
-
 /* Excluded from this release type: connectedEventName */
 
 /* Excluded from this release type: createChildLogger */
@@ -42,9 +40,22 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: disconnectedEventName */
 
-/* Excluded from this release type: EventEmitterEventType */
-
-/* Excluded from this release type: EventEmitterWithErrorHandling */
+/**
+ * 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.
+ * @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.
+ * @public
+ */
+export declare class EventEmitterWithErrorHandling<TEvent extends IEvent = IEvent> extends TypedEventEmitter<TEvent> {
+    private readonly errorHandler;
+    constructor(errorHandler: (eventName: EventEmitterEventType, error: any) => void);
+    emit(event: EventEmitterEventType, ...args: unknown[]): boolean;
+}
 
 /* Excluded from this release type: eventNamespaceSeparator */
 
@@ -66,16 +77,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: IConfigProvider */
 
-/* Excluded from this release type: IConfigProviderBase */
-
-/* Excluded from this release type: IConfigProviderBase_2 */
-
-/* Excluded from this release type: IDisposable */
-
-/* Excluded from this release type: IErrorBase */
-
-/* Excluded from this release type: IEvent */
-
 /* Excluded from this release type: IEventSampler */
 
 /* Excluded from this release type: IFluidErrorAnnotations */
@@ -102,35 +103,78 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: ITaggedTelemetryPropertyTypeExt */
 
-/* Excluded from this release type: ITelemetryBaseEvent */
-
-/* Excluded from this release type: ITelemetryBaseLogger */
-
-/* Excluded from this release type: ITelemetryBaseProperties */
-
-/* Excluded from this release type: ITelemetryErrorEvent */
-
-/* Excluded from this release type: ITelemetryErrorEventExt */
+/**
+ * Error telemetry event.
+ * @remarks Maps to category = "error"
+ * @public
+ */
+export declare interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
+    eventName: string;
+}
 
 /* Excluded from this release type: ITelemetryEventExt */
 
-/* Excluded from this release type: ITelemetryGenericEvent */
-
-/* Excluded from this release type: ITelemetryGenericEventExt */
-
-/* Excluded from this release type: ITelemetryLoggerExt */
+/**
+ * Informational (non-error) telemetry event
+ * @remarks Maps to category = "generic"
+ * @public
+ */
+export declare interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
+    eventName: string;
+    category?: TelemetryEventCategory;
+}
+
+/**
+ * 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.
+ * @public
+ */
+export declare 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.
+     */
+    sendTelemetryEvent(event: ITelemetryGenericEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.default): void;
+    /**
+     * Send 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
+     * @param event - Event to send
+     * @param error - optional error object to log
+     * @param logLevel - optional level of the log.
+     */
+    sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.default): void;
+}
 
 /* Excluded from this release type: ITelemetryLoggerPropertyBag */
 
 /* Excluded from this release type: ITelemetryLoggerPropertyBags */
 
-/* Excluded from this release type: ITelemetryPerformanceEvent */
-
-/* Excluded from this release type: ITelemetryPerformanceEventExt */
-
-/* Excluded from this release type: ITelemetryProperties */
-
-/* Excluded from this release type: ITelemetryPropertiesExt */
+/**
+ * Performance telemetry event.
+ * @remarks Maps to category = "performance"
+ * @public
+ */
+export declare interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
+    duration?: number;
+}
+
+/**
+ * JSON-serializable properties, which will be logged with telemetry.
+ * @public
+ */
+export declare interface ITelemetryPropertiesExt {
+    [index: string]: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>;
+}
 
 /* Excluded from this release type: IUsageError */
 
@@ -142,8 +186,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: logIfFalse */
 
-/* Excluded from this release type: LogLevel */
-
 /* Excluded from this release type: mixinMonitoringContext */
 
 /* Excluded from this release type: MockLogger */
@@ -174,17 +216,36 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: tagData */
 
-/* Excluded from this release type: Tagged */
-
 /* Excluded from this release type: TaggedLoggerAdapter */
 
 /* Excluded from this release type: TelemetryBaseEventPropertyType */
 
 /* Excluded from this release type: TelemetryDataTag */
 
-/* Excluded from this release type: TelemetryEventCategory */
-
-/* Excluded from this release type: TelemetryEventPropertyTypeExt */
+/**
+ * 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
+ * @public
+ */
+export declare type TelemetryEventCategory = "generic" | "error" | "performance";
+
+/**
+ * Property types that can be logged.
+ *
+ * @remarks
+ * Includes extra types beyond {@link @fluidframework/core-interfaces#TelemetryBaseEventPropertyType}, which must be
+ * converted before sending to a base logger.
+ * @public
+ */
+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)[];
+};
 
 /* Excluded from this release type: TelemetryEventPropertyTypes */
 
@@ -192,8 +253,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: ThresholdCounter */
 
-/* Excluded from this release type: TypedEventEmitter */
-
 /* Excluded from this release type: UsageError */
 
 /* Excluded from this release type: validatePrecondition */