Add logLevel property to telemetry events by MarioJGMsoft · Pull Request #26548 · microsoft/FluidFramework

MarioJGMsoft · 2026-02-25T23:21:29Z

Description

Added a new optional logLevel property to telemetry events to indicate their importance for diagnostics. This enables consumers to make sampling or filtering decisions based on the event's importance level.

The property can have three values:

verbose — Chatty logs useful for debugging but likely not needed in production.
info — Session information that could be omitted in some sessions if needed.
essential— Critical diagnostic information that should always be transmitted.

Events without a logLevel value should be treated as essential.

Reviewer Guidance

The goal is to eventually replace the existing LogLevel type with this new property. I'd appreciate feedback on the naming of the property and its values and whether the default behavior (treating missing logLevel as essential) makes sense.

The review process is outlined on this wiki page.

jason-ha

We're replacing LogLevel with string? Any string is okay?
How are we documenting to our customers what they should be checking?

jason-ha · 2026-02-26T00:45:43Z

packages/runtime/container-runtime/src/summary/orderedClientElection.ts

 		sequenceNumber: number,
 		forceSend: boolean = false,
 		reason?: string,
+		logLevel?: string,


not required?
If not specified, I think we'll emit undefined. Does undefined just get dropped?

My idea was to have undefined be treated as the essential log level, this means that if there is no logLevel property the event shouldn't be dropped.

This is because there are a lot of events in our codebase and I think it's better to have it so that we have more information diagnosing rather than missing some that wasn't properly set to essential.

MarioJGMsoft · 2026-02-26T19:44:58Z

We're replacing LogLevel with string? Any string is okay? How are we documenting to our customers what they should be checking?

Originally I wanted to avoid the issue we had with the logLevel enum, so I decided to make it a simple string. But thinking more about it now, I could create an internal enum that can work as both documentation for what costumers should be checking and a way to always have a list of expected values.

I was thinking of adding a section in one of the .md files in the docs folder, but I wasn's sure where.

markfields · 2026-02-26T22:15:23Z

.changeset/tricky-zoos-see.md

+"@fluidframework/shared-object-base": minor
+"__section": feature
+---
+Add logLevel property to events


Suggested change

Add logLevel property to events

Add logLevel property to logging events

Applied change

markfields · 2026-02-26T22:21:28Z

.changeset/tricky-zoos-see.md

+There are currently three values that the property can have:
+1. 'verbose'
+Chatty logs useful for debugging but likely not to be sent over the wire in production.
+2. 'info'
+Information about the session. These logs could be ommitted in some sessions if needed.
+3. 'essential'
+Essential information about the operation of Fluid that should always be transmitted for diagnostic purposes.


Suggested change

There are currently three values that the property can have:

1. 'verbose'

Chatty logs useful for debugging but likely not to be sent over the wire in production.

2. 'info'

Information about the session. These logs could be ommitted in some sessions if needed.

3. 'essential'

Essential information about the operation of Fluid that should always be transmitted for diagnostic purposes.

There are currently three supported values:

1. 'verbose'

Chatty logs useful for local debugging. They need not be collected in production.

2. 'info'

Information about the session. These logs could be omitted in some sessions if needed (e.g. to reduce overall telemetry volume). If any are collected from a particular session, all should be.

3. 'essential'

Essential information about the operation of Fluid. It's recommended that they should always be collected even in production, for diagnostic purposes.

Thanks for the feedback, I applied the changes

markfields · 2026-02-26T22:25:03Z

packages/dds/shared-object-base/src/sharedObject.ts

 			this.mc !== undefined && this.logger !== undefined,
 			0x349 /* this.mc and/or this.logger has not been set */,
 		);
 		const opProcessingHelper = new SampledTelemetryHelper<void, ProcessTelemetryProperties>(


Let's make this class apply a default logLevel: "info" itself. (and don't bother setting below)

Applied change

markfields · 2026-02-26T22:33:01Z

.changeset/tricky-zoos-see.md

+
+Events now include an optional `logLevel` property that indicates their importance for diagnostics and enables consumers to make sampling or filtering decisions.
+
+There are currently three values that the property can have:


Let's add some kind of helpers for this.

I wish would could do this, but it involves touching legacy-beta stuff (because ITelemetryLoggerExt is overexposed at the moment):

Update ITelemetryGenericEventExt and related types to include logLevel?: "verbose" | "info" | "essential"

Then whenever you use our internal loggers, you'd have type safety on what you pass for logLevel.
And other helpers like SampledTelemetryHelper would benefit as well

But let's not for now. Instead we can just add this to telemetry-utils logger.ts:

export const LogLevel = { verbose: "verbose", info: "info", essential: "essential" }

And then use that instead of the string literals everywhere.

Josmithr · 2026-02-26T23:27:18Z

packages/runtime/container-runtime/src/summary/orderedClientElection.ts

 		sequenceNumber: number,
 		forceSend: boolean = false,
 		reason?: string,
+		logLevel?: string,


Nit: for APIs not exposed to end users, I generally recommend making all arguments required (and allow undefined), rather than making them optional. This will help prevent usages from accidentally forgetting to provide a parameter it really wants to provide.

(Feel free to disregard, especially since it would require updating existing parameters here).

After thinking about it for a bit, from what I could see the sendPerformanceEvent() funciton is used only in this file, and the events related to the client elected performance events might all be ommitable? (@kian-thompson @markfields can confirm?)
So if that's the case then the parameter won't be needed at all and they can all default to being info

MarioJGMsoft added 6 commits February 19, 2026 16:17

feat: added new sampleable Property

b3fd32c

Merge remote-tracking branch 'origin/main' into marioja/sampleProperty

4265ae4

feat: updated property to be logLevel

410c3a5

format: applied biome

4994a23

docs: added changeset

fe38892

docs: updated changeset title

ff6daf3

MarioJGMsoft changed the title ~~Marioja/sample property~~ Add logLevel property to telemetry events Feb 25, 2026

Merge branch 'main' into marioja/sampleProperty

27d2025

jason-ha reviewed Feb 26, 2026

View reviewed changes

markfields reviewed Feb 26, 2026

View reviewed changes

MarioJGMsoft added 2 commits February 26, 2026 23:20

feat: moved logLevel declaration to class instead of individual event

35c5f83

docs: applied changes based on comments

fae1c05

Josmithr reviewed Feb 26, 2026

View reviewed changes

MarioJGMsoft added 2 commits February 27, 2026 00:32

feat: updated to using LogLevelValue const

3e28363

format: applied biome

13bce9f

	Add logLevel property to events
	Add logLevel property to logging events


		Events now include an optional `logLevel` property that indicates their importance for diagnostics and enables consumers to make sampling or filtering decisions.

		There are currently three values that the property can have:

Conversation

MarioJGMsoft commented Feb 25, 2026

Description

Reviewer Guidance

Uh oh!

jason-ha left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MarioJGMsoft commented Feb 26, 2026 •

edited

Loading