@fluidframework/telemetry-utils Package

Interfaces

Interface	Description
IConfigProvider	Explicitly typed interface for reading configurations
IConfigProviderBase	Base interface for providing configurations to enable/disable/control features
IFluidErrorAnnotations	Metadata to annotate an error object when annotating or normalizing it
IFluidErrorBase	All normalized errors flowing through the Fluid Framework adhere to this readonly interface. It features errorType and errorInstanceId on top of Error's members as readonly, and a getter/setter for telemetry props to be included when the error is logged.
IPerformanceEventMarkers	Describes what events PerformanceEvent should log By default, all events are logged, but client can override this behavior For example, there is rarely a need to record start event, as we really after success / failure tracking, including duration (on success).
ITelemetryLoggerPropertyBag
ITelemetryLoggerPropertyBags
MonitoringContext	A type containing both a telemetry logger and a configuration provider

Classes

Class	Alerts	Description
ChildLogger		ChildLogger class contains various helper telemetry methods, encoding in one place schemas for various types of Fluid telemetry events. Creates sub-logger that appends properties to all events
DebugLogger		Implementation of debug logger
EventEmitterWithErrorHandling		Event Emitter helper class Any exceptions thrown by listeners will be caught and raised through "error" event. Any exception thrown by "error" listeners will propagate to the caller.
LoggingError		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!
MockLogger		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.
MultiSinkLogger		Multi-sink logger Takes multiple ITelemetryBaseLogger objects (sinks) and logs all events into each sink Implements ITelemetryBaseLogger (through static create() method)
PerformanceEvent		Helper class to log performance events
SampledTelemetryHelper		Helper class that executes a specified code block and writes an @fluidframework/common-definitions#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.
TaggedLoggerAdapter	Deprecated
TelemetryLogger		TelemetryLogger class contains various helper telemetry methods, encoding in one place schemas for various types of Fluid telemetry events. Creates sub-logger that appends properties to all events
TelemetryUTLogger		Logger that is useful for UT It can be used in places where logger instance is required, but events should be not send over.
ThresholdCounter		Utility counter which will send event only if the provided value is above a configured threshold

Enumerations

Enum	Description
TelemetryDataTag	Broad classifications to be applied to individual properties as they're prepared to be logged to telemetry. Please do not modify existing entries for backwards compatibility.

Types

TypeAlias	Description
ConfigTypes
TelemetryEventPropertyTypes

Functions

Function	Return Type	Description
extractLogSafeErrorProperties(error, sanitizeStack)	{ message: string; errorType?: string | undefined; stack?: string | undefined; }	Inspect the given error for common "safe" props and return them
generateErrorWithStack()	Error	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.
generateStack()	string | undefined
isExternalError(e)	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, or wrapped in a well-known error type
isFluidError(e)	e is IFluidErrorBase	type guard for IFluidErrorBase interface
isTaggedTelemetryPropertyValue(x)	x is ITaggedTelemetryPropertyType	Type guard to identify if a particular value (loosely) appears to be a tagged telemetry property
isValidLegacyError(e)	e is Omit<IFluidErrorBase, "errorInstanceId">	type guard for old standard of valid/known errors
loggerToMonitoringContext(logger)	MonitoringContext<L>
logIfFalse(condition, logger, event)	condition is true	Like assert, but logs only if the condition is false, rather than throwing
mixinMonitoringContext(logger, configs)	MonitoringContext<L>
normalizeError(error, annotations)	IFluidErrorBase	Normalize the given error yielding a valid Fluid Error
raiseConnectedEvent(logger, emitter, connected, clientId)	void
safeRaiseEvent(emitter, logger, event, args)	void
wrapError(innerError, newErrorFn)	T	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
wrapErrorAndLog(innerError, newErrorFn, logger)	T	The same as wrapError, but also logs the innerError, including the wrapping error's instance id

Variables

Variable	Type	Description
connectedEventName
disconnectedEventName
getCircularReplacer	() => (key: string, value: any) => any	Borrowed from 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)
hasErrorInstanceId	(x: any) => x is { errorInstanceId: string; }
isILoggingError	(x: any) => x is ILoggingError	type guard for ILoggingError interface
sessionStorageConfigProvider	Lazy<IConfigProviderBase>	Creates a base configuration provider based on sessionStorage

Function Details

extractLogSafeErrorProperties

Inspect the given error for common "safe" props and return them

Signature

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

Parameters

Parameter	Type	Description
error	any
sanitizeStack	boolean

Returns

Return type: { message: string; errorType?: string | undefined; stack?: string | undefined; }

generateErrorWithStack

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.

Signature

export declare function generateErrorWithStack(): Error;

Returns

Error object that has stack populated.

Return type: Error

generateStack

Signature

export declare function generateStack(): string | undefined;

Returns

Return type: string | undefined

isExternalError

True for any error object that is an (optionally normalized) external error False for any error we created and raised within the FF codebase, or wrapped in a well-known error type

Signature

export declare function isExternalError(e: any): boolean;

Parameters

Parameter	Type	Description
e	any

Returns

Return type: boolean

isFluidError

type guard for IFluidErrorBase interface

Signature

export declare function isFluidError(e: any): e is IFluidErrorBase;

Parameters

Parameter	Type	Description
e	any

Returns

Return type: e is IFluidErrorBase

isTaggedTelemetryPropertyValue

Type guard to identify if a particular value (loosely) appears to be a tagged telemetry property

Signature

export declare function isTaggedTelemetryPropertyValue(x: any): x is ITaggedTelemetryPropertyType;

Parameters

Parameter	Type	Description
x	any

Returns

Return type: x is ITaggedTelemetryPropertyType

isValidLegacyError

type guard for old standard of valid/known errors

Signature

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

Parameters

Parameter	Type	Description
e	any

Returns

Return type: e is Omit<IFluidErrorBase, "errorInstanceId">

loggerToMonitoringContext

Signature

export declare function loggerToMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLogger>(logger: L): MonitoringContext<L>;

Type Parameters

Parameter	Constraint	Default	Description
L	ITelemetryBaseLogger	ITelemetryLogger

Parameters

Parameter	Type	Description
logger	L

Returns

Return type: MonitoringContext<L>

logIfFalse

Like assert, but logs only if the condition is false, rather than throwing

Signature

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

Parameters

Parameter	Type	Description
condition	any	The condition to attest too
logger	ITelemetryBaseLogger	The logger to log with
event	string | ITelemetryGenericEvent	The string or event to log

Returns

• The outcome of the condition

Return type: condition is true

mixinMonitoringContext

Signature

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

Type Parameters

Parameter	Constraint	Default	Description
L	ITelemetryBaseLogger	ITelemetryLogger

Parameters

Parameter	Type	Description
logger	L
configs	(IConfigProviderBase | undefined)[]

Returns

Return type: MonitoringContext<L>

normalizeError

Normalize the given error yielding a valid Fluid Error

Signature

export declare function normalizeError(error: unknown, annotations?: IFluidErrorAnnotations): IFluidErrorBase;

Parameters

Parameter	Modifiers	Type	Description
error		unknown	The error to normalize
annotations	optional	IFluidErrorAnnotations	Annotations to apply to the normalized error

Returns

A valid Fluid Error with any provided annotations applied

Return type: IFluidErrorBase

raiseConnectedEvent

Signature

export declare function raiseConnectedEvent(logger: ITelemetryLogger, emitter: EventEmitter, connected: boolean, clientId?: string): void;

Parameters

Parameter	Modifiers	Type	Description
logger		ITelemetryLogger
emitter		EventEmitter
connected		boolean
clientId	optional	string

safeRaiseEvent

Signature

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

Parameters

Parameter	Type	Description
emitter	EventEmitter
logger	ITelemetryLogger
event	string
args	any[]

wrapError

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

Signature

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

Type Parameters

Parameter	Constraint	Description
T	LoggingError

Parameters

Parameter	Type	Description
innerError	unknown	An error from untrusted/unknown origins
newErrorFn	(message: string) => T	callback that will create a new error given the original error's message

Returns

A new error object "wrapping" the given error

Return type: T

wrapErrorAndLog

The same as wrapError, but also logs the innerError, including the wrapping error's instance id

Signature

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

Type Parameters

Parameter	Constraint	Description
T	LoggingError

Parameters

Parameter	Type	Description
innerError	unknown
newErrorFn	(message: string) => T
logger	ITelemetryLogger

Returns

Return type: T

Variable Details

connectedEventName

Signature

connectedEventName = "connected"

disconnectedEventName

Signature

disconnectedEventName = "disconnected"

getCircularReplacer

Borrowed from 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)

Signature

getCircularReplacer: () => (key: string, value: any) => any

Type: () => (key: string, value: any) => any

hasErrorInstanceId

Signature

hasErrorInstanceId: (x: any) => x is {
    errorInstanceId: string;
}

Type: (x: any) => x is { errorInstanceId: string; }

isILoggingError

type guard for ILoggingError interface

Signature

isILoggingError: (x: any) => x is ILoggingError

Type: (x: any) => x is ILoggingError

sessionStorageConfigProvider

Creates a base configuration provider based on sessionStorage

Signature

sessionStorageConfigProvider: Lazy<IConfigProviderBase>

Type: Lazy<IConfigProviderBase>