feat(telemetry-utils): deprecate LogLevel.default/error and tag unspecified events as essential by MarioJGMsoft · Pull Request #27207 · microsoft/FluidFramework

MarioJGMsoft · 2026-04-29T23:07:12Z

Description

Tracks issue #26969 (planned removal in v3.0).

This PR has two parts:

1. Deprecate `LogLevel.default` and `LogLevel.error`

Adds @deprecated tags on LogLevel.default and LogLevel.error and migrates
all in-repo callsites:

LogLevel.default → LogLevel.info (numerically identical, value 20)
LogLevel.error → LogLevel.essential (numerically identical, value 30)

Affected files include telemetry-utils (logger.ts, mockLogger.ts,
telemetryTypes.ts, and the related tests) and the corresponding API reports.

2. Treat events with no explicit `logLevel` as `essential` in `ChildLogger`

Two related changes in packages/utils/telemetry-utils/src/logger.ts:

ChildLogger.shouldFilterOutEvent now falls back to LogLevel.essential (30)
when an event arrives without a logLevel (previously LogLevel.default = 20).
ChildLogger.send now forwards LogLevel.essential to the base logger when
no logLevel was supplied, instead of forwarding undefined.

Additionally, the parameter defaults on TelemetryLogger.sendTelemetryEvent and
sendPerformanceEvent were dropped (they were = LogLevel.default). Callers
that don't pass a logLevel now propagate undefined through the chain, where
ChildLogger applies the new essential fallback above.

3. `createSampledLogger` and `MultiSinkLogger.send` now forward `error` and `logLevel`

Two pre-existing bugs surfaced while wiring up the essential fallback above:

createSampledLogger (packages/utils/telemetry-utils/src/utils.ts)
silently dropped error and logLevel arguments before delegating to the
wrapped logger — the wrapper's method signatures didn't even accept those
arguments. The wrapper now accepts and forwards them:
- send accepts logLevel?
- sendTelemetryEvent accepts error? and logLevel? (verbose | info)
- sendErrorEvent accepts error?
- sendPerformanceEvent accepts error? and logLevel? (verbose | info)
MultiSinkLogger.send (packages/utils/telemetry-utils/src/logger.ts)
had the same bug — logLevel was dropped before fanning out to sinks. It now
accepts logLevel? and forwards it to every registered sink (defaulting to
LogLevel.essential when omitted, consistent with the part 2 behavior).

New test coverage:

utils.spec.ts — describe("logLevel forwarding") verifies the sampled
logger forwards logLevel through send, sendTelemetryEvent, and
sendPerformanceEvent, and propagates undefined when the caller omits it.
multiSinkLogger.spec.ts — describe("logLevel propagation") verifies the
default LogLevel.essential fallback, explicit-level forwarding for both
sendTelemetryEvent and sendPerformanceEvent, and includes a regression
test for the MultiSinkLogger.send drop bug.
childLogger.spec.ts — describe("logLevel forwarding") verifies
ChildLogger forwards both the essential default and explicit levels to
the underlying sink.

Misc

Fixed an incorrect type import ordering in container.spec.ts.

Behavior change for downstream consumers

Although no public API is removed in this PR, downstream consumers that filter
telemetry by numeric level should be aware:

Internal Fluid events that were previously emitted to the base logger with
logLevel = undefined (effectively treated as 20) will now arrive tagged as
30 (essential). If a host application starts dropping logLevel = 20 events
as "non-essential", it must ensure all running Fluid versions include this
change — older Fluid versions still send those same critical events at level
20, and dropping them would lose telemetry.

Breaking Changes

No public API surface is removed. See #26969 for the planned v3.0 removal of
LogLevel.default and LogLevel.error. See the "Behavior change for downstream
consumers" section above for a runtime behavior note.

Reviewer Guidance

The review process is outlined on this wiki page.

Specific asks:

Confirm the LogLevel.essential fallback in ChildLogger.shouldFilterOutEvent
and ChildLogger.send is the intended semantic (vs. leaving undefined to
flow to the base logger).
Confirm dropping the = LogLevel.default parameter defaults on
sendTelemetryEvent / sendPerformanceEvent is acceptable for consumers who
may have relied on the implicit default.
Confirm the createSampledLogger and MultiSinkLogger.send argument
forwarding fix is acceptable as part of this PR (it changes observable
behavior for hosts wrapping with these helpers).

…hose values.

github-actions · 2026-04-29T23:08:13Z

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (102 lines, 13 files), I've queued these reviewers:

Correctness — logic errors, race conditions, lifecycle issues
Security — vulnerabilities, secret exposure, injection
API Compatibility — breaking changes, release tags, type design
Performance — algorithmic regressions, memory leaks
Testing — coverage gaps, hollow tests

Toggle the reviewer checkboxes above to adjust, then tick the box below to start:

Start review

Copilot

Pull request overview

This PR updates Fluid’s telemetry log-level semantics by deprecating legacy LogLevel members and changing how ChildLogger treats events with no explicit logLevel, to better distinguish “essential” telemetry.

Changes:

Deprecates LogLevel.default and LogLevel.error, and migrates in-repo usages to LogLevel.info / LogLevel.essential.
Changes ChildLogger to treat events with no explicit logLevel as essential, including forwarding essential to the base logger.
Updates related types/docs, tests, API reports, and adds changesets documenting the behavior change.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
packages/utils/telemetry-utils/src/test/multiSinkLogger.spec.ts	Updates tests to use `info`/`essential` instead of deprecated `default`/`error`.
packages/utils/telemetry-utils/src/test/childLogger.spec.ts	Updates log-level constants in tests; should be extended to cover the new “unspecified logLevel ⇒ essential” behavior.
packages/utils/telemetry-utils/src/telemetryTypes.ts	Updates `logLevel` unions to use `info`; updates TSDoc (currently inconsistent with new runtime defaults).
packages/utils/telemetry-utils/src/mockLogger.ts	Updates MockLogger default min level / filtering fallback from `default` to `info`.
packages/utils/telemetry-utils/src/logger.ts	Removes parameter defaults, changes `ChildLogger` fallback/forwarding to `essential`, updates MultiSink defaults, and adds PerformanceEvent docs (currently inaccurate).
packages/utils/telemetry-utils/api-report/telemetry-utils.legacy.beta.api.md	API report update reflecting new `logLevel` unions.
packages/loader/container-loader/src/test/container.spec.ts	Import ordering/type-only import adjustment.
packages/common/core-interfaces/src/logger.ts	Adds `@deprecated` tags for `LogLevelConst.default/error` and updates base logger docs to default to `info`.
packages/common/core-interfaces/api-report/core-interfaces.public.api.md	API report reflects deprecated members.
packages/common/core-interfaces/api-report/core-interfaces.legacy.public.api.md	API report reflects deprecated members.
packages/common/core-interfaces/api-report/core-interfaces.legacy.beta.api.md	API report reflects deprecated members.
packages/common/core-interfaces/api-report/core-interfaces.legacy.alpha.api.md	API report reflects deprecated members.
packages/common/core-interfaces/api-report/core-interfaces.beta.api.md	API report reflects deprecated members.
.changeset/soft-doors-trade.md	Changeset documenting the `ChildLogger` unspecified-logLevel behavior change and downstream impact.
.changeset/salty-colts-appear.md	Changeset documenting the `LogLevel.default/error` deprecations and migration guidance.

markfields · 2026-04-30T20:17:57Z

 	TypedEventEmitter,
 	type IProvideLayerCompatDetails,
 } from "@fluid-internal/client-utils";
-import { AttachState, type IAudience } from "@fluidframework/container-definitions";


nit: can revert this file?

It didn't feel big enough to deserve it's own PR, so I decided to add it here, but I can definitely split it off for it's own thing.

markfields · 2026-04-30T21:03:12Z

 	 * Log a telemetry event, if it meets the appropriate log-level threshold (see {@link ITelemetryBaseLogger.minLogLevel}).
 	 * @param event - The event to log.
-	 * @param logLevel - The log level of the event. Default: {@link LogLevelConst.default | LogLevel.default}.
+	 * @param logLevel - The log level of the event. Default: {@link LogLevelConst.info | LogLevel.info}.


Isn't the default supposed to be essential? Maybe it's clearer if we say it like "suggested interpretation of undefined: LogLevel.essential"? Since this is an interface so claiming a "default value" is kind of in vain, it could be implemented any way.

Applied change

jason-ha · 2026-05-06T21:04:46Z

-		logLevel: typeof LogLevel.verbose | typeof LogLevel.default = LogLevel.default,
+		logLevel:
+			| typeof LogLevel.verbose
+			| typeof LogLevel.info
+			| typeof LogLevel.essential = LogLevel.essential,


These cannot be changes to be different from the definition in TelemetryLoggerExt and ITelemetryLoggerExt.
TypeScript's silly function variance allowance strikes again. :(

Applied change, should work properly now

Removes 11 zero-byte files added by mistake in 2c13181. These are bind-mounted from the dev container host (shell rc files, IDE config, MCP config) and don't belong in the repo.

github-actions · 2026-05-06T22:48:51Z

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  288641 links
    1922 destination URLs
    2172 URLs ignored
       0 warnings
       0 errors

github-actions · 2026-05-06T22:48:51Z

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  288641 links
    1922 destination URLs
    2172 URLs ignored
       0 warnings
       0 errors

github-actions · 2026-05-06T22:48:56Z

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  288641 links
    1922 destination URLs
    2172 URLs ignored
       0 warnings
       0 errors

MarioJGMsoft added 7 commits April 27, 2026 15:58

feat: deprecate LogLevel.default and .error and remove all calls to t…

09cc182

…hose values.

feat: send LogLevel as undefined and default to essential on send logic

3525674

Merge branch 'main' into marioja/deprecateLogLevel

f3c37bf

Merge branch 'microsoft:main' into marioja/deprecateLogLevel

07925f4

refactor: properly ordered imports and removed LogLevel.default

67614c8

docs: fixed comments

a568d12

docs: updated docs

9a81682

MarioJGMsoft changed the title ~~feat: deprecate LogLevel.default and LogLevel.error~~ feat(telemetry-utils): deprecate LogLevel.default/error and tag unspecified events as essential Apr 29, 2026

MarioJGMsoft added 3 commits April 29, 2026 23:24

docs: added changesets

da948a1

docs: added removal timeline

c0d9396

docs: updated deprecation message

f3a92b6

MarioJGMsoft marked this pull request as ready for review April 30, 2026 16:22

MarioJGMsoft requested a review from a team as a code owner April 30, 2026 16:22

Copilot AI review requested due to automatic review settings April 30, 2026 16:22

MarioJGMsoft requested a review from a team as a code owner April 30, 2026 16:22

Copilot started reviewing on behalf of MarioJGMsoft April 30, 2026 16:23 View session

Copilot AI reviewed Apr 30, 2026

View reviewed changes

markfields reviewed Apr 30, 2026

View reviewed changes

MarioJGMsoft linked an issue May 4, 2026 that may be closed by this pull request

Remove deprecated LogLevel.default and LogLevel.error #26969

Open

MarioJGMsoft added 6 commits May 4, 2026 22:04

docs: addressed docs comments

0ba1037

Merge branch 'microsoft:main' into marioja/deprecateLogLevel

eab130c

docs: updated chengeset title

5f1205d

feat: applied changes to docs and code based on comments

ba39358

feat: made logLevel required in various levels and added tests

bad5774

fix: removed type import from normal import

71c1f07

jason-ha reviewed May 6, 2026

View reviewed changes

MarioJGMsoft added 2 commits May 6, 2026 21:53

fix: applied changes based on review

2c13181

docs: updated docs

3b3f5fe

MarioJGMsoft added 5 commits May 6, 2026 22:02

docs: removed changeset

fbd560a

docs: updated performance docs

5d5fcb1

Merge branch 'main' into marioja/deprecateLogLevel

beeac4c

chore: untrack dev-container bind-mounted files accidentally added

bee89e1

Removes 11 zero-byte files added by mistake in 2c13181. These are bind-mounted from the dev container host (shell rc files, IDE config, MCP config) and don't belong in the repo.

docs: updated docs message

1131b62

Conversation

MarioJGMsoft commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

1. Deprecate LogLevel.default and LogLevel.error

2. Treat events with no explicit logLevel as essential in ChildLogger

3. createSampledLogger and MultiSinkLogger.send now forward error and logLevel

New test coverage:

Misc

Behavior change for downstream consumers

Breaking Changes

Reviewer Guidance

Uh oh!

github-actions Bot commented Apr 29, 2026 • edited by MarioJGMsoft Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

markfields Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

MarioJGMsoft May 5, 2026

Choose a reason for hiding this comment

Uh oh!

markfields Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

MarioJGMsoft May 6, 2026

Choose a reason for hiding this comment

Uh oh!

jason-ha May 6, 2026

Choose a reason for hiding this comment

Uh oh!

MarioJGMsoft May 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 6, 2026

linkcheck output

Uh oh!

github-actions Bot commented May 6, 2026

linkcheck output

Uh oh!

github-actions Bot commented May 6, 2026

linkcheck output

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MarioJGMsoft commented Apr 29, 2026 •

edited

Loading

1. Deprecate `LogLevel.default` and `LogLevel.error`

2. Treat events with no explicit `logLevel` as `essential` in `ChildLogger`

3. `createSampledLogger` and `MultiSinkLogger.send` now forward `error` and `logLevel`

github-actions Bot commented Apr 29, 2026 •

edited by MarioJGMsoft

Loading