-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add basic guidelines for telemetry usage for tooling authors (#43097)
Co-authored-by: Noah Gilson <noahgilson@microsoft.com>
- Loading branch information
Showing
1 changed file
with
39 additions
and
0 deletions.
There are no files selected for viewing
39 changes: 39 additions & 0 deletions
39
documentation/project-docs/external-component-telemetry.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
# Responsibly managing telemetry in external components | ||
|
||
Many components are _delivered_ with or by the .NET SDK but want to collect and | ||
manage telemetry. The SDK has telemetry collection mechanisms that may appear | ||
attractive, but present down-sides for these authors. | ||
|
||
This document clarifies some guidelines for authors of components that are consumed by the .NET SDK but want to own their own telemetry. | ||
|
||
## Sending telemetry | ||
|
||
### DO create and manage your own MSBuild Task for sending telemetry | ||
|
||
This allows you to have full control over the telemetry you send, where it is | ||
sent, and any PII masking requirements that are unique to your product. | ||
Attempting to use the .NET SDK's `AllowEmptyTelemetry` mechanism is not | ||
recommended for most internal partners and all external users. This is because | ||
`AllowEmptyTelemetry` | ||
* is allow-listed for known events only, so your telemetry will not be sent | ||
* sends to the SDK's telemetry storage, which your team may not have access to | ||
* is dependent on the SDK version the user uses, which may lag behind the latest available | ||
|
||
### DO NOT use the MSBuild Engine telemetry APIs for logging telemetry | ||
|
||
These APIs, while convenient, require the MSBuild Engine Host (`dotnet build`, | ||
`msbuild.exe`, Visual Studio Project system) to have configured a telemetry | ||
collector. This is not guaranteed to be the case for all users of your component, | ||
and the collector configured may not send telemetry in the manner you expect, or | ||
to destinations you expect. | ||
|
||
## Managing telemetry | ||
|
||
### DO adhere to the SDK telemetry opt-out | ||
|
||
The SDK has an [opt out](https://learn.microsoft.com/dotnet/core/tools/telemetry#how-to-opt-out) mechanism for telemetry that all SDK-generated | ||
telemetry should adhere to. When running in the context of the SDK that means your | ||
telemetry should adhere to this signal as well. This opt-out mechanism is an | ||
environment variable, but the default value of this variable changes for | ||
Microsoft-authored and source-built SDKs. The SDK should provide a unified | ||
mechanism for tooling authors to rely on instead of probing for this value. |