From 80f0b7c47d414eef918a8556040e348c9f3aec9c Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Thu, 29 Aug 2024 15:43:41 -0500 Subject: [PATCH 1/2] add basic guidelines for telemetry usage for tooling authors --- .../external-component-telemetry.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 documentation/project-docs/external-component-telemetry.md diff --git a/documentation/project-docs/external-component-telemetry.md b/documentation/project-docs/external-component-telemetry.md new file mode 100644 index 000000000000..b82eef408d02 --- /dev/null +++ b/documentation/project-docs/external-component-telemetry.md @@ -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/en-us/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. From 484ed1957b955ac68926978c128a006cb9c9e2c1 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Thu, 5 Sep 2024 11:25:17 -0500 Subject: [PATCH 2/2] Update external-component-telemetry.md Fixes that Yanni found --- documentation/project-docs/external-component-telemetry.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/project-docs/external-component-telemetry.md b/documentation/project-docs/external-component-telemetry.md index b82eef408d02..77c347e4ab69 100644 --- a/documentation/project-docs/external-component-telemetry.md +++ b/documentation/project-docs/external-component-telemetry.md @@ -8,7 +8,7 @@ This document clarifies some guidelines for authors of components that are consu ## Sending telemetry -### DO create and manage your own MSBuild Task for 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. @@ -29,9 +29,9 @@ to destinations you expect. ## Managing telemetry -## DO adhere to the SDK telemetry opt-out +### DO adhere to the SDK telemetry opt-out -The SDK has an [opt out](https://learn.microsoft.com/en-us/dotnet/core/tools/telemetry#how-to-opt-out) mechanism for telemetry that all SDK-generated +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