@fluidframework/telemetry-utils 2.0.0-rc.4.0.5 → 2.0.0-rc.5.0.0

package/src/utils.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryBaseEvent } from "@fluidframework/core-interfaces";
+import type { ITelemetryBaseEvent } from "@fluidframework/core-interfaces";
 
 import { loggerToMonitoringContext } from "./config.js";
-import { ITelemetryGenericEventExt, ITelemetryLoggerExt } from "./telemetryTypes.js";
+import type { ITelemetryGenericEventExt, ITelemetryLoggerExt } from "./telemetryTypes.js";
 
 /**
  * An object that contains a callback used in conjunction with the {@link createSampledLogger} utility function to provide custom logic for sampling events.
@@ -56,6 +56,7 @@ export interface ISampledTelemetryLogger extends ITelemetryLoggerExt {
 export function createSampledLogger(
 	logger: ITelemetryLoggerExt,
 	eventSampler?: IEventSampler,
+	skipLoggingWhenSamplingIsDisabled?: boolean,
 ): ISampledTelemetryLogger {
 	const monitoringContext = loggerToMonitoringContext(logger);
 	const isSamplingDisabled =
@@ -66,22 +67,35 @@ export function createSampledLogger(
 			// The sampler uses the following logic for sending events:
 			// 1. If isSamplingDisabled is true, then this means events should be unsampled. Therefore we send the event without any checks.
 			// 2. If isSamplingDisabled is false, then event should be sampled using the event sampler, if the sampler is not defined just send all events, other use the eventSampler.sample() method.
+			// 3. If skipLoggingWhenSamplingIsDisabled is true, then no event is sent.
 			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				if (isSamplingDisabled && skipLoggingWhenSamplingIsDisabled) {
+					return;
+				}
 				logger.send(event);
 			}
 		},
 		sendTelemetryEvent: (event: ITelemetryGenericEventExt): void => {
 			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				if (isSamplingDisabled && skipLoggingWhenSamplingIsDisabled) {
+					return;
+				}
 				logger.sendTelemetryEvent(event);
 			}
 		},
 		sendErrorEvent: (event: ITelemetryGenericEventExt): void => {
 			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				if (isSamplingDisabled && skipLoggingWhenSamplingIsDisabled) {
+					return;
+				}
 				logger.sendErrorEvent(event);
 			}
 		},
 		sendPerformanceEvent: (event: ITelemetryGenericEventExt): void => {
 			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				if (isSamplingDisabled && skipLoggingWhenSamplingIsDisabled) {
+					return;
+				}
 				logger.sendPerformanceEvent(event);
 			}
 		},
@@ -90,3 +104,18 @@ export function createSampledLogger(
 
 	return sampledLogger;
 }
+
+/**
+ * Runs the specified function and returns an object with the time it took to run as well as any output from it.
+ * @remarks Useful in conjunction with {@link TelemetryEventBatcher}.
+ *
+ * @param codeToMeasure - The code to be executed and measured.
+ * @returns The total duration of the code execution and whatever the passed-in code block returns.
+ * @internal
+ */
+export function measure<T>(codeToMeasure: () => T): { duration: number; output: T } {
+	const start = performance.now();
+	const output = codeToMeasure();
+	const duration = performance.now() - start;
+	return { duration, output };
+}

package/tsconfig.json

@@ -4,6 +4,8 @@
 	"compilerOptions": {
 		"rootDir": "./src",
 		"outDir": "./lib",
+		"exactOptionalPropertyTypes": false,
+		"noUncheckedIndexedAccess": false,
 	},
 	"include": ["src/**/*"],
 }

package/tsdoc.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+	"extends": ["../../../common/build/build-common/tsdoc-base.json"]
+}

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

@@ -1,425 +0,0 @@
-## API Report File for "@fluidframework/telemetry-utils"
-
-> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
-
-```ts
-
-import { ConfigTypes } from '@fluidframework/core-interfaces';
-import type { EventEmitter } from '@fluid-internal/client-utils';
-import { EventEmitterEventType } from '@fluid-internal/client-utils';
-import { IConfigProviderBase } from '@fluidframework/core-interfaces';
-import type { IDisposable } from '@fluidframework/core-interfaces';
-import { IErrorBase } from '@fluidframework/core-interfaces';
-import { IEvent } from '@fluidframework/core-interfaces';
-import { IGenericError } from '@fluidframework/core-interfaces/internal';
-import type { ILoggingError } from '@fluidframework/core-interfaces/internal';
-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 { IUsageError } from '@fluidframework/core-interfaces/internal';
-import { Lazy } from '@fluidframework/core-utils/internal';
-import { LogLevel } from '@fluidframework/core-interfaces';
-import { Tagged } from '@fluidframework/core-interfaces';
-import { TelemetryBaseEventPropertyType } from '@fluidframework/core-interfaces';
-import { TypedEventEmitter } from '@fluid-internal/client-utils';
-
-// @internal (undocumented)
-export const connectedEventName = "connected";
-
-// @alpha
-export function createChildLogger(props?: {
-    logger?: ITelemetryBaseLogger;
-    namespace?: string;
-    properties?: ITelemetryLoggerPropertyBags;
-}): ITelemetryLoggerExt;
-
-// @internal
-export function createChildMonitoringContext(props: Parameters<typeof createChildLogger>[0]): MonitoringContext;
-
-// @internal
-export function createMultiSinkLogger(props: MultiSinkLoggerProperties): ITelemetryLoggerExt;
-
-// @internal
-export function createSampledLogger(logger: ITelemetryLoggerExt, eventSampler?: IEventSampler): ISampledTelemetryLogger;
-
-// @internal
-export class DataCorruptionError extends LoggingError implements IErrorBase, IFluidErrorBase {
-    constructor(message: string, props: ITelemetryBaseProperties);
-    // (undocumented)
-    readonly canRetry = false;
-    // (undocumented)
-    readonly errorType: "dataCorruptionError";
-}
-
-// @internal
-export class DataProcessingError extends LoggingError implements IErrorBase, IFluidErrorBase {
-    // (undocumented)
-    readonly canRetry = false;
-    static create(errorMessage: string, dataProcessingCodepath: string, sequencedMessage?: ISequencedDocumentMessage, props?: ITelemetryPropertiesExt): IFluidErrorBase;
-    readonly errorType: "dataProcessingError";
-    static wrapIfUnrecognized(originalError: unknown, dataProcessingCodepath: string, messageLike?: Partial<Pick<ISequencedDocumentMessage, "clientId" | "sequenceNumber" | "clientSequenceNumber" | "referenceSequenceNumber" | "minimumSequenceNumber" | "timestamp">>): IFluidErrorBase;
-}
-
-// @internal (undocumented)
-export const disconnectedEventName = "disconnected";
-
-// @alpha
-export class EventEmitterWithErrorHandling<TEvent extends IEvent = IEvent> extends TypedEventEmitter<TEvent> {
-    constructor(errorHandler: (eventName: EventEmitterEventType, error: any) => void);
-    // (undocumented)
-    emit(event: EventEmitterEventType, ...args: unknown[]): boolean;
-}
-
-// @internal
-export const eventNamespaceSeparator: ":";
-
-// @internal
-export function extractLogSafeErrorProperties(error: unknown, sanitizeStack: boolean): {
-    message: string;
-    errorType?: string | undefined;
-    stack?: string | undefined;
-};
-
-// @internal
-export 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 (undocumented)
-export function formatTick(tick: number): number;
-
-// @internal
-export function generateErrorWithStack(): Error;
-
-// @internal
-export function generateStack(): string | undefined;
-
-// @internal
-export class GenericError extends LoggingError implements IGenericError, IFluidErrorBase {
-    constructor(message: string, error?: any, props?: ITelemetryBaseProperties);
-    // (undocumented)
-    readonly error?: any;
-    // (undocumented)
-    readonly errorType: "genericError";
-}
-
-// @internal
-export const getCircularReplacer: () => (key: string, value: unknown) => any;
-
-// @internal
-export const hasErrorInstanceId: (x: unknown) => x is {
-    errorInstanceId: string;
-};
-
-// @internal
-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;
-}
-
-// @internal
-export interface IEventSampler {
-    // (undocumented)
-    sample: () => boolean | undefined;
-}
-
-// @internal
-export interface IFluidErrorAnnotations {
-    props?: ITelemetryBaseProperties;
-}
-
-// @internal
-export interface IFluidErrorBase extends Error {
-    addTelemetryProperties: (props: ITelemetryPropertiesExt) => void;
-    readonly errorInstanceId: string;
-    readonly errorType: string;
-    getTelemetryProperties(): ITelemetryBaseProperties;
-    readonly message: string;
-    readonly name: string;
-    readonly stack?: string;
-}
-
-// @internal
-export interface IPerformanceEventMarkers {
-    // (undocumented)
-    cancel?: "generic" | "error";
-    // (undocumented)
-    end?: true;
-    // (undocumented)
-    start?: true;
-}
-
-// @internal
-export interface ISampledTelemetryLogger extends ITelemetryLoggerExt {
-    isSamplingDisabled: boolean;
-}
-
-// @internal
-export function isExternalError(error: unknown): boolean;
-
-// @internal
-export function isFluidError(error: unknown): error is IFluidErrorBase;
-
-// @internal
-export const isILoggingError: (x: unknown) => x is ILoggingError;
-
-// @internal
-export function isTaggedTelemetryPropertyValue(x: Tagged<TelemetryEventPropertyTypeExt> | TelemetryEventPropertyTypeExt): x is Tagged<TelemetryEventPropertyTypeExt>;
-
-// @internal
-export function isValidLegacyError(error: unknown): error is Omit<IFluidErrorBase, "errorInstanceId">;
-
-// @internal @deprecated
-export interface ITaggedTelemetryPropertyTypeExt {
-    // (undocumented)
-    tag: string;
-    // (undocumented)
-    value: TelemetryEventPropertyTypeExt;
-}
-
-// @alpha
-export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
-    // (undocumented)
-    eventName: string;
-}
-
-// @internal
-export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
-    // (undocumented)
-    category: string;
-    // (undocumented)
-    eventName: string;
-}
-
-// @alpha
-export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
-    // (undocumented)
-    category?: TelemetryEventCategory;
-    // (undocumented)
-    eventName: string;
-}
-
-// @alpha
-export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
-    sendErrorEvent(event: ITelemetryErrorEventExt, error?: unknown): void;
-    sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.default): void;
-    sendTelemetryEvent(event: ITelemetryGenericEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.default): void;
-}
-
-// @alpha (undocumented)
-export interface ITelemetryLoggerPropertyBag {
-    // (undocumented)
-    [index: string]: TelemetryEventPropertyTypes | (() => TelemetryEventPropertyTypes);
-}
-
-// @alpha (undocumented)
-export interface ITelemetryLoggerPropertyBags {
-    // (undocumented)
-    all?: ITelemetryLoggerPropertyBag;
-    // (undocumented)
-    error?: ITelemetryLoggerPropertyBag;
-}
-
-// @alpha
-export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
-    // (undocumented)
-    duration?: number;
-}
-
-// @alpha
-export interface ITelemetryPropertiesExt {
-    // (undocumented)
-    [index: string]: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>;
-}
-
-// @internal
-export function loggerToMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLoggerExt>(logger: L): MonitoringContext<L>;
-
-// @internal
-export class LoggingError extends Error implements ILoggingError, Omit<IFluidErrorBase, "errorType"> {
-    constructor(message: string, props?: ITelemetryBaseProperties, omitPropsFromLogging?: Set<string>);
-    addTelemetryProperties(props: ITelemetryPropertiesExt): void;
-    // (undocumented)
-    get errorInstanceId(): string;
-    getTelemetryProperties(): ITelemetryBaseProperties;
-    // (undocumented)
-    overwriteErrorInstanceId(id: string): void;
-    static typeCheck(object: unknown): object is LoggingError;
-}
-
-// @internal
-export function mixinMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLoggerExt>(logger: L, ...configs: (IConfigProviderBase | undefined)[]): MonitoringContext<L>;
-
-// @alpha
-export class MockLogger implements ITelemetryBaseLogger {
-    constructor(minLogLevel?: LogLevel | undefined);
-    assertMatch(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string, inlineDetailsProp?: boolean): void;
-    assertMatchAny(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string, inlineDetailsProp?: boolean): void;
-    assertMatchNone(disallowedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string, inlineDetailsProp?: boolean): void;
-    assertMatchStrict(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string, inlineDetailsProp?: boolean): void;
-    // (undocumented)
-    clear(): void;
-    // (undocumented)
-    events: ITelemetryBaseEvent[];
-    matchAnyEvent(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], inlineDetailsProp?: boolean): boolean;
-    matchEvents(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], inlineDetailsProp?: boolean): boolean;
-    matchEventStrict(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], inlineDetailsProp?: boolean): boolean;
-    // (undocumented)
-    readonly minLogLevel?: LogLevel | undefined;
-    // (undocumented)
-    send(event: ITelemetryBaseEvent): void;
-    // (undocumented)
-    toTelemetryLogger(): ITelemetryLoggerExt;
-}
-
-// @internal
-export interface MonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLoggerExt> {
-    // (undocumented)
-    config: IConfigProvider;
-    // (undocumented)
-    logger: L;
-}
-
-// @internal
-export interface MultiSinkLoggerProperties {
-    loggers?: (ITelemetryBaseLogger | undefined)[];
-    namespace?: string;
-    properties?: ITelemetryLoggerPropertyBags;
-    tryInheritProperties?: true;
-}
-
-// @internal
-export const NORMALIZED_ERROR_TYPE = "genericError";
-
-// @internal
-export function normalizeError(error: unknown, annotations?: IFluidErrorAnnotations): IFluidErrorBase;
-
-// @internal
-export function numberFromString(str: string | null | undefined): string | number | undefined;
-
-// @internal
-export function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string): void;
-
-// @internal
-export class PerformanceEvent {
-    protected constructor(logger: ITelemetryLoggerExt, event: ITelemetryGenericEventExt, markers?: IPerformanceEventMarkers, emitLogs?: boolean);
-    // (undocumented)
-    cancel(props?: ITelemetryPropertiesExt, error?: unknown): void;
-    // (undocumented)
-    get duration(): number;
-    // (undocumented)
-    end(props?: ITelemetryPropertiesExt): void;
-    reportEvent(eventNameSuffix: string, props?: ITelemetryPropertiesExt, error?: unknown): void;
-    // (undocumented)
-    reportProgress(props?: ITelemetryPropertiesExt, eventNameSuffix?: string): void;
-    static start(logger: ITelemetryLoggerExt, event: ITelemetryGenericEventExt, markers?: IPerformanceEventMarkers, emitLogs?: boolean): PerformanceEvent;
-    static timedExec<T>(logger: ITelemetryLoggerExt, event: ITelemetryGenericEventExt, callback: (event: PerformanceEvent) => T, markers?: IPerformanceEventMarkers, sampleThreshold?: number): T;
-    static timedExecAsync<T>(logger: ITelemetryLoggerExt, event: ITelemetryGenericEventExt, callback: (event: PerformanceEvent) => Promise<T>, markers?: IPerformanceEventMarkers, sampleThreshold?: number): Promise<T>;
-}
-
-// @internal
-export function raiseConnectedEvent(logger: ITelemetryLoggerExt, emitter: EventEmitter, connected: boolean, clientId?: string, disconnectedReason?: string): void;
-
-// @internal (undocumented)
-export function safeRaiseEvent(emitter: EventEmitter, logger: ITelemetryLoggerExt, event: string, ...args: unknown[]): void;
-
-// @internal
-export class SampledTelemetryHelper implements IDisposable {
-    constructor(eventBase: ITelemetryGenericEventExt, logger: ITelemetryLoggerExt, sampleThreshold: number, includeAggregateMetrics?: boolean, perBucketProperties?: Map<string, ITelemetryBaseProperties>);
-    // (undocumented)
-    dispose(error?: Error | undefined): void;
-    // (undocumented)
-    disposed: boolean;
-    measure<T>(codeToMeasure: () => T, bucket?: string): T;
-}
-
-// @internal
-export const sessionStorageConfigProvider: Lazy<IConfigProviderBase>;
-
-// @internal
-export const tagCodeArtifacts: <T extends Record<string, TelemetryBaseEventPropertyType | (() => 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); };
-
-// @internal
-export const tagData: <T extends TelemetryDataTag, V extends Record<string, TelemetryBaseEventPropertyType | (() => 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); };
-
-// @internal @deprecated (undocumented)
-export class TaggedLoggerAdapter implements ITelemetryBaseLogger {
-    constructor(logger: ITelemetryBaseLogger);
-    send(eventWithTagsMaybe: ITelemetryBaseEvent): void;
-}
-
-// @internal
-export enum TelemetryDataTag {
-    CodeArtifact = "CodeArtifact",
-    UserData = "UserData"
-}
-
-// @alpha
-export type TelemetryEventCategory = "generic" | "error" | "performance";
-
-// @alpha
-export 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 (undocumented)
-export type TelemetryEventPropertyTypes = ITelemetryPropertiesExt[string];
-
-// @internal
-export class ThresholdCounter {
-    constructor(threshold: number, logger: ITelemetryLoggerExt, thresholdMultiple?: number);
-    send(eventName: string, value: number): void;
-    sendIfMultiple(eventName: string, value: number): void;
-}
-
-// @internal
-export class UsageError extends LoggingError implements IUsageError, IFluidErrorBase {
-    constructor(message: string, props?: ITelemetryBaseProperties);
-    // (undocumented)
-    readonly errorType: "usageError";
-}
-
-// @internal
-export function validatePrecondition(condition: boolean, message: string, props?: ITelemetryBaseProperties): asserts condition;
-
-// @internal
-export const wrapConfigProviderWithDefaults: (original: IConfigProviderBase | undefined, defaults: Record<string, ConfigTypes>) => IConfigProviderBase;
-
-// @internal
-export function wrapError<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T): T;
-
-// @internal
-export function wrapErrorAndLog<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T, logger: ITelemetryLoggerExt): T;
-
-// (No @packageDocumentation comment for this package)
-
-```