Skip to content

improvement(client-telemetry-utils): BREAKING CHANGE: type erase ITelemetryLoggerExt #27476

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
jason-ha wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

improvement(client-telemetry-utils): BREAKING CHANGE: type erase ITelemetryLoggerExt #27476

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d0dc836
improvement(client-telemetry-utils): BREAKING CHANGE: type erase `ITe…
jason-ha Jun 3, 2026
609356a
merge: 'main' into test/client/type-erase-ITelemetryLoggerExt
jason-ha Jun 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/hungry-pianos-grab.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
"@fluidframework/telemetry-utils": minor
"__section": breaking
---
Deprecated ITelemetryLoggerExt methods and related types removed

Methods on `ITelemetryLoggerExt` are removed except for `send` inherited from `ITelemetryBaseLogger`.

See issue [#26910](https://github.com/microsoft/FluidFramework/issues/26910) for complete details.
6 changes: 5 additions & 1 deletion packages/framework/aqueduct/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,11 @@
"typescript": "~5.4.5"
},
"typeValidation": {
"broken": {},
"broken": {
"Interface_DataObjectFactoryProps": {
"backCompat": false
}
},
"entrypoint": "legacy"
}
}
1 change: 1 addition & 0 deletions packages/framework/aqueduct/src/test/types/validateAqueductPrevious.generated.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -276,6 +276,7 @@ declare type old_as_current_for_Interface_DataObjectFactoryProps = requireAssign
* typeValidation.broken:
* "Interface_DataObjectFactoryProps": {"backCompat": false}
*/
// @ts-expect-error compatibility expected to be broken
declare type current_as_old_for_Interface_DataObjectFactoryProps = requireAssignableTo<TypeOnly<current.DataObjectFactoryProps<never>>, TypeOnly<old.DataObjectFactoryProps<never>>>

/*
Expand Down
12 changes: 11 additions & 1 deletion packages/loader/container-loader/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,7 +221,17 @@
"typescript": "~5.4.5"
},
"typeValidation": {
"broken": {},
"broken": {
"Class_Loader": {
"backCompat": false
},
"ClassStatics_Loader": {
"backCompat": false
},
"Interface_ILoaderServices": {
"backCompat": false
}
},
"entrypoint": "legacy"
}
}
3 changes: 3 additions & 0 deletions packages/loader/container-loader/src/test/types/validateContainerLoaderPrevious.generated.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ declare type old_as_current_for_Class_Loader = requireAssignableTo<TypeOnly<old.
* typeValidation.broken:
* "Class_Loader": {"backCompat": false}
*/
// @ts-expect-error compatibility expected to be broken
declare type current_as_old_for_Class_Loader = requireAssignableTo<TypeOnly<current.Loader>, TypeOnly<old.Loader>>

/*
Expand All @@ -42,6 +43,7 @@ declare type current_as_old_for_Class_Loader = requireAssignableTo<TypeOnly<curr
* typeValidation.broken:
* "ClassStatics_Loader": {"backCompat": false}
*/
// @ts-expect-error compatibility expected to be broken
declare type current_as_old_for_ClassStatics_Loader = requireAssignableTo<TypeOnly<typeof current.Loader>, TypeOnly<typeof old.Loader>>

/*
Expand Down Expand Up @@ -240,6 +242,7 @@ declare type old_as_current_for_Interface_ILoaderServices = requireAssignableTo<
* typeValidation.broken:
* "Interface_ILoaderServices": {"backCompat": false}
*/
// @ts-expect-error compatibility expected to be broken
declare type current_as_old_for_Interface_ILoaderServices = requireAssignableTo<TypeOnly<current.ILoaderServices>, TypeOnly<old.ILoaderServices>>

/*
Expand Down
9 changes: 8 additions & 1 deletion packages/runtime/datastore/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,14 @@
"typescript": "~5.4.5"
},
"typeValidation": {
"broken": {},
"broken": {
"Class_FluidDataStoreRuntime": {
"backCompat": false
},
"ClassStatics_FluidDataStoreRuntime": {
"backCompat": false
}
},
"entrypoint": "legacy"
}
}
2 changes: 2 additions & 0 deletions packages/runtime/datastore/src/test/types/validateDatastorePrevious.generated.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ declare type old_as_current_for_Class_FluidDataStoreRuntime = requireAssignableT
* typeValidation.broken:
* "Class_FluidDataStoreRuntime": {"backCompat": false}
*/
// @ts-expect-error compatibility expected to be broken
declare type current_as_old_for_Class_FluidDataStoreRuntime = requireAssignableTo<TypeOnly<current.FluidDataStoreRuntime>, TypeOnly<old.FluidDataStoreRuntime>>

/*
Expand Down Expand Up @@ -60,6 +61,7 @@ declare type current_as_old_for_Class_FluidObjectHandle = requireAssignableTo<Ty
* typeValidation.broken:
* "ClassStatics_FluidDataStoreRuntime": {"backCompat": false}
*/
// @ts-expect-error compatibility expected to be broken
declare type current_as_old_for_ClassStatics_FluidDataStoreRuntime = requireAssignableTo<TypeOnly<typeof current.FluidDataStoreRuntime>, TypeOnly<typeof old.FluidDataStoreRuntime>>

/*
Expand Down
9 changes: 8 additions & 1 deletion packages/runtime/test-runtime-utils/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,14 @@
"typescript": "~5.4.5"
},
"typeValidation": {
"broken": {},
"broken": {
"Class_MockFluidDataStoreContext": {
"backCompat": false
},
"ClassStatics_MockFluidDataStoreContext": {
"backCompat": false
}
},
"entrypoint": "legacy"
}
}
2 changes: 2 additions & 0 deletions ...s/runtime/test-runtime-utils/src/test/types/validateTestRuntimeUtilsPrevious.generated.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,7 @@ declare type old_as_current_for_Class_MockFluidDataStoreContext = requireAssigna
* typeValidation.broken:
* "Class_MockFluidDataStoreContext": {"backCompat": false}
*/
// @ts-expect-error compatibility expected to be broken
declare type current_as_old_for_Class_MockFluidDataStoreContext = requireAssignableTo<TypeOnly<current.MockFluidDataStoreContext>, TypeOnly<old.MockFluidDataStoreContext>>

/*
Expand Down Expand Up @@ -357,6 +358,7 @@ declare type current_as_old_for_ClassStatics_MockDeltaQueue = requireAssignableT
* typeValidation.broken:
* "ClassStatics_MockFluidDataStoreContext": {"backCompat": false}
*/
// @ts-expect-error compatibility expected to be broken
declare type current_as_old_for_ClassStatics_MockFluidDataStoreContext = requireAssignableTo<TypeOnly<typeof current.MockFluidDataStoreContext>, TypeOnly<typeof old.MockFluidDataStoreContext>>

/*
Expand Down
5 changes: 2 additions & 3 deletions packages/utils/telemetry-utils/DEV.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,8 @@ This can include non-deprecated versions of externally accessible APIs and/or AP
## ITelemetryLoggerExt external deprecation

Internally `TelemetryLoggerExt` maybe used to access internal, extended logger. Externally `ITelemetryLoggerExt` is passed around.
Until a breaking change can be made these two types are structurally equivalent and must remain so.
The one difference is that `ITelemetryLoggerExt` has `@deprecated` methods to discourage use.
Once breaking change can be made, `ITelemetryLoggerExt` will become a branded type without any viable methods and thus neither external nor internal code may act upon it.
Temporarily, `ITelemetryLoggerExt` imported from `@fluidframework/telemetry-utils/internal` is a type alias to `TelemetryLoggerExt` to reduce internal churn.
Copy link
Copy Markdown
Contributor

@Josmithr Josmithr Jun 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have a backlog item tracking this cleanup? Would be nice if all of the relevant temporary export notes could include a TODO note referencing that item. Would make it easier to find and cleanup everything relevant when we tackle that item.

Copy link
Copy Markdown
Contributor

@MarioJGMsoft MarioJGMsoft Jun 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm already doing the cleanup here: #27484

All such imports should be replaced with direct `TelemetryLoggerExt` use.
Internally, `extractTelemetryLoggerExt` can be used to get `TelemetryLoggerExt` from `ITelemetryLoggerExt`.
These transitions are already put in place and should be preserved.
Similarly, `toITelemetryLoggerExt` can be used to go the other direction.
Expand Down
27 changes: 1 addition & 26 deletions packages/utils/telemetry-utils/api-report/telemetry-utils.legacy.beta.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,25 +18,8 @@ export class EventEmitterWithErrorHandling<TEvent extends IEvent = IEvent> exten
emit(event: EventEmitterEventType, ...args: unknown[]): boolean;
}

// @beta @deprecated @legacy
export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
eventName: string;
}

// @beta @deprecated @legacy
export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
category?: TelemetryEventCategory;
eventName: string;
}

// @beta @sealed @legacy
export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
// @deprecated
sendErrorEvent(event: ITelemetryErrorEventExt, error?: unknown): void;
// @deprecated
sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.info): void;
// @deprecated
sendTelemetryEvent(event: ITelemetryGenericEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.info): void;
export interface ITelemetryLoggerExt extends ErasedType<"TelemetryLoggerExt">, ITelemetryBaseLogger {
}

// @beta @legacy (undocumented)
Expand All @@ -50,17 +33,9 @@ export interface ITelemetryLoggerPropertyBags {
error?: ITelemetryLoggerPropertyBag;
}

// @beta @deprecated @legacy
export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
duration?: number;
}

// @beta @legacy
export type ITelemetryPropertiesExt = Record<string, TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>>;

// @beta @deprecated @legacy
export type TelemetryEventCategory = "generic" | "error" | "performance";

// @beta @legacy
export type TelemetryEventPropertyTypeExt = string | number | boolean | undefined | (string | number | boolean)[] | Record<string, string | number | boolean | undefined | (string | number | boolean)[]>;

Expand Down
22 changes: 21 additions & 1 deletion packages/utils/telemetry-utils/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,27 @@
"typescript": "~5.4.5"
},
"typeValidation": {
"broken": {},
"broken": {
"Interface_ITelemetryErrorEventExt": {
"backCompat": false,
"forwardCompat": false
},
"Interface_ITelemetryGenericEventExt": {
"backCompat": false,
"forwardCompat": false
},
"Interface_ITelemetryLoggerExt": {
"backCompat": false
},
"Interface_ITelemetryPerformanceEventExt": {
"backCompat": false,
"forwardCompat": false
},
"TypeAlias_TelemetryEventCategory": {
"backCompat": false,
"forwardCompat": false
}
},
"entrypoint": "legacy"
}
}
8 changes: 3 additions & 5 deletions packages/utils/telemetry-utils/src/api.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,11 @@
// eslint-disable-next-line no-restricted-syntax
export * from "./main.js";

// Additional APIs that are deprecated and thus left out of the common export set.
// Additional APIs that are special and thus left out of the common export set.
export type {
ITelemetryErrorEventExt,
ITelemetryGenericEventExt,
// ITelemetryLoggerExt is temporarily set to an alias of `TelemetryLoggerExt` when imported from "/internal".
Copy link
Copy Markdown
Contributor

@Josmithr Josmithr Jun 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When can this be removed? We should probably be explicit about that in the comment here.

Copy link
Copy Markdown
Contributor Author

@jason-ha jason-ha Jun 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whenever. Right now or later. @MarioJGMsoft has AB#74860. Likely it will happen before this PR merges, but if not, I'll add reference in here.

Copy link
Copy Markdown
Contributor

@MarioJGMsoft MarioJGMsoft Jun 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I opened this PR to remove the code: #27484

// Add it to "/legacy" export set here.
ITelemetryLoggerExt,
ITelemetryPerformanceEventExt,
TelemetryEventCategory,
} from "./telemetryTypes.js";

// ----------------------------------------------------------------------------
Expand Down
77 changes: 16 additions & 61 deletions packages/utils/telemetry-utils/src/telemetryTypes.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,12 @@
* Licensed under the MIT License.
*/

import type { ITelemetryBaseLogger, LogLevel, Tagged } from "@fluidframework/core-interfaces";
import type {
ErasedType,
ITelemetryBaseLogger,
LogLevel,
Tagged,
} from "@fluidframework/core-interfaces";

/**
* The categories FF uses when instrumenting the code.
Expand All @@ -13,9 +18,8 @@ import type { ITelemetryBaseLogger, LogLevel, Tagged } from "@fluidframework/cor
* 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
* @deprecated This type is being removed without a replacement.
* @see {@link https://github.com/microsoft/FluidFramework/issues/26910 | Issue #26910} for details.
* @legacy @beta
*
* @internal
*/
export type TelemetryEventCategory = "generic" | "error" | "performance";

Expand Down Expand Up @@ -67,9 +71,7 @@ export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
/**
* Informational (non-error) telemetry event
* @remarks Maps to category = "generic"
* @deprecated This type is being removed without a replacement.
* @see {@link https://github.com/microsoft/FluidFramework/issues/26910 | Issue #26910} for details.
* @legacy @beta
* @internal
*/
export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
/**
Expand All @@ -87,9 +89,7 @@ export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
/**
* Error telemetry event.
* @remarks Maps to category = "error"
* @deprecated This type is being removed without a replacement.
* @see {@link https://github.com/microsoft/FluidFramework/issues/26910 | Issue #26910} for details.
* @legacy @beta
* @internal
*/
export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
/**
Expand All @@ -101,9 +101,7 @@ export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
/**
* Performance telemetry event.
* @remarks Maps to category = "performance"
* @deprecated This type is being removed without a replacement.
* @see {@link https://github.com/microsoft/FluidFramework/issues/26910 | Issue #26910} for details.
* @legacy @beta
* @internal
*/
export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
/**
Expand All @@ -113,15 +111,9 @@ export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt
}

/**
* This is the externally facing type for a FluidFramework internal telemetry logger wrapper.
*
* @remarks
* The methods if this interface are not to be used directly by consumers and are all
* deprecated to removed without replacement. This type is not deprecated and will
* transition to an erased type to handle cases where "internal" `ITelemetryLoggerExt`
* previously leaked out.
* Handle for an extended {@link @fluidframework/core-interfaces#ITelemetryBaseLogger} used internally within the Fluid Framework.
*
* @see {@link https://github.com/microsoft/FluidFramework/issues/26910 | Issue #26910} for deprecation and breaking change details.
* @see {@link https://github.com/microsoft/FluidFramework/issues/26910 | Issue #26910} for past method deprecation and breaking change details.
*
* @privateRemarks
* External APIs taking in an `ITelemetryLoggerExt` ideally should be updated to
Expand All @@ -131,46 +123,9 @@ export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt
* @legacy
* @beta
*/
export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
/**
* Send an information telemetry event.
* @param event - Event to send.
* @param error - Optional error object to log.
* @param logLevel - Optional level of the log. If undefined, the logLevel should be treated as {@link @fluidframework/core-interfaces#LogLevel.essential}.
* If the event's category is `error`, the logLevel will be upgraded to {@link @fluidframework/core-interfaces#LogLevel.essential}.
* @deprecated This method is being removed without a replacement.
* @see {@link https://github.com/microsoft/FluidFramework/issues/26910 | Issue #26910} for details.
*/
sendTelemetryEvent(
event: ITelemetryGenericEventExt,
error?: unknown,
logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
): void;

/**
* Send an error telemetry event.
* @param event - Event to send.
* @param error - Optional error object to log.
* @deprecated This method is being removed without a replacement.
* @see {@link https://github.com/microsoft/FluidFramework/issues/26910 | Issue #26910} for details.
*/
sendErrorEvent(event: ITelemetryErrorEventExt, error?: unknown): void;

/**
* Send a performance telemetry event.
* @param event - Event to send
* @param error - Optional error object to log.
* @param logLevel - Optional level of the log. If undefined, the logLevel should be treated as {@link @fluidframework/core-interfaces#LogLevel.essential}.
* If the event's category is `error`, the logLevel will be upgraded to {@link @fluidframework/core-interfaces#LogLevel.essential}.
* @deprecated This method is being removed without a replacement.
* @see {@link https://github.com/microsoft/FluidFramework/issues/26910 | Issue #26910} for details.
*/
sendPerformanceEvent(
event: ITelemetryPerformanceEventExt,
error?: unknown,
logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
): void;
}
export interface ITelemetryLoggerExt
extends ErasedType<"TelemetryLoggerExt">,
ITelemetryBaseLogger {}

/**
* An extended {@link @fluidframework/core-interfaces#ITelemetryBaseLogger} which allows for more lenient event types.
Expand Down
Loading
Loading