FluidFramework/api-report/telemetry-utils.api.md

API Report File for "@fluidframework/telemetry-utils"

Do not edit this file. It is a report generated by API Extractor.

import { EventEmitter } from 'events';
import { EventEmitterEventType } from '@fluidframework/common-utils';
import { IDebugger } from 'debug';
import { IDisposable } from '@fluidframework/common-definitions';
import { IEvent } from '@fluidframework/common-definitions';
import { ILoggingError } from '@fluidframework/common-definitions';
import { ITaggedTelemetryPropertyType } from '@fluidframework/common-definitions';
import { ITelemetryBaseEvent } from '@fluidframework/common-definitions';
import { ITelemetryBaseLogger } from '@fluidframework/common-definitions';
import { ITelemetryErrorEvent } from '@fluidframework/common-definitions';
import { ITelemetryGenericEvent } from '@fluidframework/common-definitions';
import { ITelemetryLogger } from '@fluidframework/common-definitions';
import { ITelemetryPerformanceEvent } from '@fluidframework/common-definitions';
import { ITelemetryProperties } from '@fluidframework/common-definitions';
import { Lazy } from '@fluidframework/common-utils';
import { TelemetryEventCategory } from '@fluidframework/common-definitions';
import { TelemetryEventPropertyType } from '@fluidframework/common-definitions';
import { TypedEventEmitter } from '@fluidframework/common-utils';

// @public
export class BaseTelemetryNullLogger implements ITelemetryBaseLogger {
    send(event: ITelemetryBaseEvent): void;
}

// @public
export class ChildLogger extends TelemetryLogger {
    // (undocumented)
    protected readonly baseLogger: ITelemetryBaseLogger;
    static create(baseLogger?: ITelemetryBaseLogger, namespace?: string, properties?: ITelemetryLoggerPropertyBags): TelemetryLogger;
    send(event: ITelemetryBaseEvent): void;
}

// @public (undocumented)
export type ConfigTypes = string | number | boolean | number[] | string[] | boolean[] | undefined;

// @public (undocumented)
export const connectedEventName = "connected";

// @public
export class DebugLogger extends TelemetryLogger {
    constructor(debug: IDebugger, debugErr: IDebugger, properties?: ITelemetryLoggerPropertyBags);
    static create(namespace: string, properties?: ITelemetryLoggerPropertyBags): TelemetryLogger;
    static mixinDebugLogger(namespace: string, baseLogger?: ITelemetryBaseLogger, properties?: ITelemetryLoggerPropertyBags): TelemetryLogger;
    send(event: ITelemetryBaseEvent): void;
}

// @public (undocumented)
export const disconnectedEventName = "disconnected";

// @public
export class EventEmitterWithErrorHandling<TEvent extends IEvent = IEvent> extends TypedEventEmitter<TEvent> {
    constructor(errorHandler: (eventName: EventEmitterEventType, error: any) => void);
    // (undocumented)
    emit(event: EventEmitterEventType, ...args: any[]): boolean;
}

// @public
export function extractLogSafeErrorProperties(error: any, sanitizeStack: boolean): {
    message: string;
    errorType?: string | undefined;
    stack?: string | undefined;
};

// @public
export function generateErrorWithStack(): Error;

// @public (undocumented)
export function generateStack(): string | undefined;

// @public
export const getCircularReplacer: () => (key: string, value: any) => any;

// @public (undocumented)
export const hasErrorInstanceId: (x: any) => x is {
    errorInstanceId: string;
};

// @public
export interface IConfigProvider extends IConfigProviderBase {
    // (undocumented)
    getBoolean(name: string): boolean | undefined;
    // (undocumented)
    getBooleanArray(name: string): boolean[] | undefined;
    // (undocumented)
    getNumber(name: string): number | undefined;
    // (undocumented)
    getNumberArray(name: string): number[] | undefined;
    // (undocumented)
    getString(name: string): string | undefined;
    // (undocumented)
    getStringArray(name: string): string[] | undefined;
}

// @public
export interface IConfigProviderBase {
    // (undocumented)
    getRawConfig(name: string): ConfigTypes;
}

// @public
export interface IFluidErrorAnnotations {
    props?: ITelemetryProperties;
}

// @public
export interface IFluidErrorBase extends Error {
    addTelemetryProperties: (props: ITelemetryProperties) => void;
    readonly errorInstanceId: string;
    readonly errorType: string;
    getTelemetryProperties(): ITelemetryProperties;
    readonly message: string;
    readonly name: string;
    readonly stack?: string;
}

// @public
export interface IPerformanceEventMarkers {
    // (undocumented)
    cancel?: "generic" | "error";
    // (undocumented)
    end?: true;
    // (undocumented)
    start?: true;
}

// @public
export function isExternalError(e: any): boolean;

// @public
export function isFluidError(e: any): e is IFluidErrorBase;

// @public
export const isILoggingError: (x: any) => x is ILoggingError;

// @public
export function isTaggedTelemetryPropertyValue(x: ITaggedTelemetryPropertyTypeExt | TelemetryEventPropertyTypeExt): x is ITaggedTelemetryPropertyType | ITaggedTelemetryPropertyTypeExt;

// @public
export function isValidLegacyError(e: any): e is Omit<IFluidErrorBase, "errorInstanceId">;

// @public
export interface ITaggedTelemetryPropertyTypeExt {
    // (undocumented)
    tag: string;
    // (undocumented)
    value: TelemetryEventPropertyTypeExt;
}

// @public
export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
    // (undocumented)
    eventName: string;
}

// @public
export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
    // (undocumented)
    category: string;
    // (undocumented)
    eventName: string;
}

// @public
export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
    // (undocumented)
    category?: TelemetryEventCategory;
    // (undocumented)
    eventName: string;
}

// @public
export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
    sendErrorEvent(event: ITelemetryErrorEventExt, error?: any): void;
    sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: any): void;
    sendTelemetryEvent(event: ITelemetryGenericEventExt, error?: any): void;
}

// @public (undocumented)
export interface ITelemetryLoggerPropertyBag {
    // (undocumented)
    [index: string]: TelemetryEventPropertyTypes | (() => TelemetryEventPropertyTypes);
}

// @public (undocumented)
export interface ITelemetryLoggerPropertyBags {
    // (undocumented)
    all?: ITelemetryLoggerPropertyBag;
    // (undocumented)
    error?: ITelemetryLoggerPropertyBag;
}

// @public
export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
    // (undocumented)
    duration?: number;
}

// @public
export interface ITelemetryPropertiesExt {
    // (undocumented)
    [index: string]: TelemetryEventPropertyTypeExt | ITaggedTelemetryPropertyTypeExt;
}

// @public (undocumented)
export function loggerToMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLogger>(logger: L): MonitoringContext<L>;

// @public
export class LoggingError extends Error implements ILoggingError, Omit<IFluidErrorBase, "errorType"> {
    constructor(message: string, props?: ITelemetryProperties, omitPropsFromLogging?: Set<string>);
    addTelemetryProperties(props: ITelemetryProperties): void;
    // (undocumented)
    get errorInstanceId(): string;
    getTelemetryProperties(): ITelemetryProperties;
    // (undocumented)
    overwriteErrorInstanceId(id: string): void;
    static typeCheck(object: unknown): object is LoggingError;
}

// @public
export function logIfFalse(condition: any, logger: ITelemetryBaseLogger, event: string | ITelemetryGenericEvent): condition is true;

// @public (undocumented)
export function mixinMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLogger>(logger: L, ...configs: (IConfigProviderBase | undefined)[]): MonitoringContext<L>;

// @public
export class MockLogger extends TelemetryLogger implements ITelemetryLogger {
    constructor();
    assertMatch(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string): void;
    assertMatchAny(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string): void;
    assertMatchNone(disallowedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string): void;
    assertMatchStrict(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string): void;
    // (undocumented)
    clear(): void;
    // (undocumented)
    events: ITelemetryBaseEvent[];
    matchAnyEvent(expectedEvents: Omit<ITelemetryBaseEvent, "category">[]): boolean;
    matchEvents(expectedEvents: Omit<ITelemetryBaseEvent, "category">[]): boolean;
    matchEventStrict(expectedEvents: Omit<ITelemetryBaseEvent, "category">[]): boolean;
    // (undocumented)
    send(event: ITelemetryBaseEvent): void;
}

// @public
export interface MonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLogger> {
    // (undocumented)
    config: IConfigProvider;
    // (undocumented)
    logger: L;
}

// @public
export class MultiSinkLogger extends TelemetryLogger {
    constructor(namespace?: string, properties?: ITelemetryLoggerPropertyBags);
    addLogger(logger?: ITelemetryBaseLogger): void;
    // (undocumented)
    protected loggers: ITelemetryBaseLogger[];
    send(event: ITelemetryBaseEvent): void;
}

// @public
export const NORMALIZED_ERROR_TYPE = "genericError";

// @public
export function normalizeError(error: unknown, annotations?: IFluidErrorAnnotations): IFluidErrorBase;

// @public
export class PerformanceEvent {
    protected constructor(logger: ITelemetryLogger, event: ITelemetryGenericEvent, markers?: IPerformanceEventMarkers);
    // (undocumented)
    cancel(props?: ITelemetryProperties, error?: any): void;
    // (undocumented)
    get duration(): number;
    // (undocumented)
    end(props?: ITelemetryProperties): void;
    reportEvent(eventNameSuffix: string, props?: ITelemetryProperties, error?: any): void;
    // (undocumented)
    reportProgress(props?: ITelemetryProperties, eventNameSuffix?: string): void;
    // (undocumented)
    static start(logger: ITelemetryLogger, event: ITelemetryGenericEvent, markers?: IPerformanceEventMarkers): PerformanceEvent;
    // (undocumented)
    static timedExec<T>(logger: ITelemetryLogger, event: ITelemetryGenericEvent, callback: (event: PerformanceEvent) => T, markers?: IPerformanceEventMarkers): T;
    // (undocumented)
    static timedExecAsync<T>(logger: ITelemetryLogger, event: ITelemetryGenericEvent, callback: (event: PerformanceEvent) => Promise<T>, markers?: IPerformanceEventMarkers): Promise<T>;
}

// @public
export function raiseConnectedEvent(logger: ITelemetryLogger, emitter: EventEmitter, connected: boolean, clientId?: string, disconnectedReason?: string): void;

// @public (undocumented)
export function safeRaiseEvent(emitter: EventEmitter, logger: ITelemetryLogger, event: string, ...args: any[]): void;

// @public
export class SampledTelemetryHelper implements IDisposable {
    constructor(eventBase: ITelemetryGenericEvent, logger: ITelemetryLogger, sampleThreshold: number, includeAggregateMetrics?: boolean, perBucketProperties?: Map<string, ITelemetryProperties>);
    // (undocumented)
    dispose(error?: Error | undefined): void;
    // (undocumented)
    disposed: boolean;
    // (undocumented)
    measure<T>(codeToMeasure: () => T, bucket?: string): T;
}

// @public
export const sessionStorageConfigProvider: Lazy<IConfigProviderBase>;

// @public @deprecated (undocumented)
export class TaggedLoggerAdapter implements ITelemetryBaseLogger {
    constructor(logger: ITelemetryBaseLogger);
    // (undocumented)
    send(eventWithTagsMaybe: ITelemetryBaseEvent): void;
}

// @public
export enum TelemetryDataTag {
    CodeArtifact = "CodeArtifact",
    UserData = "UserData"
}

// @public
export type TelemetryEventPropertyTypeExt = string | number | boolean | undefined | (string | number | boolean)[];

// @public (undocumented)
export type TelemetryEventPropertyTypes = TelemetryEventPropertyType | ITaggedTelemetryPropertyType;

// @public
export abstract class TelemetryLogger implements ITelemetryLoggerExt {
    constructor(namespace?: string | undefined, properties?: ITelemetryLoggerPropertyBags | undefined);
    // (undocumented)
    static readonly eventNamespaceSeparator = ":";
    // (undocumented)
    static formatTick(tick: number): number;
    // (undocumented)
    protected readonly namespace?: string | undefined;
    static numberFromString(str: string | null | undefined): string | number | undefined;
    static prepareErrorObject(event: ITelemetryBaseEvent, error: any, fetchStack: boolean): void;
    // (undocumented)
    protected prepareEvent(event: ITelemetryBaseEvent): ITelemetryBaseEvent;
    // (undocumented)
    protected readonly properties?: ITelemetryLoggerPropertyBags | undefined;
    // (undocumented)
    static sanitizePkgName(name: string): string;
    abstract send(event: ITelemetryBaseEvent): void;
    sendErrorEvent(event: ITelemetryErrorEvent, error?: any): void;
    sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: any): void;
    sendTelemetryEvent(event: ITelemetryGenericEventExt, error?: any): void;
    protected sendTelemetryEventCore(event: ITelemetryGenericEventExt & {
        category: TelemetryEventCategory;
    }, error?: any): void;
}

// @public
export class TelemetryNullLogger implements ITelemetryLogger {
    // (undocumented)
    send(event: ITelemetryBaseEvent): void;
    // (undocumented)
    sendErrorEvent(event: ITelemetryErrorEvent, error?: any): void;
    // (undocumented)
    sendPerformanceEvent(event: ITelemetryPerformanceEvent, error?: any): void;
    // (undocumented)
    sendTelemetryEvent(event: ITelemetryGenericEvent, error?: any): void;
}

// @public
export class TelemetryUTLogger implements ITelemetryLogger {
    // (undocumented)
    debugAssert(condition: boolean, event?: ITelemetryErrorEvent): void;
    // (undocumented)
    logException(event: ITelemetryErrorEvent, exception: any): void;
    // (undocumented)
    logGenericError(eventName: string, error: any): void;
    // (undocumented)
    send(event: ITelemetryBaseEvent): void;
    // (undocumented)
    sendErrorEvent(event: ITelemetryErrorEvent, error?: any): void;
    // (undocumented)
    sendPerformanceEvent(event: ITelemetryPerformanceEvent, error?: any): void;
    // (undocumented)
    sendTelemetryEvent(event: ITelemetryGenericEvent, error?: any): void;
    // (undocumented)
    shipAssert(condition: boolean, event?: ITelemetryErrorEvent): void;
}

// @public
export class ThresholdCounter {
    constructor(threshold: number, logger: ITelemetryLogger, thresholdMultiple?: number);
    send(eventName: string, value: number): void;
    sendIfMultiple(eventName: string, value: number): void;
}

// @public
export function wrapError<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T): T;

// @public
export function wrapErrorAndLog<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T, logger: ITelemetryLogger): T;

// (No @packageDocumentation comment for this package)