Skip to content

Add LLM environment property to telemetry docs #50961

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 22, 2025
Merged

Add LLM environment property to telemetry docs #50961

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3e88895
Add LLM environment property to telemetry docs
MichaelSimons Sep 22, 2025
b21272b
Address linter errors
MichaelSimons Sep 22, 2025
a4df5b7
Tweak wording
MichaelSimons Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 59 additions & 31 deletions documentation/project-docs/telemetry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# .NET SDK Telemetry Documentation

## Table of Contents

- [.NET SDK Telemetry Documentation](#net-sdk-telemetry-documentation)
- [Table of Contents](#table-of-contents)
- [How to Control Telemetry](#how-to-control-telemetry)
Expand All @@ -25,7 +26,6 @@ The .NET SDK telemetry can be disabled using the following environment variable:
- Example: `set DOTNET_CLI_TELEMETRY_OPTOUT=1` (Windows)
- Note: this value is defaulted to `true` on non-Microsoft-provided builds of the .NET SDK (e.g. those provided by our Linux Distro partners, through Source Build, etc.)


### Related Environment Variables

- **`DOTNET_NOLOGO`**: Set to `true` to hide .NET welcome and telemetry messages on first run
Expand All @@ -40,7 +40,6 @@ The .NET SDK telemetry can be disabled using the following environment variable:
- For Microsoft official builds: Telemetry is **enabled by default** (opt-out model)
- For non-Microsoft builds: Telemetry is **disabled by default** (controlled by `MICROSOFT_ENABLE_TELEMETRY` compile flag)


- **Connection String**: Telemetry data is sent to Application Insights with instrumentation key: `74cc1c9e-3e6e-4d05-b3fc-dde9101d0254`

- **First Time Use**: Telemetry is only collected after the first-time-use notice has been shown and accepted (tracked via sentinel file)
Expand All @@ -51,8 +50,6 @@ The .NET SDK telemetry can be disabled using the following environment variable:

Every telemetry event automatically includes these common properties:



| Property | Description | Example Value |
|----------|-------------|---------------|
| **OS Version** | Operating system version | `Microsoft Windows 10.0.14393` |
Expand All @@ -64,6 +61,7 @@ Every telemetry event automatically includes these common properties:
| **Telemetry Profile** | Custom telemetry profile (if set via env var) | Custom value or null |
| **Docker Container** | Whether running in Docker container | `True` or `False` |
| **CI** | Whether running in CI environment | `True` or `False` |
| **LLM** | Detected LLM/assistant environment identifiers (comma-separated) | `claude` or `cursor` |
| **Current Path Hash** | SHA256 hash of current directory path | Hashed value |
| **Machine ID** | SHA256 hash of machine MAC address (or GUID if unavailable) | Hashed value |
| **Machine ID Old** | Legacy machine ID for compatibility | Hashed value |
Expand All @@ -80,29 +78,35 @@ Every telemetry event automatically includes these common properties:
### Core CLI Events

#### `command/finish`

**When fired**: At the end of every dotnet CLI command execution

**Properties**:

- `exitCode`: The exit code of the command

**Description**: Tracks the completion status of any dotnet command

---

#### `schema`

**When fired**: When CLI schema is generated or accessed

**Properties**:

- `command`: The command hierarchy as a string

**Description**: Tracks schema generation for the CLI

---

#### `toplevelparser/command`

**When fired**: For every top-level dotnet command

**Properties**:

- `verb`: Top-level command name (build, restore, publish, etc.)

**Measurements**: Performance data (startup time, parse time, etc.)
Expand All @@ -112,6 +116,7 @@ Every telemetry event automatically includes these common properties:
---

#### `sublevelparser/command`

**When fired**: For subcommands and specific command options

**Properties**: Various depending on command (verbosity, configuration, framework, etc.)
Expand All @@ -121,9 +126,11 @@ Every telemetry event automatically includes these common properties:
---

#### `commandresolution/commandresolved`

**When fired**: When a command is resolved through the command factory

**Properties**:

- `commandName`: SHA256 hash of command name
- `commandResolver`: Type of command resolver used

Expand All @@ -132,19 +139,23 @@ Every telemetry event automatically includes these common properties:
---

#### `install/reportsuccess`

**When fired**: When installation success is reported

**Properties**:

- `exeName`: Name of the install method that was used - one of `debianpackage`, a specific macOS `.pkg` file name, or a specific Windows exe installer file name.

**Description**: Tracks successful tool installations

---

#### `mainCatchException/exception`

**When fired**: When unhandled exceptions occur in the main CLI

**Properties**:

- `exceptionType`: Type of exception
- `detail`: Exception details (sensitive message removed)

Expand All @@ -153,19 +164,23 @@ Every telemetry event automatically includes these common properties:
### Template Engine Events

#### `template/new-install`

**When fired**: During template package installation

**Properties**:

- `CountOfThingsToInstall`: Number of template packages being installed

**Description**: Tracks template package installation operations

---

#### `template/new-create-template`

**When fired**: When creating a new project from template

**Properties**:

- `language`: Template language (C#, F#, VB, etc)
- `argument-error`: Whether there were argument errors ("True"/"False")
- `framework`: Framework choice (only sent for Microsoft-authored templates)
Expand All @@ -182,9 +197,11 @@ Every telemetry event automatically includes these common properties:
### SDK-Collected Build Events

#### `msbuild/targetframeworkeval`

**When fired**: When target framework is evaluated

**Properties**:

- `TargetFrameworkVersion`: Target framework version
- `RuntimeIdentifier`: Runtime identifier
- `SelfContained`: Whether self-contained
Expand All @@ -197,11 +214,12 @@ Every telemetry event automatically includes these common properties:

---


#### `taskBaseCatchException`

**When fired**: When exceptions occur in SDK-provided MSBuild tasks

**Properties**:

- `exceptionType`: Exception type
- `detail`: Exception details (message removed)

Expand All @@ -210,53 +228,60 @@ Every telemetry event automatically includes these common properties:
---

#### `PublishProperties`

**When fired**: During the Publish Target

**Properties**: Gathers the values of the following MSBuild Properties if they are set in the project file or via command line:
* PublishReadyToRun
* PublishSingleFile
* PublishTrimmed
* PublishAot
* PublishProtocol

- PublishReadyToRun
- PublishSingleFile
- PublishTrimmed
- PublishAot
- PublishProtocol

**Description**: Tracks publish-related properties

---

#### `WorkloadPublishProperties`

**When fired**: During workload publish operations

**Properties**: Gathers the values of the following MSBuild Properties if they are set in the project file or via command line:
* TargetPlatformIdentifier: TargetPlatformIdentifier
* RuntimeIdentifier: RuntimeIdentifier
* BlazorWasm: _WorkloadUsesBlazorWasm
* WasmSDK: _WorkloadUsesWasmSDK
* UsesMaui: UseMaui
* UsesMobileSDKOnly: _WorkloadUsesMobileSDKOnly
* UsesOtherMobileSDK: _WorkloadUsesOther
* MonoAOT: _WorkloadUsesMonoAOT
* NativeAOT: _WorkloadUsesNativeAOT
* Interp: _WorkloadUsesInterpreter
* LibraryMode: _WorkloadUsesLibraryMode
* ResolvedRuntimePack: _MonoWorkloadRuntimePackPackageVersion
* StripILAfterAOT: _WorkloadUsesStripILAfterAOT

- TargetPlatformIdentifier: TargetPlatformIdentifier
- RuntimeIdentifier: RuntimeIdentifier
- BlazorWasm: _WorkloadUsesBlazorWasm
- WasmSDK: _WorkloadUsesWasmSDK
- UsesMaui: UseMaui
- UsesMobileSDKOnly: _WorkloadUsesMobileSDKOnly
- UsesOtherMobileSDK: _WorkloadUsesOther
- MonoAOT: _WorkloadUsesMonoAOT
- NativeAOT: _WorkloadUsesNativeAOT
- Interp: _WorkloadUsesInterpreter
- LibraryMode: _WorkloadUsesLibraryMode
- ResolvedRuntimePack: _MonoWorkloadRuntimePackPackageVersion
- StripILAfterAOT: _WorkloadUsesStripILAfterAOT

**Description**: Tracks workload-specific publish properties

---

#### `ReadyToRun`

**When fired**: During ReadyToRun compilation

**Properties**: Gathers the values of the following MSBuild Properties and Items if they are set in the project file or via command line:

* PublishReadyToRunUseCrossgen2: PublishReadyToRunUseCrossgen2
* Crossgen2PackVersion: ResolvedCrossgen2Pack.NuGetPackageVersion
* CompileListCount: _ReadyToRunCompileList->Count()
* FailedCount: _ReadyToRunCompilationFailures->Count()
- PublishReadyToRunUseCrossgen2: PublishReadyToRunUseCrossgen2
- Crossgen2PackVersion: ResolvedCrossgen2Pack.NuGetPackageVersion
- CompileListCount: _ReadyToRunCompileList->Count()
- FailedCount: _ReadyToRunCompilationFailures->Count()

**Description**: Tracks ReadyToRun compilation usage

---

### MSBuild Engine Telemetry

See [MSBuild Telemetry Documentation](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/CollectedTelemetry.md) for details on these events.
Expand All @@ -268,23 +293,26 @@ See [Container Telemetry Documentation](https://github.com/dotnet/sdk-container-
### `dotnet new` Command MSBuild Evaluation

#### `new/msbuild-eval`

**When fired**: When MSBuild project evaluation occurs during `dotnet new`

**Properties** (hashed):

- `ProjectPath`: Project path
- `SdkStyleProject`: Whether it's SDK-style project
- `Status`: Evaluation status
- `TargetFrameworks`: Target frameworks

**Measurements**:

- `EvaluationTime`: Total evaluation time in milliseconds
- `InnerEvaluationTime`: Inner evaluation time in milliseconds

**Description**: Tracks MSBuild evaluation performance for new projects

## How to update this document

* Ensure that all telemetry events and properties are accurately documented
* Review and update common properties as needed
* Add new events or properties as they are introduced in the .NET SDK
* Follow the pre-existing format
- Ensure that all telemetry events and properties are accurately documented
- Review and update common properties as needed
- Add new events or properties as they are introduced in the .NET SDK
- Follow the pre-existing format