Skip to content

TelemetryEvents.md

Latest commit

 

History

History
696 lines (549 loc) · 48.5 KB

TelemetryEvents.md

File metadata and controls

696 lines (549 loc) · 48.5 KB
Raw

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 events are summarized below. See PRIVACY.md for privacy information and how to disable telemetry.

Intelligent Terminal-specific events

Intelligent Terminal events use controlled categories and aggregate measurements. They do not include prompts, responses, terminal contents, API keys, credential identifiers, custom endpoint URLs, model identifiers, custom agent names, or custom agent command lines.

Agent identifiers are limited to copilot, claude, codex, gemini, and opencode; every other identifier is reported as custom.

Provider: Microsoft.Windows.Terminal.App

This existing Terminal provider emits the following Intelligent Terminal-specific events:

Event Trigger Fields
AgentPaneOpened An agent pane is created, restored, or opened into a requested view. Closing or stashing the pane does not emit this event. TriggerSource, Branding
CommandPaletteDispatchedAgentPrompt A foreground or background agent prompt is submitted through the Command Palette. IsBackgroundMode
DelegateInvoked Terminal successfully launches wta delegate. TriggerSource (CommandPalette or Action)
ErrorDetected Terminal receives the first auto-detected error state for a pane. Branding

Current AgentPaneOpened.TriggerSource values are Action, SessionsAction, Autofix, FirstRunExperience, AgentSwitch, BottomBarToggle, BottomBarSessions, SettingsReload, and FocusAction.

Provider: Microsoft.Windows.Terminal.Setting.Model

These census events are emitted from the effective settings during settings load:

Event Trigger Fields and controlled values
AgentProviderConfigured Emitted once for the effective ACP agent and once for the effective delegate agent when configured. ProviderType (AcpAgent or DelegateAgent), ProviderId, Branding, Distribution. Unknown and custom provider IDs are reported as custom.
CustomModelProviderConfigured Emitted once for each configured BYOK/custom model provider. HasApiKey (a credential reference is configured), ApiKeyRequired (the provider requires a key), Branding, Distribution. No provider, endpoint, model, credential, or key value is included.
IntelligentFeatureConfigured Emitted once for each supported Intelligent Terminal setting using its effective value. FeatureName, FeatureValue, Branding, Distribution

IntelligentFeatureConfigured currently reports:

FeatureName FeatureValue
AutoErrorDetection true or false
AutoFix true or false
AgentPanePosition The controlled pane-position setting value
QuotaUsage true or false
VerticalTabs true or false

Provider: Microsoft.Windows.Terminal.WTA

  • GUID: {4cfcff80-4e6b-5bfd-8ea1-d38e1226f70b}
  • Keyword: MICROSOFT_KEYWORD_MEASURES
  • Level: Verbose

ACP lifecycle and performance

Event Trigger Fields
AcpInitializeComplete An ACP initialize attempt completes or times out. DurationMs, Success, Route, FailureKind, AcpErrorCode
AcpNewSessionComplete An ACP session/new attempt completes or times out. SessionId (empty on failure), DurationMs, Success, Route, FailureKind, AcpErrorCode
AgentColdStartComplete A newly spawned agent process finishes or fails its ACP initialization. Warm process-pool reuse does not emit this event. AgentId, Source, DurationMs, Success, FailureKind

ACP lifecycle durations use monotonic clocks. FailureKind is empty on success; ACP RPC failures use AcpError or Timeout. Cold-start failures use SpawnFailed, InitializeFailed, or Timeout. AgentColdStartComplete.Source is Host or Wsl.

Agent turns and autofix

Event Trigger Fields
AgentPromptSent WTA dispatches a prompt to an agent over ACP, including manual and automatic autofix prompts. SessionId, PromptLengthBytes, IsAutofix, IsByok, AgentId, TemplateKind, Route (AcpDispatch)
AgentResponseFirstToken The first user-visible response chunk arrives. SessionId, FirstTokenLatencyMs, ChunkLengthBytes, AgentId
AgentResponseComplete The ACP prompt request completes. SessionId, TotalDurationMs, TotalResponseBytes, Success, IsByok, AgentId
ErrorDetected WTA's classifier identifies an actionable or critical pane error. Severity, Method, PaneId
ErrorFixResolved The next command after an attempted fix succeeds in the same pane. PaneId, TimeSinceFixMs, AgentId

Prompt and response text is never included. Length fields contain byte counts only. IsByok is captured for the specific prompt so live model changes are attributed correctly. TotalResponseBytes is currently unpopulated and retained for schema compatibility.

Commands, sessions, delegation, MCP, and hooks

Event Trigger Fields and controlled values
SlashCommandInvoked WTA dispatches a registered slash command. CommandName: help, clear, new, fix, restart, stop, sessions, agent, model, config, or move
SessionsViewOpened The Agent Session View is opened. None
SessionResumeInvoked A resume operation is dispatched from Agent Session View. Route (AgentPane for ACP session/load, or Cli for provider-native CLI resume), AgentId
DelegateInvoked An agent recommendation invokes the configured delegate through WTA. TriggerSource (Agent)
SessionMcpToolCalled A session MCP function is invoked. ToolName: terminal_send, terminal_open, terminal_open_and_send, request_user_input, or unknown
HookOperationCompleted Hook installation or uninstallation finishes for one supported CLI. Operation (Install or Uninstall), Cli (copilot, claude, gemini, codex, or opencode), Outcome

Install outcomes are installed, skipped, or failed. Uninstall outcomes are succeeded, skipped, or failed.

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.