Skip to content

Commit 8bb749b

Browse files
SydneyhSmithSydneyhSmith
authored
Add files via upload
1 parent 7ba80b9 commit 8bb749b

File tree

1 file changed

+170
-0
lines changed

1 file changed

+170
-0
lines changed

‎1-Draft/RFCNNNN-AdditionalTelemetry.md

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
RFC: RFC
3+
Author: Sydney Smith
4+
Status: Draft
5+
SupercededBy: N/A
6+
Version: 1.0
7+
Area: Telemetry
8+
Comments Due: 3/29/19
9+
Plan to implement: <Yes | No>
10+
---
11+
12+
# Additional Telemetry in PowerShell
13+
14+
Add usage telemetry across PSEdition, Platform, Application, session type and command types.
15+
Improve the opt-out mechanisms for PowerShell telemetry.Provide community access to aggregated
16+
statistics.
17+
18+
## Motivation
19+
20+
To make the best possible investments in PowerShell we need answers backed by data to the following questions:
21+
22+
- Is PowerShell Core usage growing (in terms of number of starts)?
23+
- Is the PowerShell Core user-base growing (both in terms of number of users and devices)?
24+
- How is PowerShell being used? What is the usage distribution across command types and session type?
25+
- What are impediments to PowerShell Core usage growth?
26+
- What are issues that customers are hitting in PowerShell Core?
27+
- What versions of PowerShell tools and services should Microsoft continue to support?
28+
- What PowerShell integration scenarios are people using? How many people are using PowerShell
29+
Editor services
30+
- How can we optimize the engine size and efficiency of PowerShell for cloud scenarios?
31+
32+
To ensure we are getting an accurate picture of how everyone uses PowerShell, not just those most
33+
vocal/involved in the community, we need to make improvements in our telemetry.
34+
PowerShell usage telemetry will allow us to better prioritize testing, support, and investments.
35+
It should be straightforward and easy to opt-out of PowerShell telemetry (presently the process is
36+
not intuitive nor well documented).
37+
To better share our plans and successes with the community we want more complete telemetry on our
38+
[Public PowerBi report](https://msit.powerbi.com/view?r=eyJrIjoiYTYyN2U3ODgtMjBlMi00MGM1LWI0ZjctMmQ3MzE2ZDNkMzIyIiwidCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsImMiOjV9&pageName=ReportSection5).
39+
Simply put, we want to make PowerShell better and believe this can be achieved by better
40+
understanding how PowerShell is being used.
41+
42+
### Non-Goals
43+
44+
The goal of this is **not** to collect any personal data of PowerShell users or infringe on
45+
users' privacy.
46+
Respecting the privacy of our users has been the principal factor in determining which metrics we
47+
plan to collect.
48+
The goal of this is not to collect patterns of individual users but to look at aggregate usage trends.
49+
50+
## Specification
51+
52+
Add telemetry to track the following metrics:
53+
54+
- Count of unique devices (PowerShell)
55+
- Count of unique users (PowerShell)
56+
- Count of execution types (ex. cmdlets, native binaries/applications) (PowerShell)
57+
- Count of session types (ex. hosted vs not hosted sessions) (PowerShell)
58+
- Hosting application of the of the PowerShell session (ex. VSCode, ISE, AZDevOps) (PowerShell)
59+
- Version of PowerShell, PowerShellGet, PackageManagement, Nuget and platform
60+
used to install from PSGallery (PowerShellGet)
61+
62+
### Other features
63+
64+
- Public PowerBi DashBoard to make the aggregated statistics available to the community.
65+
Find a mocked-up PowerBi DashBoard with randomly generated data at the end of the document.
66+
It includes the following reports:
67+
- Unique user trends
68+
- Unique devices trends
69+
- Types of user &mdash;based on types of executions taking place
70+
- VSCode usage trends
71+
- Application trends
72+
- Hosted Scenario Trends
73+
- PowerShellGet installation trends
74+
- A cmdlet for providing feedback (Send-PSFeedback):
75+
- This cmdlet would take in a string and send it back to the PowerShell team
76+
- The cmdlet will also send Platform data (OS/version) and Shell data ($PSVersionTable)
77+
- The cmdlet will have an -OpenGitHubIssue switch that will allow the user to open a GitHubIssue
78+
in the PowerShell/PowerShell repository
79+
- The user will have the option to include the the last error using an -IncludeError switch
80+
- If the command is not successful (ex. there is no Web Connection) the cmdlet will return a
81+
warning and alternative instructions for support through GitHub
82+
- If no location switch is used the cmdlet will default send the feedback to the PowerShell
83+
User Voice
84+
- Based on usage of this cmdlet there would potential for additional parameters
85+
- Disabling, and re-enabling telemetry will be available through a new cmdlet (Set-PSTelemetry):
86+
- The cmdlet will stop all collection of telemetry for the remainder of that session and stop
87+
telemetry from being collected on subsequent starts
88+
- The user can request their telemetry is deleted by using a Remove-PSTelemetry cmdlet
89+
- In order to have their telemetry deleted the user will be required to provide their System GUID
90+
and User GUID
91+
- If the cmdlet is unable to send the information the cmdlet will return a warning and alternative
92+
instructions for support through GitHub. It will be specified that GUIDs are unique identifiers
93+
and should not be shared publicly on GitHub.
94+
- There will be three options for the telemetry environment variable which can all be set manually
95+
or using the Set-PSTelemetry cmdlet
96+
- $True indicates all telemetry will be collected
97+
- $False indicates no telemetry will be collected
98+
- $NonIdentifying indicates that only non-identifying telemetry will be collected i.e. no GUIDs
99+
will be collected
100+
- The existing disabling mechanisms for PowerShell telemetry will remain including the ability to
101+
set the telemetry environment variable before the first start of PowerShell
102+
103+
### Future work
104+
105+
A public API for module authors and PowerShell hosted application owners to use the same
106+
infrastructure to collect telemetry for their module or application.
107+
Making the API public is a phase two goal of this project.
108+
We will make the telemetry publicly available once it is internally validated.
109+
Microsoft will not collect, store, or manage any data externally gathered through this API.
110+
111+
## Design
112+
113+
### PowerShell Changes
114+
115+
- Count of unique devices will be based on a System GUID generated on the first start-up
116+
- Count of unique users will be based on a User GUID generated at PowerShell start time and stored
117+
in the user's configuration directory
118+
- The combination of the User GUID and System GUID will be used to determine counts of unique
119+
users and unique devices
120+
- The Application ID will be used to disambiguate PowerShell Hosted applications. It will be a
121+
standardized method for applications to identify themselves in our telemetry. It will be up to
122+
Application owners to tag their usage for inclusion in our counts.
123+
- The count execution type will be collected throughout the PowerShell session
124+
- The type of PowerShell session (hosted vs non-hosted) will be collected at PowerShell
125+
engine start time
126+
- An example of what would be collected on PowerShell Start up:
127+
- System GUID: b45d67e8-8c51-4ea3-a170-0a3cedb697ed
128+
- User GUID: c58030d3-1a91-4086-9cb1-5bddd342056d
129+
- The ApplicationID: VSCode
130+
- The Platform being used: Windows 10 Pro
131+
- The Version of PowerShell: 6.2.0-preview.4
132+
- The type of PS session: Hosted
133+
- An example of what might be collected during a PowerShell Session:
134+
- Count of cmdlets and functions: 10
135+
- Count of native binaries/applications: 5
136+
- Currently telemetry is collected at the console startup but we would move collection as close to
137+
the PowerShell engine start time as possible in order to capture hosted PowerShell scenarios in
138+
the telemetry
139+
- Telemetry will be collected through Azure Application Insights and will be stored using Azure
140+
Storage Tables
141+
142+
### PowerShellGet Changes
143+
144+
Create a header when packages are installed from the PowerShell Gallery,
145+
to collect/send the following information:
146+
147+
- Version of PowerShellGet, PackageManagement, and NugetProvider
148+
- Version and Edition of PowerShell
149+
- Identifier for Operating System
150+
151+
- An example of what would be collected at Package Installation:
152+
- The Version of PowerShellGet: 2.0.3
153+
- The Version of PackageManagement: 1.2.4
154+
- The NugetProvider: 3.0.0.1
155+
- The version of PowerShell: Core 6.2
156+
- The platform being used: macOS 10.3
157+
158+
## Mock PowerBi Report
159+
![PowerBi]('\Fake PowerBi.pdf')
160+
161+
## Alternate Proposals and Considerations
162+
163+
Privacy concerns including GDPR regulations are a major consideration of this RFC.
164+
We underwent a privacy review before drafting this RFC to ensure that we are respecting
165+
the privacy of all users. The System GUID will be stored in $PSHome so that the user
166+
can provide it and have their data deleted at anytime.
167+
Performance impact is also a major consideration of these changes, and the metrics chosen are
168+
designed to have as nominal an impact on end user experience as possible.
169+
170+
[Microsoft Privacy Policy](https://privacy.microsoft.com/en-US/privacystatement)

0 commit comments

Comments
 (0)