@fluidframework/telemetry-utils 2.0.0-internal.7.2.2 → 2.0.0-internal.7.4.0

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

@@ -0,0 +1,1123 @@
+/// <reference types="node" />
+
+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';
+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';
+
+/**
+ * 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.
+ *
+ * @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;
+    namespace?: string;
+    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.
+ *
+ * @internal
+ */
+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}.
+ * You can chose to not provide an event sampler which is effectively a no-op, meaning that it will be treated as if the sampler always returns true.
+ *
+ * @remarks
+ * The sampling functionality uses the Fluid telemetry logging configuration along with the optionally provided event sampling callback to determine whether an event should
+ * be logged or not.
+ *
+ * Configuration object parameters:
+ * 'Fluid.Telemetry.DisableSampling': if this config value is set to true, all events will be unsampled and therefore logged.
+ * Otherwise only a sample will be logged according to the provided event sampler callback.
+ *
+ * Note that the same sampler is used for all APIs of the returned logger. If you want separate events flowing through the returned logger to be sampled separately, the {@link IEventSampler} you provide should track them separately.
+ *
+ * @internal
+ */
+export declare function createSampledLogger(logger: ITelemetryLoggerExt, eventSampler?: IEventSampler): ISampledTelemetryLogger;
+
+/**
+ * DataCorruptionError indicates that we encountered definitive evidence that the data at rest
+ * backing this container is corrupted, and this container would never be expected to load properly again
+ *
+ * @internal
+ */
+export declare class DataCorruptionError extends LoggingError implements IErrorBase, IFluidErrorBase {
+    readonly errorType: "dataCorruptionError";
+    readonly canRetry = false;
+    constructor(message: string, props: ITelemetryBaseProperties);
+}
+
+/**
+ * Indicates we hit a fatal error while processing incoming data from the Fluid Service.
+ *
+ * @remarks
+ *
+ * The error will often originate in the dataStore or DDS implementation that is responding to incoming changes.
+ * This differs from {@link DataCorruptionError} in that this may be a transient error that will not repro in another
+ * client or session.
+ *
+ * @internal
+ */
+export declare class DataProcessingError extends LoggingError implements IErrorBase, IFluidErrorBase {
+    /**
+     * {@inheritDoc IFluidErrorBase.errorType}
+     */
+    readonly errorType: "dataProcessingError";
+    readonly canRetry = false;
+    private constructor();
+    /**
+     * Create a new `DataProcessingError` detected and raised within the Fluid Framework.
+     */
+    static create(errorMessage: string, dataProcessingCodepath: string, sequencedMessage?: ISequencedDocumentMessage, props?: ITelemetryBaseProperties): IFluidErrorBase;
+    /**
+     * Wrap the given error in a `DataProcessingError`, unless the error is already of a known type
+     * with the exception of a normalized {@link LoggingError}, which will still be wrapped.
+     *
+     * In either case, the error will have some relevant properties added for telemetry.
+     *
+     * @remarks
+     *
+     * We wrap conditionally since known error types represent well-understood failure modes, and ideally
+     * one day we will move away from throwing these errors but rather we'll return them.
+     * But an unrecognized error needs to be classified as `DataProcessingError`.
+     *
+     * @param originalError - The error to be converted.
+     * @param dataProcessingCodepath - Which code-path failed while processing data.
+     * @param messageLike - Message to include info about via telemetry props.
+     *
+     * @returns Either a new `DataProcessingError`, or (if wrapping is deemed unnecessary) the given error.
+     */
+    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.
+ * @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
+ */
+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;
+}
+
+/**
+ * String used to concatenate the namespace of parent loggers and their child loggers.
+ * @internal
+ */
+export declare const eventNamespaceSeparator: ":";
+
+/**
+ * Inspect the given error for common "safe" props and return them.
+ *
+ * @internal
+ */
+export declare function extractLogSafeErrorProperties(error: unknown, sanitizeStack: boolean): {
+    message: string;
+    errorType?: string | undefined;
+    stack?: string | undefined;
+};
+
+/**
+ * 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;
+    messageSequenceNumber: number | undefined;
+    messageClientSequenceNumber: number | undefined;
+    messageReferenceSequenceNumber: number | undefined;
+    messageMinimumSequenceNumber: number | undefined;
+    messageTimestamp: number | undefined;
+};
+
+/**
+ * @internal
+ */
+export declare function formatTick(tick: number): number;
+
+/**
+ * The purpose of this function is to provide ability to capture stack context quickly.
+ * Accessing new Error().stack is slow, and the slowest part is accessing stack property itself.
+ * There are scenarios where we generate error with stack, but error is handled in most cases and
+ * stack property is not accessed.
+ * For such cases it's better to not read stack property right away, but rather delay it until / if it's needed
+ * Some browsers will populate stack right away, others require throwing Error, so we do auto-detection on the fly.
+ * @returns Error object that has stack populated.
+ *
+ * @internal
+ */
+export declare function generateErrorWithStack(): Error;
+
+/**
+ * Generate a stack at this callsite as if an error were thrown from here.
+ * @returns the callstack (does not throw)
+ *
+ * @internal
+ */
+export declare function generateStack(): string | undefined;
+
+/**
+ * Generic wrapper for an unrecognized/uncategorized error object
+ *
+ * @internal
+ */
+export declare class GenericError extends LoggingError implements IGenericError, IFluidErrorBase {
+    readonly error?: any;
+    readonly errorType: "genericError";
+    /**
+     * Create a new GenericError
+     * @param message - Error message
+     * @param error - inner error object
+     * @param props - Telemetry props to include when the error is logged
+     */
+    constructor(message: string, error?: any, props?: ITelemetryBaseProperties);
+}
+
+/**
+ * Borrowed from
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cyclic_object_value#examples}
+ * Avoids runtime errors with circular references.
+ * Not ideal, as will cut values that are not necessarily circular references.
+ * Could be improved by implementing Node's util.inspect() for browser (minus all the coloring code)
+ *
+ * @internal
+ */
+export declare const getCircularReplacer: () => (key: string, value: unknown) => any;
+
+/**
+ * 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.
+ *
+ * @internal
+ */
+export declare interface IConfigProvider extends IConfigProviderBase_2 {
+    getBoolean(name: string): boolean | undefined;
+    getNumber(name: string): number | undefined;
+    getString(name: string): string | undefined;
+    getBooleanArray(name: string): boolean[] | undefined;
+    getNumberArray(name: string): number[] | undefined;
+    getStringArray(name: string): string[] | undefined;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * An object that contains a callback used in conjunction with the {@link createSampledLogger} utility function to provide custom logic for sampling events.
+ *
+ * @internal
+ */
+export declare interface IEventSampler {
+    /**
+     * @returns true if the event should be sampled or false if not
+     */
+    sample: () => boolean | undefined;
+}
+
+/**
+ * Metadata to annotate an error object when annotating or normalizing it
+ *
+ * @internal
+ */
+export declare interface IFluidErrorAnnotations {
+    /**
+     * Telemetry props to log with the error
+     */
+    props?: ITelemetryBaseProperties;
+}
+
+/**
+ * An error emitted by the Fluid Framework.
+ *
+ * @remarks
+ *
+ * All normalized errors flowing through the Fluid Framework adhere to this readonly interface.
+ *
+ * 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 {
+    /**
+     * Classification of what type of error this is.
+     *
+     * @remarks Used programmatically by consumers to interpret the error.
+     */
+    readonly errorType: string;
+    /**
+     * Error's message property, made readonly.
+     *
+     * @remarks
+     *
+     * Recommendations:
+     *
+     * Be specific, but also take care when including variable data to consider suitability for aggregation in telemetry.
+     * Also avoid including any data that jeopardizes the user's privacy. Add a tagged telemetry property instead.
+     */
+    readonly message: string;
+    /**
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack}.
+     */
+    readonly stack?: string;
+    /**
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/name}.
+     */
+    readonly name: string;
+    /**
+     * A Guid identifying this error instance.
+     *
+     * @remarks
+     *
+     * Useful in telemetry for deduplicating multiple logging events arising from the same error,
+     * or correlating an error with an inner error that caused it, in case of error wrapping.
+     */
+    readonly errorInstanceId: string;
+    /**
+     * Get the telemetry properties stashed on this error for logging.
+     */
+    getTelemetryProperties(): ITelemetryProperties;
+    /**
+     * Add telemetry properties to this error which will be logged with the error
+     */
+    addTelemetryProperties: (props: ITelemetryProperties) => void;
+}
+
+/**
+ * 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;
+    end?: true;
+    cancel?: "generic" | "error";
+}
+
+/**
+ * A telemetry logger that has sampling capabilities
+ *
+ * @internal
+ */
+export declare interface ISampledTelemetryLogger extends ITelemetryLoggerExt {
+    /**
+     * Indicates if the feature flag to disable sampling is set.
+     *
+     * @remarks Exposed to enable some advanced scenarios where the code using the sampled logger
+     * could take advantage of skipping the execution of some logic when it can determine
+     * it won't be necessary because the telemetry event that needs it wouldn't be
+     * emitted anyway.
+     */
+    isSamplingDisabled: boolean;
+}
+
+/**
+ * True for any error object that is an (optionally normalized) external error
+ * False for any error we created and raised within the FF codebase via LoggingError base class,
+ * or wrapped in a well-known error type
+ *
+ * @internal
+ */
+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 {@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
+ * {@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">;
+
+/**
+ * A property to be logged to telemetry containing both the value and a tag. Tags are generic strings that can be used
+ * 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 {@link @fluidframework/core-interfaces#Tagged}\<{@link TelemetryEventPropertyTypeExt}\>
+ * @internal
+ */
+export declare interface ITaggedTelemetryPropertyTypeExt {
+    value: TelemetryEventPropertyTypeExt;
+    tag: string;
+}
+
+/**
+ * Error telemetry event.
+ * @remarks Maps to category = "error"
+ * @alpha
+ */
+export declare interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
+    eventName: string;
+}
+
+/**
+ * Interface for logging telemetry statements.
+ * @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;
+    eventName: string;
+}
+
+/**
+ * Informational (non-error) telemetry event
+ * @remarks Maps to category = "generic"
+ * @alpha
+ */
+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.
+ * @alpha
+ */
+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;
+}
+
+/**
+ * @internal
+ */
+export declare interface ITelemetryLoggerPropertyBag {
+    [index: string]: TelemetryEventPropertyTypes | (() => TelemetryEventPropertyTypes);
+}
+
+/**
+ * @internal
+ */
+export declare interface ITelemetryLoggerPropertyBags {
+    all?: ITelemetryLoggerPropertyBag;
+    error?: ITelemetryLoggerPropertyBag;
+}
+
+/**
+ * Performance telemetry event.
+ * @remarks Maps to category = "performance"
+ * @alpha
+ */
+export declare interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
+    duration?: number;
+}
+
+/**
+ * JSON-serializable properties, which will be logged with telemetry.
+ *
+ * @alpha
+ */
+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>;
+
+/**
+ * Base class for "trusted" errors we create, whose properties can generally be logged to telemetry safely.
+ * All properties set on the object, or passed in (via the constructor or addTelemetryProperties),
+ * will be logged in accordance with their tag, if present.
+ *
+ * PLEASE take care to avoid setting sensitive data on this object without proper tagging!
+ *
+ * @internal
+ */
+export declare class LoggingError extends Error implements ILoggingError, Omit<IFluidErrorBase, "errorType"> {
+    private readonly omitPropsFromLogging;
+    private _errorInstanceId;
+    get errorInstanceId(): string;
+    overwriteErrorInstanceId(id: string): void;
+    /**
+     * Backwards compatibility to appease {@link isFluidError} in old code that may handle this error.
+     */
+    private readonly fluidErrorCode;
+    /**
+     * Create a new LoggingError
+     * @param message - Error message to use for Error base class
+     * @param props - telemetry props to include on the error for when it's logged
+     * @param omitPropsFromLogging - properties by name to omit from telemetry props
+     */
+    constructor(message: string, props?: ITelemetryBaseProperties, omitPropsFromLogging?: Set<string>);
+    /**
+     * Determines if a given object is an instance of a LoggingError
+     * @param object - any object
+     * @returns true if the object is an instance of a LoggingError, false if not.
+     */
+    static typeCheck(object: unknown): object is LoggingError;
+    /**
+     * Add additional properties to be logged
+     */
+    addTelemetryProperties(props: ITelemetryBaseProperties): void;
+    /**
+     * Get all properties fit to be logged to telemetry for this error
+     */
+    getTelemetryProperties(): ITelemetryBaseProperties;
+}
+
+/**
+ * Like assert, but logs only if the condition is false, rather than throwing
+ * @param condition - The condition to attest too
+ * @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;
+
+/**
+ * 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;
+    events: ITelemetryBaseEvent[];
+    constructor(minLogLevel?: LogLevel | undefined);
+    clear(): void;
+    toTelemetryLogger(): ITelemetryLoggerExt;
+    send(event: ITelemetryBaseEvent): void;
+    /**
+     * Search events logged since the last time matchEvents was called, looking for the given expected
+     * events in order.
+     * @param expectedEvents - events in order that are expected to appear in the recorded log.
+     * @param inlineDetailsProp - true if the "details" property in the actual event should be extracted and inlined.
+     * 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(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], inlineDetailsProp?: boolean): boolean;
+    /**
+     * Asserts that matchEvents is true, and prints the actual/expected output if not.
+     */
+    assertMatch(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string, inlineDetailsProp?: boolean): void;
+    /**
+     * Search events logged since the last time matchEvents was called, looking for any of the given
+     * expected events.
+     * @param expectedEvents - events that are expected to appear in the recorded log.
+     * @param inlineDetailsProp - true if the "details" property in the actual event should be extracted and inlined.
+     * 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.
+     * @returns if any of the expected events is found.
+     */
+    matchAnyEvent(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], inlineDetailsProp?: boolean): boolean;
+    /**
+     * Asserts that matchAnyEvent is true, and prints the actual/expected output if not.
+     */
+    assertMatchAny(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string, inlineDetailsProp?: boolean): void;
+    /**
+     * Search events logged since the last time matchEvents was called, looking only for the given expected
+     * events in order.
+     * @param expectedEvents - events in order that are expected to be the only events in the recorded log.
+     * @param inlineDetailsProp - true if the "details" property in the actual event should be extracted and inlined.
+     * 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(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], inlineDetailsProp?: boolean): boolean;
+    /**
+     * Asserts that matchEvents is true, and prints the actual/expected output if not
+     */
+    assertMatchStrict(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string, inlineDetailsProp?: boolean): void;
+    /**
+     * Asserts that matchAnyEvent is false for the given events, and prints the actual/expected output if not
+     */
+    assertMatchNone(disallowedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string, inlineDetailsProp?: boolean): void;
+    private getMatchedEventsCount;
+    /**
+     * Ensure the expected event is a strict subset of the actual event
+     */
+    private static eventsMatch;
+}
+
+/**
+ * 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
+ *
+ * @internal
+ */
+export declare const NORMALIZED_ERROR_TYPE = "genericError";
+
+/**
+ * Normalize the given error yielding a valid Fluid Error
+ * @returns A valid Fluid Error with any provided annotations applied
+ * @param error - The error to normalize
+ * @param annotations - Annotations to apply to the normalized error
+ *
+ * @internal
+ */
+export declare function normalizeError(error: unknown, annotations?: IFluidErrorAnnotations): IFluidErrorBase;
+
+/**
+ * Attempts to parse number from 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).
+ *
+ * @internal
+ */
+export declare function numberFromString(str: string | null | undefined): string | number | undefined;
+
+/**
+ * Attempts to overwrite the error's stack
+ *
+ * There have been reports of certain JS environments where overwriting stack will throw.
+ * If that happens, this adds the given stack as the telemetry property "stack2"
+ *
+ * @internal
+ */
+export declare function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string): void;
+
+/**
+ * Helper class to log performance events.
+ *
+ * @internal
+ */
+export declare class PerformanceEvent {
+    private readonly logger;
+    private readonly markers;
+    private readonly recordHeapSize;
+    private readonly emitLogs;
+    /**
+     * Creates an instance of {@link PerformanceEvent} and starts measurements
+     * @param logger - the logger to be used for publishing events
+     * @param event - the logging event details which will be published with the performance measurements
+     * @param markers - See {@link IPerformanceEventMarkers}
+     * @param recordHeapSize - whether or not to also record memory performance
+     * @param emitLogs - should this instance emit logs. If set to false, logs will not be emitted to the logger,
+     * but measurements will still be performed and any specified markers will be generated.
+     * @returns An instance of {@link PerformanceEvent}
+     */
+    static start(logger: ITelemetryLoggerExt, event: ITelemetryGenericEvent, markers?: IPerformanceEventMarkers, recordHeapSize?: boolean, emitLogs?: boolean): PerformanceEvent;
+    /**
+     * Measure a synchronous task
+     * @param logger - the logger to be used for publishing events
+     * @param event - the logging event details which will be published with the performance measurements
+     * @param callback - the task to be executed and measured
+     * @param markers - See {@link IPerformanceEventMarkers}
+     * @param sampleThreshold - events with the same name and category will be sent to the logger
+     * only when we hit this many executions of the task. If unspecified, all events will be sent.
+     * @returns The results of the executed task
+     *
+     * @remarks Note that if the "same" event (category + eventName) would be emitted by different
+     * tasks (`callback`), `sampleThreshold` is still applied only based on the event's category + eventName,
+     * so executing either of the tasks will increase the internal counter and they
+     * effectively "share" the sampling rate for the event.
+     */
+    static timedExec<T>(logger: ITelemetryLoggerExt, event: ITelemetryGenericEvent, callback: (event: PerformanceEvent) => T, markers?: IPerformanceEventMarkers, sampleThreshold?: number): T;
+    /**
+     * Measure an asynchronous task
+     * @param logger - the logger to be used for publishing events
+     * @param event - the logging event details which will be published with the performance measurements
+     * @param callback - the task to be executed and measured
+     * @param markers - See {@link IPerformanceEventMarkers}
+     * @param recordHeapSize - whether or not to also record memory performance
+     * @param sampleThreshold - events with the same name and category will be sent to the logger
+     * only when we hit this many executions of the task. If unspecified, all events will be sent.
+     * @returns The results of the executed task
+     *
+     * @remarks Note that if the "same" event (category + eventName) would be emitted by different
+     * tasks (`callback`), `sampleThreshold` is still applied only based on the event's category + eventName,
+     * so executing either of the tasks will increase the internal counter and they
+     * effectively "share" the sampling rate for the event.
+     */
+    static timedExecAsync<T>(logger: ITelemetryLoggerExt, event: ITelemetryGenericEvent, callback: (event: PerformanceEvent) => Promise<T>, markers?: IPerformanceEventMarkers, recordHeapSize?: boolean, sampleThreshold?: number): Promise<T>;
+    get duration(): number;
+    private event?;
+    private readonly startTime;
+    private startMark?;
+    private startMemoryCollection;
+    protected constructor(logger: ITelemetryLoggerExt, event: ITelemetryGenericEvent, markers?: IPerformanceEventMarkers, recordHeapSize?: boolean, emitLogs?: boolean);
+    reportProgress(props?: ITelemetryProperties, eventNameSuffix?: string): void;
+    private autoEnd;
+    end(props?: ITelemetryProperties): void;
+    private performanceEndMark;
+    cancel(props?: ITelemetryProperties, error?: unknown): void;
+    /**
+     * Report the event, if it hasn't already been reported.
+     */
+    reportEvent(eventNameSuffix: string, props?: ITelemetryProperties, error?: unknown): void;
+    private static readonly eventHits;
+    private static shouldReport;
+}
+
+/**
+ * Raises events pertaining to the connection
+ * @param logger - The logger to log telemetry
+ * @param emitter - The event emitter instance
+ * @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.
+ *
+ * @internal
+ */
+export declare class SampledTelemetryHelper implements IDisposable {
+    private readonly eventBase;
+    private readonly logger;
+    private readonly sampleThreshold;
+    private readonly includeAggregateMetrics;
+    private readonly perBucketProperties;
+    disposed: boolean;
+    private readonly measurementsMap;
+    /**
+     * @param eventBase -
+     * Custom properties to include in the telemetry performance event when it is written.
+     * @param logger -
+     * The logger to use to write the telemetry performance event.
+     * @param sampleThreshold -
+     * Telemetry performance events will be generated every time we hit this many executions of the code block.
+     * @param includeAggregateMetrics -
+     * If set to `true`, the telemetry performance event will include aggregated metrics (total duration, min duration,
+     * max duration) for all the executions in between generated events.
+     * @param perBucketProperties -
+     * Map of strings that represent different buckets (which can be specified when calling the 'measure' method), to
+     * properties which should be added to the telemetry event for that bucket. If a bucket being measured does not
+     * have an entry in this map, no additional properties will be added to its telemetry events. The following keys are
+     * reserved for use by this class: "duration", "count", "totalDuration", "minDuration", "maxDuration". If any of
+     * them is specified as a key in one of the ITelemetryProperties objects in this map, that key-value pair will be
+     * ignored.
+     */
+    constructor(eventBase: ITelemetryGenericEvent, logger: ITelemetryLoggerExt, sampleThreshold: number, includeAggregateMetrics?: boolean, perBucketProperties?: Map<string, ITelemetryProperties>);
+    /**
+     * Executes the specified code and keeps track of execution time statistics.
+     * If it's been called enough times (the sampleThreshold for the class) then it generates a log message with the necessary information.
+     *
+     * @param codeToMeasure - The code to be executed and measured.
+     * @param bucket - A key to track executions of the code block separately.
+     * Each different value of this parameter has a separate set of executions and metrics tracked by the class.
+     * If no such distinction needs to be made, do not provide a value.
+     * @returns Whatever the passed-in code block returns.
+     */
+    measure<T>(codeToMeasure: () => T, bucket?: string): T;
+    private flushBucket;
+    dispose(error?: Error | undefined): void;
+}
+
+/**
+ * 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_2>;
+
+/**
+ * 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]>;
+        tag: TelemetryDataTag.CodeArtifact;
+    } : {
+        value: Exclude<T[P], undefined>;
+        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;
+    } : {
+        value: Exclude<V[P], undefined>;
+        tag: T;
+    }) | (V[P] extends undefined ? undefined : never); };
+
+/**
+ * @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;
+    constructor(logger: ITelemetryBaseLogger);
+    /**
+     * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseLogger.send}
+     */
+    send(eventWithTagsMaybe: ITelemetryBaseEvent): void;
+}
+
+/**
+ * Broad classifications to be applied to individual properties as they're prepared to be logged to telemetry.
+ *
+ * @privateRemarks Please do not modify existing entries, to maintain backwards compatibility.
+ *
+ * @internal
+ */
+export declare enum TelemetryDataTag {
+    /**
+     * Data containing terms or IDs from code packages that may have been dynamically loaded
+     */
+    CodeArtifact = "CodeArtifact",
+    /**
+     * Personal data of a variety of classifications that pertains to the user
+     */
+    UserData = "UserData"
+}
+
+/**
+ * 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 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.
+ *
+ * @alpha
+ */
+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;
+    sendTelemetryEvent(event: ITelemetryGenericEvent, error?: unknown): void;
+    sendErrorEvent(event: ITelemetryErrorEvent, error?: unknown): void;
+    sendPerformanceEvent(event: ITelemetryPerformanceEvent, error?: unknown): void;
+}
+
+/**
+ * Utility counter which will send event only if the provided value is above a configured threshold.
+ *
+ * @internal
+ */
+export declare class ThresholdCounter {
+    private readonly threshold;
+    private readonly logger;
+    private thresholdMultiple;
+    constructor(threshold: number, logger: ITelemetryLoggerExt, thresholdMultiple?: number);
+    /**
+     * Sends the value if it's above the treshold.
+     */
+    send(eventName: string, value: number): void;
+    /**
+     * Sends the value if it's above the threshold
+     * and a multiple of the threshold.
+     *
+     * To be used in scenarios where we'd like to record a
+     * threshold violation while reducing telemetry noise.
+     */
+    sendIfMultiple(eventName: string, value: number): void;
+}
+
+/**
+ * Error indicating an API is being used improperly resulting in an invalid operation.
+ *
+ * @internal
+ */
+export declare class UsageError extends LoggingError implements IUsageError, IFluidErrorBase {
+    readonly errorType: "usageError";
+    constructor(message: string, props?: ITelemetryBaseProperties);
+}
+
+/**
+ * Throws a UsageError with the given message if the condition is not met.
+ * Use this API when `false` indicates a precondition is not met on a public API (for any FF layer).
+ *
+ * @param condition - The condition that should be true, if the condition is false a UsageError will be thrown.
+ * @param message - The message to include in the error when the condition does not hold.
+ * @param props - Telemetry props to include on the error when the condition does not hold.
+ * @internal
+ */
+export declare function validatePrecondition(condition: boolean, message: string, props?: ITelemetryBaseProperties): asserts condition;
+
+/**
+ * Create a new error using newErrorFn, wrapping and caused by the given unknown error.
+ * Copies the inner error's stack, errorInstanceId and telemetry props over to the new error if present
+ * @param innerError - An error from untrusted/unknown origins
+ * @param newErrorFn - callback that will create a new error given the original error's message
+ * @returns A new error object "wrapping" the given error
+ *
+ * @internal
+ */
+export declare function wrapError<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T): T;
+
+/**
+ * The same as wrapError, but also logs the innerError, including the wrapping error's instance ID.
+ *
+ * @typeParam T - The kind of wrapper error to create.
+ *
+ * @internal
+ */
+export declare function wrapErrorAndLog<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T, logger: ITelemetryLoggerExt): T;
+
+export { }