@fluidframework/telemetry-utils 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.225277

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

@@ -0,0 +1,264 @@
+/// <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 */
+
+/* Excluded from this release type: createChildLogger */
+
+/* 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;
+}
+
+/* Excluded from this release type: ITelemetryLoggerPropertyBag */
+
+/* Excluded from this release type: ITelemetryLoggerPropertyBags */
+
+/**
+ * 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: TelemetryBaseEventPropertyType */
+
+/* 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)[];
+};
+
+/* Excluded from this release type: TelemetryEventPropertyTypes */
+
+/* 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 { }