Window Framework for UI Toolkit v2.0.x
GWG.WindowFramework.Telemetry.WindowFrameTelemetry Class Reference

Static dispatcher for the WindowFramework Debug Telemetry System. Emits structured, machine-readable (AI/LLM-parseable) JSON diagnostic logs without decorative formatting. More...

Data Structures

class  InteractionObserver
struct  OperationScope
 Pairs operation begin and exit even when the caller returns early or throws. More...

Static Public Member Functions

static void LogContextMenu (string eventName, string menuTitle, Vector2 mousePos, int itemCount, string detail=null)
 Logs a context menu lifecycle or interaction event.
static void LogDocking (string eventName, VisualElement window, string dockState, Vector2 mousePos, string detail=null)
 Logs a window docking or tab nesting operation.
static void LogGeometry (string eventName, VisualElement window, string direction, Vector2 mousePos, Vector2 oldSize, Vector2 newSize, Vector2 oldPos, Vector2 newPos)
 Logs a window geometry transformation event (e.g. resize drag delta, position movement, clamping).
static void LogOperation (string eventName, TelemetryChannel channel, string target, string outcome="Completed", double startedAt=-1, int count=-1)
 Emits a feature operation or state transition without exposing user content.
static void LogPersistence (string eventName, string themeId, string outcome, int records, bool windowRecord=false, VisualElement scope=null)
 Records save/load/application outcomes with a stable opaque selection fingerprint.
static void LogPlayerTheme (string stage, string field=null, VisualElement scope=null, bool success=true, int count=-1)
 Emits portable-theme stage evidence through the existing diagnostic dispatcher.
static void LogPointer (string eventName, VisualElement targetElement, Vector2 mousePosition, string detail=null)
 Logs a pointer boundary crossing or hit-test event with element geometry and pointer coordinates.
static void LogSnapping (string eventName, VisualElement window, Vector2 rawPos, Vector2 snappedPos, string detail=null)
 Logs a magnetic snapping calculation event.
static void LogStartup (string eventName, string target, double startedAt=-1, string detail=null)
 Records startup milestones and bounded geometry-wait samples with a shared monotonic clock.
static void LogStyleSheet (string eventName, VisualElement scope, StyleSheet sheet, string outcome, int count=-1)
 Records an actual managed stylesheet operation, not a layout-completion claim.
static void LogThemeNameValidation (TextField field, Label status, bool createEnabled)
 Observes validation classes, token resolution and input borders without logging entered names.
static void LogThemeSelectorRow (VisualElement row, VisualElement star)
 Records independent row states and measured styling, not visual acceptance.
static void LogTooltip (string eventName, string tooltipText, Vector2 mousePos, Vector2 resolvedPos, string detail=null)
 Logs a tooltip lifecycle or placement event.
static OperationScope Measure (string operation, TelemetryChannel channel, string target)
 Starts a bounded feature operation. A disabled scope is inert and allocates nothing.
static IDisposable ObserveInteractions (VisualElement root)
 Observes semantic UI events in an explicit subtree. Dispose on owner detach/disable.

Properties

static TelemetryChannel ActiveChannels = TelemetryChannel.All [get, set]
 Active channel filter mask. Defaults to all channels.
static bool Enabled = false [get, set]
 Master runtime toggle for telemetry emission.

Static Private Member Functions

static void AppendField (StringBuilder sb, string key, string value)
static void AppendTraceIdentity (StringBuilder sb, VisualElement scope=null)
static string EscapeJson (string s)

Static Private Attributes

static string _runId
static bool _runIsPlaying
static readonly System.Collections.Generic.HashSet< VisualElement > InteractionRoots = new System.Collections.Generic.HashSet<VisualElement>()

Detailed Description

Static dispatcher for the WindowFramework Debug Telemetry System. Emits structured, machine-readable (AI/LLM-parseable) JSON diagnostic logs without decorative formatting.

Individual emission APIs use their declared Conditional/preprocessor guards. Do not assume every call in this class is removed when WFW_TELEMETRY_ENABLED is absent: editor operation logs remain available, ObserveInteractions can install editor callbacks, and Measure returns an inert struct in an uninstrumented player. Argument evaluation at nonconditional callsites still follows ordinary C# rules. Enabled and ActiveChannels additionally gate emitted output. Diagnostic output goes through Unity Debug.Log, not a separate guaranteed telemetry file.

Member Function Documentation

◆ AppendField()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.AppendField ( StringBuilder sb,
string key,
string value )
inlinestaticprivate
Here is the call graph for this function:
Here is the caller graph for this function:

◆ AppendTraceIdentity()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.AppendTraceIdentity ( StringBuilder sb,
VisualElement scope = null )
inlinestaticprivate
Here is the call graph for this function:
Here is the caller graph for this function:

◆ EscapeJson()

string GWG.WindowFramework.Telemetry.WindowFrameTelemetry.EscapeJson ( string s)
inlinestaticprivate
Here is the caller graph for this function:

◆ LogContextMenu()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogContextMenu ( string eventName,
string menuTitle,
Vector2 mousePos,
int itemCount,
string detail = null )
inlinestatic

Logs a context menu lifecycle or interaction event.

Parameters
eventNameEvent identifier (e.g. "CONTEXT_SHOW", "CONTEXT_SELECT", "CONTEXT_DISMISS").
menuTitleTitle or identifier of the context menu.
mousePosPointer coordinates during interaction.
itemCountNumber of menu items displayed.
detailOptional dismiss reason or selected item title.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogDocking()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogDocking ( string eventName,
VisualElement window,
string dockState,
Vector2 mousePos,
string detail = null )
inlinestatic

Logs a window docking or tab nesting operation.

Parameters
eventNameEvent identifier (e.g. "DOCK_SPLIT", "UNDOCK_TEAROFF", "TAB_NEST", "TAB_UNDOCK").
windowPrimary WindowFrame involved in the dock operation.
dockStateTarget or current dock state description.
mousePosPointer coordinate during operation.
detailOptional detail or secondary window name.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogGeometry()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogGeometry ( string eventName,
VisualElement window,
string direction,
Vector2 mousePos,
Vector2 oldSize,
Vector2 newSize,
Vector2 oldPos,
Vector2 newPos )
inlinestatic

Logs a window geometry transformation event (e.g. resize drag delta, position movement, clamping).

Parameters
eventNameEvent identifier (e.g. "RESIZE_DRAG", "RESIZE_START", "RESIZE_END").
windowTarget WindowFrame element.
directionDirection of the resize operation.
mousePosCurrent mouse coordinates.
oldSizePrevious size before delta calculation.
newSizeNew resolved size.
oldPosPrevious position before delta calculation.
newPosNew resolved position.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogOperation()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogOperation ( string eventName,
TelemetryChannel channel,
string target,
string outcome = "Completed",
double startedAt = -1,
int count = -1 )
inlinestatic

Emits a feature operation or state transition without exposing user content.

Use stable event identifiers and type/element identities. Supply outcomes for rejection/failure and a start timestamp for completed work. Do not send paths, input values, theme payloads or arbitrary exception text. High-frequency callers must sample or log transitions.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogPersistence()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogPersistence ( string eventName,
string themeId,
string outcome,
int records,
bool windowRecord = false,
VisualElement scope = null )
inlinestatic

Records save/load/application outcomes with a stable opaque selection fingerprint.

The fingerprint is diagnostic correlation, not a selection ID or security mechanism. No file path, theme name, raw identity, input value or persistence payload is emitted.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogPlayerTheme()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogPlayerTheme ( string stage,
string field = null,
VisualElement scope = null,
bool success = true,
int count = -1 )
inlinestatic

Emits portable-theme stage evidence through the existing diagnostic dispatcher.

Parameters
stageFixed framework stage code; never player JSON or path text.
fieldFramework catalog field or null; never user-provided values.
scopeScope for attachment/type evidence; its name is not logged.
successStage result, not an end-to-end acceptance claim.
countStage-specific count, or -1 when not applicable.

Permanent opt-in instrumentation, not a temporary runner. Uses WindowGeometry channel to avoid changing existing enum values/customer filters. Player call sites compile out without WFW_TELEMETRY_ENABLED; Editor calls retain the existing Enabled/filter gates. No payload, display name, stable ID or absolute path is emitted.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogPointer()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogPointer ( string eventName,
VisualElement targetElement,
Vector2 mousePosition,
string detail = null )
inlinestatic

Logs a pointer boundary crossing or hit-test event with element geometry and pointer coordinates.

Parameters
eventNameEvent identifier (e.g. "POINTER_ENTER", "POINTER_LEAVE", "CURSOR_SWITCH").
targetElementThe visual element receiving the pointer interaction.
mousePositionCurrent mouse position in panel coordinates.
detailOptional contextual detail string.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogSnapping()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogSnapping ( string eventName,
VisualElement window,
Vector2 rawPos,
Vector2 snappedPos,
string detail = null )
inlinestatic

Logs a magnetic snapping calculation event.

Parameters
eventNameEvent identifier (e.g. "SNAP_SCREEN", "SNAP_NEIGHBOR", "SNAP_SUPPRESSED").
windowThe WindowFrame being positioned.
rawPosCalculated position before snapping.
snappedPosResolved position after magnetic snapping.
detailOptional contextual detail.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogStartup()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogStartup ( string eventName,
string target,
double startedAt = -1,
string detail = null )
inlinestatic

Records startup milestones and bounded geometry-wait samples with a shared monotonic clock.

Parameters
eventNameStage identifier, e.g. STARTUP_WINDOW_ATTACHED.
targetController or window identity, not user content or filesystem paths.
startedAtRealtime seconds at operation start, or negative for a milestone only.
detailStage result or wait reason. Never include theme JSON or user-entered text.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogStyleSheet()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogStyleSheet ( string eventName,
VisualElement scope,
StyleSheet sheet,
string outcome,
int count = -1 )
inlinestatic

Records an actual managed stylesheet operation, not a layout-completion claim.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogThemeNameValidation()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogThemeNameValidation ( TextField field,
Label status,
bool createEnabled )
inlinestatic

Observes validation classes, token resolution and input borders without logging entered names.

Opt-in WindowGeometry diagnostics only. Call after style propagation; does not modify UI.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogThemeSelectorRow()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogThemeSelectorRow ( VisualElement row,
VisualElement star )
inlinestatic

Records independent row states and measured styling, not visual acceptance.

Called after a row geometry event. A usable layout is not proof that all custom styles resolved; image presence and measured colours are observations only. No row names, theme IDs, paths or player text are recorded. Existing channel/compilation gates apply.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ LogTooltip()

void GWG.WindowFramework.Telemetry.WindowFrameTelemetry.LogTooltip ( string eventName,
string tooltipText,
Vector2 mousePos,
Vector2 resolvedPos,
string detail = null )
inlinestatic

Logs a tooltip lifecycle or placement event.

Parameters
eventNameEvent identifier (e.g. "TOOLTIP_TRIGGER", "TOOLTIP_SHOW", "TOOLTIP_HIDE").
tooltipTextText payload of the tooltip.
mousePosPointer position triggering the event.
resolvedPosCalculated anchor coordinate of the tooltip.
detailOptional status or timing detail.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ Measure()

OperationScope GWG.WindowFramework.Telemetry.WindowFrameTelemetry.Measure ( string operation,
TelemetryChannel channel,
string target )
inlinestatic

Starts a bounded feature operation. A disabled scope is inert and allocates nothing.

Here is the caller graph for this function:

◆ ObserveInteractions()

IDisposable GWG.WindowFramework.Telemetry.WindowFrameTelemetry.ObserveInteractions ( VisualElement root)
inlinestatic

Observes semantic UI events in an explicit subtree. Dispose on owner detach/disable.

Records input type, button clicks, focus, and USS transition outcomes; never input values or labels. Attach one observer per owned tree to avoid duplicate events. Transitions are event-driven.

Here is the caller graph for this function:

Field Documentation

◆ _runId

string GWG.WindowFramework.Telemetry.WindowFrameTelemetry._runId
staticprivate

◆ _runIsPlaying

bool GWG.WindowFramework.Telemetry.WindowFrameTelemetry._runIsPlaying
staticprivate

◆ InteractionRoots

readonly System.Collections.Generic.HashSet<VisualElement> GWG.WindowFramework.Telemetry.WindowFrameTelemetry.InteractionRoots = new System.Collections.Generic.HashSet<VisualElement>()
staticprivate

Property Documentation

◆ ActiveChannels

TelemetryChannel GWG.WindowFramework.Telemetry.WindowFrameTelemetry.ActiveChannels = TelemetryChannel.All
staticgetset

Active channel filter mask. Defaults to all channels.

◆ Enabled

bool GWG.WindowFramework.Telemetry.WindowFrameTelemetry.Enabled = false
staticgetset

Master runtime toggle for telemetry emission.