Skip to content

Commit f047dd8

Browse files
baronfelbaronfel
authored
add a repo-local telemetry doc and notification for folks that work on CLI Telemetry (#50867)
1 parent 9208954 commit f047dd8

File tree

2 files changed

+314
-6
lines changed

2 files changed

+314
-6
lines changed

‎.github/policies/resourceManagement.yml‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
id:
1+
id:
22
name: GitOps.PullRequestIssueManagement
33
description: GitOps.PullRequestIssueManagement primitive
4-
owner:
4+
owner:
55
resource: repository
66
disabled: false
7-
where:
7+
where:
88
configuration:
99
resourceManagementConfiguration:
1010
scheduledSearches:
@@ -90,7 +90,7 @@ configuration:
9090
label: needs-breaking-change-doc-created
9191
- addReply:
9292
reply: >-
93-
Added `needs-breaking-change-doc-created` label because this PR has the `breaking-change` label.
93+
Added `needs-breaking-change-doc-created` label because this PR has the `breaking-change` label.
9494
9595
9696
When you commit this breaking change:
@@ -103,5 +103,23 @@ configuration:
103103
104104
You can refer to the [.NET SDK breaking change guidelines](https://github.com/dotnet/sdk/blob/main/documentation/project-docs/breaking-change-guidelines.md)
105105
description: Add breaking change instructions to PR.
106-
onFailure:
107-
onSuccess:
106+
- description: Remind Telemetry PR authors of the telemetry guidelines
107+
if:
108+
- payloadType: Pull_Request
109+
- labelAdded:
110+
label: Area-Telemetry
111+
then:
112+
- addReply:
113+
reply: >-
114+
This PR has been labeled with `Area-Telemetry`. Please ensure that any telemetry changes in this PR
115+
116+
* comply with the [published guidance](https://learn.microsoft.com/dotnet/core/tools/telemetry#data-points)
117+
* are added to the [repo-local telemetry documentation](./documentation/project-docs/telemetry.md)
118+
* get a matching .NET Docs issue raised to document the telemetry changes
119+
* Go to https://learn.microsoft.com/dotnet/core/tools/telemetry
120+
* Scroll down to the bottom and click the 'Open a documentation issue' link to create an issue with pre-filled details
121+
- requestReview:
122+
reviewer: dsplaisted
123+
124+
onFailure:
125+
onSuccess:

‎documentation/project-docs/telemetry.md‎

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
# .NET SDK Telemetry Documentation
2+
3+
## Table of Contents
4+
- [.NET SDK Telemetry Documentation](#net-sdk-telemetry-documentation)
5+
- [Table of Contents](#table-of-contents)
6+
- [How to Control Telemetry](#how-to-control-telemetry)
7+
- [Common Properties Collected](#common-properties-collected)
8+
- [Telemetry Events](#telemetry-events)
9+
- [Core CLI Events](#core-cli-events)
10+
- [Template Engine Events](#template-engine-events)
11+
- [SDK-Collected Build Events](#sdk-collected-build-events)
12+
- [MSBuild Engine Telemetry](#msbuild-engine-telemetry)
13+
- [Container Events](#container-events)
14+
- [`dotnet new` Command MSBuild Evaluation](#dotnet-new-command-msbuild-evaluation)
15+
- [How to update this document](#how-to-update-this-document)
16+
17+
## How to Control Telemetry
18+
19+
### Disabling Telemetry
20+
21+
The .NET SDK telemetry can be disabled using the following environment variable:
22+
23+
- **`DOTNET_CLI_TELEMETRY_OPTOUT`**: Set to `1`, `true`, or `yes` to opt-out of telemetry collection
24+
- Example: `export DOTNET_CLI_TELEMETRY_OPTOUT=1` (Linux/macOS)
25+
- Example: `set DOTNET_CLI_TELEMETRY_OPTOUT=1` (Windows)
26+
- 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.)
27+
28+
29+
### Related Environment Variables
30+
31+
- **`DOTNET_NOLOGO`**: Set to `true` to hide .NET welcome and telemetry messages on first run
32+
- Values: `true`, `1`, or `yes` to mute messages
33+
- Values: `false`, `0`, or `no` to allow messages
34+
- Default: `false` (messages are displayed)
35+
- Note: This flag does not affect telemetry collection itself
36+
37+
### Telemetry Configuration
38+
39+
- **Default Behavior**:
40+
- For Microsoft official builds: Telemetry is **enabled by default** (opt-out model)
41+
- For non-Microsoft builds: Telemetry is **disabled by default** (controlled by `MICROSOFT_ENABLE_TELEMETRY` compile flag)
42+
43+
44+
- **Connection String**: Telemetry data is sent to Application Insights with instrumentation key: `74cc1c9e-3e6e-4d05-b3fc-dde9101d0254`
45+
46+
- **First Time Use**: Telemetry is only collected after the first-time-use notice has been shown and accepted (tracked via sentinel file)
47+
48+
- **Event Namespace**: All telemetry events are automatically prefixed with `dotnet/cli/`
49+
50+
## Common Properties Collected
51+
52+
Every telemetry event automatically includes these common properties:
53+
54+
55+
56+
| Property | Description | Example Value |
57+
|----------|-------------|---------------|
58+
| **OS Version** | Operating system version | `Microsoft Windows 10.0.14393` |
59+
| **OS Platform** | Operating system platform | `Windows`, `Linux`, `OSX` |
60+
| **OS Architecture** | Operating system architecture | `X64`, `X86`, `Arm64` |
61+
| **Output Redirected** | Whether console output is redirected | `True` or `False` |
62+
| **Runtime Id** | .NET runtime identifier | `win10-x64`, `linux-x64` |
63+
| **Product Version** | .NET SDK version | `8.0.100` |
64+
| **Telemetry Profile** | Custom telemetry profile (if set via env var) | Custom value or null |
65+
| **Docker Container** | Whether running in Docker container | `True` or `False` |
66+
| **CI** | Whether running in CI environment | `True` or `False` |
67+
| **Current Path Hash** | SHA256 hash of current directory path | Hashed value |
68+
| **Machine ID** | SHA256 hash of machine MAC address (or GUID if unavailable) | Hashed value |
69+
| **Machine ID Old** | Legacy machine ID for compatibility | Hashed value |
70+
| **Device ID** | Device identifier | Device-specific ID |
71+
| **Kernel Version** | OS kernel version | `Darwin 17.4.0`, `Linux 4.9.0` |
72+
| **Installation Type** | How the SDK was installed | Installation method |
73+
| **Product Type** | Type of .NET product | Product identifier |
74+
| **Libc Release** | Libc release information | Libc release version |
75+
| **Libc Version** | Libc version information | Libc version number |
76+
| **SessionId** | Unique session identifier | GUID |
77+
78+
## Telemetry Events
79+
80+
### Core CLI Events
81+
82+
#### `command/finish`
83+
**When fired**: At the end of every dotnet CLI command execution
84+
85+
**Properties**:
86+
- `exitCode`: The exit code of the command
87+
88+
**Description**: Tracks the completion status of any dotnet command
89+
90+
---
91+
92+
#### `schema`
93+
**When fired**: When CLI schema is generated or accessed
94+
95+
**Properties**:
96+
- `command`: The command hierarchy as a string
97+
98+
**Description**: Tracks schema generation for the CLI
99+
100+
---
101+
102+
#### `toplevelparser/command`
103+
**When fired**: For every top-level dotnet command
104+
105+
**Properties**:
106+
- `verb`: Top-level command name (build, restore, publish, etc.)
107+
108+
**Measurements**: Performance data (startup time, parse time, etc.)
109+
110+
**Description**: Tracks usage patterns of main dotnet commands
111+
112+
---
113+
114+
#### `sublevelparser/command`
115+
**When fired**: For subcommands and specific command options
116+
117+
**Properties**: Various depending on command (verbosity, configuration, framework, etc.)
118+
119+
**Description**: Tracks detailed command option usage
120+
121+
---
122+
123+
#### `commandresolution/commandresolved`
124+
**When fired**: When a command is resolved through the command factory
125+
126+
**Properties**:
127+
- `commandName`: SHA256 hash of command name
128+
- `commandResolver`: Type of command resolver used
129+
130+
**Description**: Tracks how commands are resolved in the CLI
131+
132+
---
133+
134+
#### `install/reportsuccess`
135+
**When fired**: When installation success is reported
136+
137+
**Properties**:
138+
- `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.
139+
140+
**Description**: Tracks successful tool installations
141+
142+
---
143+
144+
#### `mainCatchException/exception`
145+
**When fired**: When unhandled exceptions occur in the main CLI
146+
147+
**Properties**:
148+
- `exceptionType`: Type of exception
149+
- `detail`: Exception details (sensitive message removed)
150+
151+
**Description**: Tracks unhandled exceptions for diagnostics
152+
153+
### Template Engine Events
154+
155+
#### `template/new-install`
156+
**When fired**: During template package installation
157+
158+
**Properties**:
159+
- `CountOfThingsToInstall`: Number of template packages being installed
160+
161+
**Description**: Tracks template package installation operations
162+
163+
---
164+
165+
#### `template/new-create-template`
166+
**When fired**: When creating a new project from template
167+
168+
**Properties**:
169+
- `language`: Template language (C#, F#, VB, etc)
170+
- `argument-error`: Whether there were argument errors ("True"/"False")
171+
- `framework`: Framework choice (only sent for Microsoft-authored templates)
172+
- `template-name`: SHA256 hash of template identity
173+
- `template-short-name`: SHA256 hash of template short names
174+
- `package-name`: SHA256 hash of package name
175+
- `package-version`: SHA256 hash of package version
176+
- `is-template-3rd-party`: Whether template is third-party
177+
- `create-success`: Whether creation succeeded
178+
- `auth`: Authentication choice (only sent for Microsoft-authored templates)
179+
180+
**Description**: Tracks template usage and creation success
181+
182+
### SDK-Collected Build Events
183+
184+
#### `msbuild/targetframeworkeval`
185+
**When fired**: When target framework is evaluated
186+
187+
**Properties**:
188+
- `TargetFrameworkVersion`: Target framework version
189+
- `RuntimeIdentifier`: Runtime identifier
190+
- `SelfContained`: Whether self-contained
191+
- `UseApphost`: Whether using app host
192+
- `OutputType`: Output type (Exe, Library, etc.)
193+
- `UseArtifactsOutput`: Whether using artifacts output
194+
- `ArtifactsPathLocationType`: Artifacts path location type - one of `Explicitly Specified`, `DirectoryBuildPropsFolder`, or `ProjectFolder`.
195+
196+
**Description**: Tracks target framework configurations
197+
198+
---
199+
200+
201+
#### `taskBaseCatchException`
202+
**When fired**: When exceptions occur in SDK-provided MSBuild tasks
203+
204+
**Properties**:
205+
- `exceptionType`: Exception type
206+
- `detail`: Exception details (message removed)
207+
208+
**Description**: Tracks exceptions in MSBuild task execution
209+
210+
---
211+
212+
#### `PublishProperties`
213+
**When fired**: During the Publish Target
214+
215+
**Properties**: Gathers the values of the following MSBuild Properties if they are set in the project file or via command line:
216+
* PublishReadyToRun
217+
* PublishSingleFile
218+
* PublishTrimmed
219+
* PublishAot
220+
* PublishProtocol
221+
222+
**Description**: Tracks publish-related properties
223+
224+
---
225+
226+
#### `WorkloadPublishProperties`
227+
**When fired**: During workload publish operations
228+
229+
**Properties**: Gathers the values of the following MSBuild Properties if they are set in the project file or via command line:
230+
* TargetPlatformIdentifier: TargetPlatformIdentifier
231+
* RuntimeIdentifier: RuntimeIdentifier
232+
* BlazorWasm: _WorkloadUsesBlazorWasm
233+
* WasmSDK: _WorkloadUsesWasmSDK
234+
* UsesMaui: UseMaui
235+
* UsesMobileSDKOnly: _WorkloadUsesMobileSDKOnly
236+
* UsesOtherMobileSDK: _WorkloadUsesOther
237+
* MonoAOT: _WorkloadUsesMonoAOT
238+
* NativeAOT: _WorkloadUsesNativeAOT
239+
* Interp: _WorkloadUsesInterpreter
240+
* LibraryMode: _WorkloadUsesLibraryMode
241+
* ResolvedRuntimePack: _MonoWorkloadRuntimePackPackageVersion
242+
* StripILAfterAOT: _WorkloadUsesStripILAfterAOT
243+
244+
**Description**: Tracks workload-specific publish properties
245+
246+
---
247+
248+
#### `ReadyToRun`
249+
**When fired**: During ReadyToRun compilation
250+
251+
**Properties**: Gathers the values of the following MSBuild Properties and Items if they are set in the project file or via command line:
252+
253+
* PublishReadyToRunUseCrossgen2: PublishReadyToRunUseCrossgen2
254+
* Crossgen2PackVersion: ResolvedCrossgen2Pack.NuGetPackageVersion
255+
* CompileListCount: _ReadyToRunCompileList->Count()
256+
* FailedCount: _ReadyToRunCompilationFailures->Count()
257+
258+
**Description**: Tracks ReadyToRun compilation usage
259+
260+
### MSBuild Engine Telemetry
261+
262+
See [MSBuild Telemetry Documentation](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/CollectedTelemetry.md) for details on these events.
263+
264+
### Container Events
265+
266+
See [Container Telemetry Documentation](https://github.com/dotnet/sdk-container-builds/blob/main/docs/Telemetry.md) for details.
267+
268+
### `dotnet new` Command MSBuild Evaluation
269+
270+
#### `new/msbuild-eval`
271+
**When fired**: When MSBuild project evaluation occurs during `dotnet new`
272+
273+
**Properties** (hashed):
274+
- `ProjectPath`: Project path
275+
- `SdkStyleProject`: Whether it's SDK-style project
276+
- `Status`: Evaluation status
277+
- `TargetFrameworks`: Target frameworks
278+
279+
**Measurements**:
280+
- `EvaluationTime`: Total evaluation time in milliseconds
281+
- `InnerEvaluationTime`: Inner evaluation time in milliseconds
282+
283+
**Description**: Tracks MSBuild evaluation performance for new projects
284+
285+
## How to update this document
286+
287+
* Ensure that all telemetry events and properties are accurately documented
288+
* Review and update common properties as needed
289+
* Add new events or properties as they are introduced in the .NET SDK
290+
* Follow the pre-existing format

0 commit comments

Comments
 (0)