Skip to content

TelemetryEvents.md

Latest commit

 

History

History
602 lines (478 loc) · 42.7 KB

TelemetryEvents.md

File metadata and controls

602 lines (478 loc) · 42.7 KB

Windows Terminal telemetry events

Note: This file is inherited from upstream Windows Terminal (microsoft/terminal) and documents the telemetry events emitted by the underlying Windows Terminal / OpenConsole code that Intelligent Terminal forks from.

Intelligent Terminal-specific telemetry (events emitted by WTA, agent-pane lifecycle, autofix, hooks installation, etc.) is not yet catalogued here. See PRIVACY.md for IT-specific privacy information and how to disable telemetry.

This document enumerates every true telemetry event in the Windows Terminal codebase under src\ — i.e., every TraceLoggingWrite(...) call site whose argument list contains one of the Microsoft telemetry keywords (MICROSOFT_KEYWORD_MEASURES, MICROSOFT_KEYWORD_TELEMETRY, or MICROSOFT_KEYWORD_CRITICAL_DATA) and is therefore reported to Microsoft.

Events grouped by their TRACELOGGING_DEFINE_PROVIDER. Diagnostic-only ETW traces tagged with TIL_KEYWORD_TRACE (UiaTracing.cpp, parser/tracing.cpp, most of host/tracing.cpp, the server *Dispatchers.cpp, VtIo.cpp, VtInputThread.cpp, etc.) are excluded.

Conventions used in the field tables below:

  • Type uses the trailing portion of the TraceLogging<Type>(...) macro (e.g., TraceLoggingBool → Bool, TraceLoggingValue → Value (auto)).
  • Description is the optional 3rd-argument string literal on the metadata macro; a dash (—) means none was supplied.
  • Source expression is paraphrased; literal constants are shown in quotes.
  • Source links are pinned to commit fb71a04 so that the line numbers stay accurate even as the codebase evolves.

Provider: Microsoft.Windows.Terminal.App

  • Symbol: g_hTerminalAppProvider
  • GUID: {24a1622f-7da7-5c77-3303-d850bd1ab2ed}
  • Defined in: src\cascadia\TerminalApp\init.cpp
  • Privacy tag (all events): PDT_ProductAndServiceUsage
  • Keyword (all events): MICROSOFT_KEYWORD_MEASURES

ActionDispatched

  • Description: Event emitted when an action was successfully performed.

  • Source: src\cascadia\TerminalApp\ShortcutActionDispatch.cpp:67

  • Fields:

    Name Type Source expression Description
    Action Value (int) static_cast<int>(actionAndArgs.Action()) —
    Branding Value branding (build branding string) —

AppCreated

  • Description: Event emitted when the application is started.

  • Source: src\cascadia\TerminalApp\AppLogic.cpp:193

  • Fields:

    Name Type Source expression Description
    TabsInTitlebar Bool _settings.GlobalSettings().ShowTabsInTitlebar() —

AppInitialized

  • Description: Event emitted once the app is initialized.

  • Source: src\cascadia\TerminalApp\AppLogic.cpp:475

  • Fields:

    Name Type Source expression Description
    latency Float32 latency (initialization latency) —

CommandPaletteDismissed

CommandPaletteDispatchedAction

  • Description: Event emitted when the user selects an action in the Command Palette.

  • Source: src\cascadia\TerminalApp\CommandPalette.cpp:801

  • Fields:

    Name Type Source expression Description
    SearchTextLength UInt32 searchTextLength Number of characters in the search string.
    NestedCommandDepth UInt32 nestedCommandDepth The depth in the tree of commands for the dispatched action.

CommandPaletteDispatchedCommandline

CommandPaletteOpened

  • Description: Event emitted when the Command Palette is opened.

  • Source: src\cascadia\TerminalApp\CommandPalette.cpp:64

  • Fields:

    Name Type Source expression Description
    Mode WideString L"Action" (literal) Which mode the palette was opened in.

ConnectionCreated

  • Description: Event emitted upon the creation of a connection.

  • Source: src\cascadia\TerminalApp\TerminalPage.cpp:1617

  • Fields:

    Name Type Source expression Description
    ConnectionTypeGuid Guid connectionType The type of the connection.
    ProfileGuid Guid profile.Guid() The profile's GUID.
    SessionGuid Guid connection.SessionId() The WT_SESSION's GUID.

NewTabByDragDrop

NewTabMenuClosed

  • Description: Event emitted when the new tab menu is closed.

  • Source: src\cascadia\TerminalApp\TerminalPage.cpp:1110

  • Fields:

    Name Type Source expression Description
    TabCount Value (int) page->NumberOfTabs() The count of tabs currently opened in this window.

NewTabMenuCreatedNewTerminalSession

  • Description: Event emitted when a new terminal was created via the new tab menu.

  • Source: src\cascadia\TerminalApp\TerminalPage.cpp:1498

  • Fields:

    Name Type Source expression Description
    NewTabCount Value (int) NumberOfTabs() The count of tabs currently opened in this window.
    SessionType Value sessionType The type of session that was created.

NewTabMenuDefaultButtonClicked

  • Description: Event emitted when the default button from the new tab split button is invoked.

  • Source: src\cascadia\TerminalApp\TerminalPage.cpp:400

  • Fields:

    Name Type Source expression Description
    TabCount Value (int) page->NumberOfTabs() The count of tabs currently opened in this window.

NewTabMenuItemClicked

NewTabMenuItemElevateSubmenuItemClicked

  • Description: Event emitted when the elevate submenu item from the new tab menu is invoked.

  • Source: src\cascadia\TerminalApp\TerminalPage.cpp:5935

  • Fields:

    Name Type Source expression Description
    TabCount Value (int) page->NumberOfTabs() The count of tabs currently opened in this window.

NewTabMenuOpened

  • Description: Event emitted when the new tab menu is opened.

  • Source: src\cascadia\TerminalApp\TerminalPage.cpp:1092

  • Fields:

    Name Type Source expression Description
    TabCount Value (int) page->NumberOfTabs() The count of tabs currently opened in this window.

QuickFixSuggestionUsed

SuggestionsControlDismissed

SuggestionsControlDispatchedAction

  • Description: Event emitted when the user selects an action in the Command Palette.

  • Source: src\cascadia\TerminalApp\SuggestionsControl.cpp:749

  • Fields:

    Name Type Source expression Description
    SearchTextLength UInt32 searchTextLength Number of characters in the search string.
    NestedCommandDepth UInt32 nestedCommandDepth The depth in the tree of commands for the dispatched action.

SuggestionsControlOpened

TabRenamerClosed

  • Description: Event emitted when the tab renamer is closed.

  • Source: src\cascadia\TerminalApp\TabHeaderControl.cpp:112

  • Fields:

    Name Type Source expression Description
    CancelledRename Boolean _renameCancelled True if the user cancelled the rename, false if they committed.

TabRenamerOpened

WindowCreated

Provider: Microsoft.Windows.Terminal.Settings.Editor

  • Symbol: g_hTerminalSettingsEditorProvider
  • GUID: {1b16317d-b594-51f8-c552-5d50572b5efc}
  • Defined in: src\cascadia\TerminalSettingsEditor\init.cpp
  • Privacy tag (all events): PDT_ProductAndServiceUsage
  • Keyword (all events): MICROSOFT_KEYWORD_MEASURES

AddNewProfile

  • Description: Event emitted when the user adds a new profile.

  • Source (2 call sites, distinct Type constant per call site):

  • Fields:

    Name Type Source expression Description
    Type Value (string) "EmptyProfile" / "Duplicate" The type of the creation method (i.e. empty profile, duplicate).
    SourceProfileHasSource Value (bool) !selectedProfile.Source().empty() (only for the "Duplicate" variant at line 62) True if the source profile has a source (i.e. dynamic profile generator namespace, fragment). Otherwise, false, indicating it's based on a custom profile.

CreateUnfocusedAppearance

  • Description: Event emitted when the user creates an unfocused appearance for a profile.

  • Source: src\cascadia\TerminalSettingsEditor\Profiles_Appearance.cpp:87

  • Fields:

    Name Type Source expression Description
    IsProfileDefaults Value (bool) _Profile.IsBaseLayer() If the modified profile is the profile.defaults object.
    ProfileGuid Value (GUID) static_cast<GUID>(_Profile.Guid()) The guid of the profile that was navigated to.
    ProfileSource Value (wide string) _Profile.Source().c_str() The source of the profile that was navigated to.

DeleteProfile

  • Description: Event emitted when the user deletes a profile.

  • Source: src\cascadia\TerminalSettingsEditor\Profiles_Base.cpp:93

  • Fields:

    Name Type Source expression Description
    ProfileGuid Value (string) to_hstring(_Profile.Guid()).c_str() The guid of the profile that was navigated to.
    ProfileSource Value (wide string) _Profile.Source().c_str() The source of the profile that was navigated to.
    Orphaned Value (bool) false (literal) Tracks if the profile is orphaned.
    Hidden Value (bool) _Profile.Hidden() Tracks if the profile is hidden.

NavigatedToPage

OpenJson

  • Description: Event emitted when the user clicks the Open JSON button in the settings UI.

  • Source: src\cascadia\TerminalSettingsEditor\MainPage.cpp:417

  • Fields:

    Name Type Source expression Description
    SettingsTarget Value (string) target == SettingsTarget::DefaultsFile ? "DefaultsFile" : "SettingsFile" The target settings file.

ResetApplicationState

ResetToDefaultSettings

Provider: Microsoft.Windows.Terminal.Setting.Model

  • Symbol: g_hSettingsModelProvider
  • GUID: {be579944-4d33-5202-e5d6-a7a57f1935cb}
  • Defined in: src\cascadia\TerminalSettingsModel\init.cpp
  • Privacy tag (all events): PDT_ProductAndServiceUsage
  • Keyword (all events): MICROSOFT_KEYWORD_MEASURES

DefaultTerminalChanged

  • Description: (no TraceLoggingDescription supplied.)

  • Source: src\cascadia\TerminalSettingsModel\DefaultTerminal.cpp:102

  • Fields:

    Name Type Source expression Description
    TerminalName WideString term.Name().c_str() The name of the default terminal.
    TerminalVersion WideString term.Version().c_str() The version of the default terminal.
    TerminalAuthor WideString term.Author().c_str() The author of the default terminal.

JsonSettingsChanged

MarksProfilesUsage

  • Description: Event emitted upon settings load, containing the number of profiles opted-in to scrollbar marks.

  • Source: src\cascadia\TerminalSettingsModel\CascadiaSettingsSerialization.cpp:1378

  • Fields:

    Name Type Source expression Description
    NumberOfAutoMarkPromptsProfiles Int32 totalAutoMark Number of profiles for which AutoMarkPrompts is enabled.
    NumberOfShowMarksProfiles Int32 totalShowMarks Number of profiles for which ShowMarks is enabled.

SendInputUsage

ThemesInUse

  • Description: Data about the themes in use.

  • Source: src\cascadia\TerminalSettingsModel\CascadiaSettingsSerialization.cpp:1337

  • Fields:

    Name Type Source expression Description
    ThemeClass Int32 themeChoice Identifier for the theme chosen. 0 = system (legacySystem = 6), 1 = light (legacyLight = 5), 2 = dark (legacyDark = 4), 3 = any custom theme.
    ChangedTheme Bool changedTheme True if the user actually changed the theme from the default theme.
    NumberOfThemes Int32 numThemes Number of themes in the user's settings.

UISettingsChanged

Provider: Microsoft.Windows.Terminal.Connection

ConPtyConnected

  • Description: Event emitted when ConPTY connection is started.

  • Source: src\cascadia\TerminalConnection\ConptyConnection.cpp:185

  • Privacy tag: PDT_ProductAndServiceUsage

  • Fields:

    Name Type Source expression Description
    SessionGuid Guid _sessionId The WT_SESSION's GUID.
    Client WideString _clientName.c_str() The attached client process.

ConPtyConnectedToDefterm

  • Description: Event emitted when ConPTY connection is started, for a defterm session.

  • Source: src\cascadia\TerminalConnection\ConptyConnection.cpp:433

  • Privacy tag: PDT_ProductAndServiceUsage

  • Fields:

    Name Type Source expression Description
    SessionGuid Guid _sessionId The WT_SESSION's GUID.
    Client WideString _clientName.c_str() The attached client process.

ReceivedFirstByte

  • Description: An event emitted when the connection receives the first byte.

  • Source: src\cascadia\TerminalConnection\ConptyConnection.cpp:785

  • Privacy tag: PDT_ProductAndServicePerformance (differs from the rest of this provider)

  • Fields:

    Name Type Source expression Description
    SessionGuid Guid _sessionId The WT_SESSION's GUID.
    Duration Float64 delta.count() —

ReceiveTerminalHandoff_Success

Provider: Microsoft.Terminal.Core

  • Symbol: g_hCTerminalCoreProvider
  • GUID: {103ac8cf-97d2-51aa-b3ba-5ffd5528fa5f}
  • Defined in: src\cascadia\TerminalCore\TerminalApi.cpp
  • Privacy tag (all events): PDT_ProductAndServiceUsage
  • Keyword (all events): MICROSOFT_KEYWORD_MEASURES

Registered by: src\cascadia\TerminalControl\init.cpp (alongside g_hTerminalControlProvider).

ShellIntegrationWorkingDirSet

Provider: Microsoft.Windows.Terminal.Win32Host

  • Symbol: g_hWindowsTerminalProvider
  • GUID: {56c06166-2e2e-5f4d-7ff3-74f4b78c87d6}
  • Defined in: src\cascadia\WindowsTerminal\main.cpp
  • Privacy tag (all events): PDT_ProductAndServiceUsage
  • Keyword (all events): MICROSOFT_KEYWORD_MEASURES

ExeCreated

SessionBecameInteractive

Provider: Microsoft.Windows.Console.Host

  • Symbol: g_hConhostV2EventTraceProvider
  • GUID: {fe1ff234-1f09-50a8-d38d-c44fab43e818}
  • Defined in: src\host\tracing.cpp
  • Privacy tag (all events): PDT_ProductAndServiceUsage
  • Keyword (all events): MICROSOFT_KEYWORD_MEASURES

Most events written to this provider are diagnostic ETW traces (tagged with TIL_KEYWORD_TRACE) and are out of scope. Only the three telemetry-keyword events below are listed.

ConsoleHandoffFailed

  • Description: Failed while attempting handoff.

  • Source: src\server\IoDispatchers.cpp:385

  • Fields:

    Name Type Source expression Description
    handoffCLSID Guid Globals.delegationPair.console —
    (unnamed) HResult hr —

ConsoleHandoffSessionStarted

  • Description: A new interactive console session was started.

  • Source: src\server\IoDispatchers.cpp:275

  • Fields:

    Name Type Source expression Description
    handoffCLSID Guid Globals.delegationPair.console —
    handoffTargetChosenByWindows Bool handoffTargetChosenByWindows —

ConsoleHandoffSucceeded

  • Description: Successfully handed off console connection.

  • Source: src\server\IoDispatchers.cpp:365

  • Fields:

    Name Type Source expression Description
    handoffCLSID Guid Globals.delegationPair.console —

Provider: Microsoft.Windows.Console.Launcher

  • Symbol: g_ConhostLauncherProvider
  • GUID: {770aa552-671a-5e97-579b-151709ec0dbd}
  • Defined in: src\host\exe\exemain.cpp
  • Privacy tag (all events): PDT_ProductAndServiceUsage

IsLegacyLoaded

  • Description: (no TraceLoggingDescription supplied.) Indicates that the legacy ConhostV1.dll console host was loaded by the launcher.

  • Source: src\host\exe\exemain.cpp:150

  • Keyword: MICROSOFT_KEYWORD_TELEMETRY (differs from the other providers, which all use MICROSOFT_KEYWORD_MEASURES)

  • Fields:

    Name Type Source expression Description
    ConsoleLegacy Bool true (literal) —

Cross-provider: WIL fallback failure event

The helper Microsoft::Console::ErrorReporting::EnableFallbackFailureReporting(<provider>) (see src\inc\WilErrorReporting.h) installs a WIL fallback that emits a single named telemetry event whenever a WIL THROW_… / LOG_… macro reports a failure that hasn't already been logged. The event is written to whichever provider was most recently passed to EnableFallbackFailureReporting in the current module.

Each Terminal DLL/EXE in this list passes its own provider, so this event can appear under any of them:

FallbackError

  • Description: WIL-reported failure that was not already reported elsewhere. (HRESULT 0x80131515 — XAML accessibility — is filtered out.)

  • Source: src\inc\WilErrorReporting.h:32

  • Privacy tag: PDT_ProductAndServicePerformance

  • Keyword: MICROSOFT_KEYWORD_TELEMETRY

  • Level: WINEVENT_LEVEL_ERROR

  • Fields (all wrapped inside a TraceLoggingStruct(14, "wilResult")):

    Name Type Source expression Description
    hresult UInt32 failure.hr Failure error code.
    fileName String failure.pszFile Source code file name where the error occurred.
    lineNumber UInt32 failure.uLineNumber Line number within the source code file where the error occurred.
    module String failure.pszModule Name of the binary where the error occurred.
    failureType UInt32 static_cast<DWORD>(failure.type) Indicates what type of failure was observed (exception, returned error, logged error or fail fast).
    message WideString failure.pszMessage Custom message associated with the failure (if any).
    threadId UInt32 failure.threadId Identifier of the thread the error occurred on.
    callContext String failure.pszCallContext List of telemetry activities containing this error.
    originatingContextId UInt32 failure.callContextOriginating.contextId Identifier for the oldest telemetry activity containing this error.
    originatingContextName String failure.callContextOriginating.contextName Name of the oldest telemetry activity containing this error.
    originatingContextMessage WideString failure.callContextOriginating.contextMessage Custom message associated with the oldest telemetry activity containing this error (if any).
    currentContextId UInt32 failure.callContextCurrent.contextId Identifier for the newest telemetry activity containing this error.
    currentContextName String failure.callContextCurrent.contextName Name of the newest telemetry activity containing this error.
    currentContextMessage WideString failure.callContextCurrent.contextMessage Custom message associated with the newest telemetry activity containing this error (if any).

Providers with no telemetry events

These providers are defined and registered but emit no telemetry-keyword events. They are listed here for completeness; their (diagnostic) events are out of scope.

Provider GUID Defined in
g_hTerminalControlProvider (Microsoft.Windows.Terminal.Control) {28c82e50-57af-5a86-c25b-e39cd990032b} src\cascadia\TerminalControl\init.cpp
g_UiaProviderTraceProvider (Microsoft.Windows.Console.UIA) {e7ebce59-2161-572d-b263-2f16a6afb9e5} src\types\UiaTracing.cpp
g_hConsoleVirtTermParserEventTraceProvider (Microsoft.Windows.Console.VirtualTerminal.Parser) {c9ba2a84-d3ca-5e19-2bd6-776a0910cb9d} src\terminal\parser\tracing.cpp

g_hConhostV2EventTraceProvider is also used for many diagnostic events; only its telemetry-keyword events are listed above. g_hTerminalControlProvider has no TraceLoggingWrite calls at all in the source tree but receives the cross-provider FallbackError event when its DLL is the most recent caller of EnableFallbackFailureReporting.