diff --git a/.changeset/hungry-pianos-grab.md b/.changeset/hungry-pianos-grab.md new file mode 100644 index 000000000000..a5e8109efb3e --- /dev/null +++ b/.changeset/hungry-pianos-grab.md @@ -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. diff --git a/packages/framework/aqueduct/package.json b/packages/framework/aqueduct/package.json index bccfa0fb8fda..9bb8152b849c 100644 --- a/packages/framework/aqueduct/package.json +++ b/packages/framework/aqueduct/package.json @@ -154,7 +154,11 @@ "typescript": "~5.4.5" }, "typeValidation": { - "broken": {}, + "broken": { + "Interface_DataObjectFactoryProps": { + "backCompat": false + } + }, "entrypoint": "legacy" } } diff --git a/packages/framework/aqueduct/src/test/types/validateAqueductPrevious.generated.ts b/packages/framework/aqueduct/src/test/types/validateAqueductPrevious.generated.ts index 35464e29ddeb..42c55ce70065 100644 --- a/packages/framework/aqueduct/src/test/types/validateAqueductPrevious.generated.ts +++ b/packages/framework/aqueduct/src/test/types/validateAqueductPrevious.generated.ts @@ -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>> /* diff --git a/packages/loader/container-loader/package.json b/packages/loader/container-loader/package.json index d1a754718776..df2db0d873b1 100644 --- a/packages/loader/container-loader/package.json +++ b/packages/loader/container-loader/package.json @@ -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" } } diff --git a/packages/loader/container-loader/src/test/types/validateContainerLoaderPrevious.generated.ts b/packages/loader/container-loader/src/test/types/validateContainerLoaderPrevious.generated.ts index 722be3476210..2f6f10604120 100644 --- a/packages/loader/container-loader/src/test/types/validateContainerLoaderPrevious.generated.ts +++ b/packages/loader/container-loader/src/test/types/validateContainerLoaderPrevious.generated.ts @@ -33,6 +33,7 @@ declare type old_as_current_for_Class_Loader = requireAssignableTo, TypeOnly> /* @@ -42,6 +43,7 @@ declare type current_as_old_for_Class_Loader = requireAssignableTo, TypeOnly> /* @@ -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> /* diff --git a/packages/runtime/datastore/package.json b/packages/runtime/datastore/package.json index 8b071861f8e5..6ff79e8c05ab 100644 --- a/packages/runtime/datastore/package.json +++ b/packages/runtime/datastore/package.json @@ -157,7 +157,14 @@ "typescript": "~5.4.5" }, "typeValidation": { - "broken": {}, + "broken": { + "Class_FluidDataStoreRuntime": { + "backCompat": false + }, + "ClassStatics_FluidDataStoreRuntime": { + "backCompat": false + } + }, "entrypoint": "legacy" } } diff --git a/packages/runtime/datastore/src/test/types/validateDatastorePrevious.generated.ts b/packages/runtime/datastore/src/test/types/validateDatastorePrevious.generated.ts index b0e5b7c27b93..b5c47c712c4c 100644 --- a/packages/runtime/datastore/src/test/types/validateDatastorePrevious.generated.ts +++ b/packages/runtime/datastore/src/test/types/validateDatastorePrevious.generated.ts @@ -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> /* @@ -60,6 +61,7 @@ declare type current_as_old_for_Class_FluidObjectHandle = requireAssignableTo, TypeOnly> /* diff --git a/packages/runtime/test-runtime-utils/package.json b/packages/runtime/test-runtime-utils/package.json index 3a12a2ff848f..db991601bc21 100644 --- a/packages/runtime/test-runtime-utils/package.json +++ b/packages/runtime/test-runtime-utils/package.json @@ -153,7 +153,14 @@ "typescript": "~5.4.5" }, "typeValidation": { - "broken": {}, + "broken": { + "Class_MockFluidDataStoreContext": { + "backCompat": false + }, + "ClassStatics_MockFluidDataStoreContext": { + "backCompat": false + } + }, "entrypoint": "legacy" } } diff --git a/packages/runtime/test-runtime-utils/src/test/types/validateTestRuntimeUtilsPrevious.generated.ts b/packages/runtime/test-runtime-utils/src/test/types/validateTestRuntimeUtilsPrevious.generated.ts index 4232bacdf68d..bdf1b2373331 100644 --- a/packages/runtime/test-runtime-utils/src/test/types/validateTestRuntimeUtilsPrevious.generated.ts +++ b/packages/runtime/test-runtime-utils/src/test/types/validateTestRuntimeUtilsPrevious.generated.ts @@ -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> /* @@ -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> /* diff --git a/packages/utils/telemetry-utils/DEV.md b/packages/utils/telemetry-utils/DEV.md index d15fedfc953f..8e07573fc51c 100644 --- a/packages/utils/telemetry-utils/DEV.md +++ b/packages/utils/telemetry-utils/DEV.md @@ -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. +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. diff --git a/packages/utils/telemetry-utils/api-report/telemetry-utils.legacy.beta.api.md b/packages/utils/telemetry-utils/api-report/telemetry-utils.legacy.beta.api.md index 1af6c1b4480a..3fdb2451550b 100644 --- a/packages/utils/telemetry-utils/api-report/telemetry-utils.legacy.beta.api.md +++ b/packages/utils/telemetry-utils/api-report/telemetry-utils.legacy.beta.api.md @@ -18,25 +18,8 @@ export class EventEmitterWithErrorHandling 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) @@ -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>; -// @beta @deprecated @legacy -export type TelemetryEventCategory = "generic" | "error" | "performance"; - // @beta @legacy export type TelemetryEventPropertyTypeExt = string | number | boolean | undefined | (string | number | boolean)[] | Record; diff --git a/packages/utils/telemetry-utils/package.json b/packages/utils/telemetry-utils/package.json index 819d143fdbf3..9c659f6636fb 100644 --- a/packages/utils/telemetry-utils/package.json +++ b/packages/utils/telemetry-utils/package.json @@ -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" } } diff --git a/packages/utils/telemetry-utils/src/api.ts b/packages/utils/telemetry-utils/src/api.ts index dbb020c233fa..b3faa2d8c07a 100644 --- a/packages/utils/telemetry-utils/src/api.ts +++ b/packages/utils/telemetry-utils/src/api.ts @@ -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". + // Add it to "/legacy" export set here. ITelemetryLoggerExt, - ITelemetryPerformanceEventExt, - TelemetryEventCategory, } from "./telemetryTypes.js"; // ---------------------------------------------------------------------------- diff --git a/packages/utils/telemetry-utils/src/telemetryTypes.ts b/packages/utils/telemetry-utils/src/telemetryTypes.ts index b444a4a64e44..24031886579c 100644 --- a/packages/utils/telemetry-utils/src/telemetryTypes.ts +++ b/packages/utils/telemetry-utils/src/telemetryTypes.ts @@ -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. @@ -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"; @@ -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 { /** @@ -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 { /** @@ -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 { /** @@ -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 @@ -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. diff --git a/packages/utils/telemetry-utils/src/test/types/validateTelemetryUtilsPrevious.generated.ts b/packages/utils/telemetry-utils/src/test/types/validateTelemetryUtilsPrevious.generated.ts index 63246fb61fda..53b6b31e3ee3 100644 --- a/packages/utils/telemetry-utils/src/test/types/validateTelemetryUtilsPrevious.generated.ts +++ b/packages/utils/telemetry-utils/src/test/types/validateTelemetryUtilsPrevious.generated.ts @@ -60,6 +60,7 @@ declare type current_as_old_for_Function_createChildLogger = requireAssignableTo * typeValidation.broken: * "Interface_ITelemetryErrorEventExt": {"forwardCompat": false} */ +// @ts-expect-error compatibility expected to be broken declare type old_as_current_for_Interface_ITelemetryErrorEventExt = requireAssignableTo, TypeOnly> /* @@ -69,6 +70,7 @@ declare type old_as_current_for_Interface_ITelemetryErrorEventExt = requireAssig * typeValidation.broken: * "Interface_ITelemetryErrorEventExt": {"backCompat": false} */ +// @ts-expect-error compatibility expected to be broken declare type current_as_old_for_Interface_ITelemetryErrorEventExt = requireAssignableTo, TypeOnly> /* @@ -78,6 +80,7 @@ declare type current_as_old_for_Interface_ITelemetryErrorEventExt = requireAssig * typeValidation.broken: * "Interface_ITelemetryGenericEventExt": {"forwardCompat": false} */ +// @ts-expect-error compatibility expected to be broken declare type old_as_current_for_Interface_ITelemetryGenericEventExt = requireAssignableTo, TypeOnly> /* @@ -87,6 +90,7 @@ declare type old_as_current_for_Interface_ITelemetryGenericEventExt = requireAss * typeValidation.broken: * "Interface_ITelemetryGenericEventExt": {"backCompat": false} */ +// @ts-expect-error compatibility expected to be broken declare type current_as_old_for_Interface_ITelemetryGenericEventExt = requireAssignableTo, TypeOnly> /* @@ -96,6 +100,7 @@ declare type current_as_old_for_Interface_ITelemetryGenericEventExt = requireAss * typeValidation.broken: * "Interface_ITelemetryLoggerExt": {"backCompat": false} */ +// @ts-expect-error compatibility expected to be broken declare type current_as_old_for_Interface_ITelemetryLoggerExt = requireAssignableTo, TypeOnly> /* @@ -123,6 +128,7 @@ declare type current_as_old_for_Interface_ITelemetryLoggerPropertyBags = require * typeValidation.broken: * "Interface_ITelemetryPerformanceEventExt": {"forwardCompat": false} */ +// @ts-expect-error compatibility expected to be broken declare type old_as_current_for_Interface_ITelemetryPerformanceEventExt = requireAssignableTo, TypeOnly> /* @@ -132,6 +138,7 @@ declare type old_as_current_for_Interface_ITelemetryPerformanceEventExt = requir * typeValidation.broken: * "Interface_ITelemetryPerformanceEventExt": {"backCompat": false} */ +// @ts-expect-error compatibility expected to be broken declare type current_as_old_for_Interface_ITelemetryPerformanceEventExt = requireAssignableTo, TypeOnly> /* @@ -177,6 +184,7 @@ declare type current_as_old_for_TypeAlias_ITelemetryPropertiesExt = requireAssig * typeValidation.broken: * "TypeAlias_TelemetryEventCategory": {"forwardCompat": false} */ +// @ts-expect-error compatibility expected to be broken declare type old_as_current_for_TypeAlias_TelemetryEventCategory = requireAssignableTo, TypeOnly> /* @@ -186,6 +194,7 @@ declare type old_as_current_for_TypeAlias_TelemetryEventCategory = requireAssign * typeValidation.broken: * "TypeAlias_TelemetryEventCategory": {"backCompat": false} */ +// @ts-expect-error compatibility expected to be broken declare type current_as_old_for_TypeAlias_TelemetryEventCategory = requireAssignableTo, TypeOnly> /* diff --git a/packages/utils/telemetry-utils/src/test/utils.spec.ts b/packages/utils/telemetry-utils/src/test/utils.spec.ts index af1d3e3f43f9..6b8e54d7ba5c 100644 --- a/packages/utils/telemetry-utils/src/test/utils.spec.ts +++ b/packages/utils/telemetry-utils/src/test/utils.spec.ts @@ -11,10 +11,6 @@ import type { ITelemetryBaseEvent, } from "@fluidframework/core-interfaces"; import { LogLevel } from "@fluidframework/core-interfaces"; -import type { InternalCoreInterfacesUtilityTypes } from "@fluidframework/core-interfaces/internal"; - -import type { ITelemetryLoggerExt as ITelemetryLoggerExtInternal } from "@fluidframework/telemetry-utils/internal"; -import type { ITelemetryLoggerExt as ITelemetryLoggerExtExternal } from "@fluidframework/telemetry-utils/legacy"; import { mixinMonitoringContext } from "../config.js"; import { TelemetryDataTag, tagCodeArtifacts, tagData } from "../logger.js"; @@ -24,28 +20,6 @@ import type { } from "../telemetryTypesUndeprecated.js"; import { type IEventSampler, createSampledLogger } from "../utils.js"; -/** - * Use to compile-time assert types of two variables are identical. - */ -function assertIdenticalTypes( - _actual: T & InternalCoreInterfacesUtilityTypes.IfSameType, - _expected: U & InternalCoreInterfacesUtilityTypes.IfSameType, -): InternalCoreInterfacesUtilityTypes.IfSameType { - return undefined as InternalCoreInterfacesUtilityTypes.IfSameType; -} - -/** - * This is exported but never called - tests that internal and external ITelemetryLoggerExt types are identical. - * At this time the only difference allowed is for the external version to have `@deprecated` tags on it methods. - * To be removed when external type is erased and the types are permitted to diverge. - */ -export function checkIdenticalLoggers( - internal: ITelemetryLoggerExtInternal, - external: ITelemetryLoggerExtExternal, -): void { - assertIdenticalTypes(internal, external); -} - describe("tagData", () => { it("tagData with data", () => { const taggedData = tagData(TelemetryDataTag.CodeArtifact, { foo: "bar" });