Skip to content

Commit a38eb5e

Browse files
machvmachv
authored
Merge pull request #392 from microsoft/dev
Auto-Start option for Deploy script
2 parents 4bdb7b1 + 47aa699 commit a38eb5e

File tree

5 files changed

+198
-79
lines changed

5 files changed

+198
-79
lines changed

‎Docs/wslab-telemetry.md‎

Lines changed: 120 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,31 @@
22

33
## Introduction
44

5-
We started to collect telemetry to better understand impact of WSLab scripts as currently we cannot determine number of VMs deployed and where is WSLab being used. Data are hosted in Azure Application Insights and it is absolutely transparent what information is being collected, since all is visible in PowerShell Scripts.
5+
WSLab introduced opt-in telemetry collection to better understand impact of WSLab scripts as currently we cannot determine number of VMs deployed or where is WSLab being used. Data sent from scripts are hosted in Azure Application Insights service and it is absolutely transparent what information is being collected, since all code is visible in PowerShell Scripts on Github repository.
66

7-
Currently there is no public facing interface, however we plan to create PowerBI dashboards, where we will present Leader Boards and some nice statistics - such as how many VMs were deployed and we will be able to create statistics that will show in what countries is WSLab running and many more
7+
Currently there is no public facing interface to read collected information, however in the future plan is to create a public Power BI dashboard, where we will present Leader Boards and usage statistics - such as how many VMs were deployed and we will be able to create statistics that will show in what countries is WSLab running etc.
8+
9+
We are not collecting any PII, whole purpose of this telemetry is to get overall usage statistics of WSLab.
810

911
## Verbosity level
1012

11-
Currently there are 3 different levels: **None**, **Basic** and **Full**. If nothing is configured in LabConfig, you will be asked to provide your preferred option.
13+
Currently there are 3 different verbosity levels for telemetry: **None**, **Basic** and **Full**. If nothing is configured in LabConfig, you will be asked to provide your preferred option. If you would like to skip this interactive prompt completely, configure desired telemetry level in your LabConfig file on per lab basis. You can also configure telemetry behaviour globally using environment variable `WSLAB_TELEMETRY_LEVEL` set to one of three options. If you configure both, LabConfig and Environment variable, LabConfig value take precedence.
1214

1315
### None
1416

15-
If you don't want to send anything, or if you are in offline environment.
17+
If you don't want to send anything, or if you are in an offline environment.
1618

1719
### Basic
1820

1921
Sends information about deployed lab, that is vital for us to understand impact of WSLab scripts.
2022

2123
### Full
2224

23-
Provides enhanced information such as computer model, amount of RAM and number of cores. This information is not essential, however i will provide interesting insight.
25+
Provides enhanced information such as amount of RAM and number of CPU cores of host environment. This information is not essential, however it will provide interesting insight to correlate script performance.
26+
27+
## Tag
28+
29+
If you would like to participate in leaderboard and show how many lab VMs you've deployed, you can also include `TelemetryNickname` variable in LabConfig configuration and this value would be then appended to every telemetry event sent.
2430

2531
## LabConfig examples
2632

@@ -57,65 +63,128 @@ $LabConfig = @{
5763
5864
```
5965

66+
## Telemetry Events
67+
68+
If WSLab telemetry is enabled, multiple events are sent. All events are listed in the table below. In general when script is started `.Start` type of event is sent and after script sucessfully finished respective `.End` event is sent. Two separate events are used to measure success rate of the scripts.
69+
70+
| Event | Script | Description |
71+
|---------------------------|---------------------------|-------------|
72+
| `Prereq.Start` | `1_Prereq.ps1` | When script it started. |
73+
| `Prereq.End` | `1_Prereq.ps1` | When all prerequisities are downloaded. |
74+
| `CreateParentDisks.Start` | `2_CreateParentDisks.ps1` | When script it started. |
75+
| `CreateParentDisks.Vhd` | `2_CreateParentDisks.ps1` | One event per each parent disk. Includes information how long the disk took to hydrate. |
76+
| `CreateParentDisks.End` | `2_CreateParentDisks.ps1` | When all parent disks are created. |
77+
| `Deploy.Start` | `3_Deploy.ps1` | When script it started. |
78+
| `Deploy.VM` | `3_Deploy.ps1` | One event per each provisioned lab VM. Includes information about that VM. |
79+
| `Deploy.End` | `3_Deploy.ps1` | When lab has been deployed. Includes details about lab (e. g. incremental or new deploy). |
80+
| `Cleanup` | `Cleanup.ps1` | When lab has been deprovisioned. Includes count of actually removed VMs. |
81+
6082
## Collected information
6183

62-
These properties are attached to every telemetry event that is sent to the Application Insights workspace.
63-
64-
| | Basic | Full |Description| Sample Value | Application Insights property |
65-
|---------------------|:-----:|:----:|-----------| --- | ---- |
66-
| Application Version | x | x | Version of WSLab Scripts | v20.07.1 | `ai.application.ver` |
67-
| Telemetry Level | x | x | Which level of telemetry has been set | Full | `telemetry.level` |
68-
| Product type | x | x | Workstation or Server| Workstation | `os.type` |
69-
| Session ID | x | x | One-way hash (`SHA1`) of `MachineGUID`, `PSScriptRoot` and `ComputerName`. Purpose of this session ID is only to link execution of separate scripts within the same lab folder. | 482e33a99e6fb41e5f739d9294ac1b339c7c3c60 | `ai.session.id` |
70-
| Device Locale | x | x | Locale of Host OS | en-US | `ai.device.locale` |
71-
| PowerShell Edition | x | x | Desktop or Core | Core | `powershell.edition` |
72-
| PowerShell Version | x | x | version | 7.0.2 | `powershell.version` |
73-
| TotalDuration | x | x | Duration of script run in seconds | 23,62 | `TotalDuration` |
74-
| Device Manufacturer | | x | Device Manufacturer | LENOVO | `ai.device.oemName` |
75-
| Device model | | x | Device model based on `Win32_ComputerSystem` | ThinkPad P52 | `ai.device.model` |
76-
| Operating System | | x | OS SKU and build | Windows 10 Enterprise (10.0.19041.388)| `ai.device.os` |
77-
| OS Build | | x | OS Build Number | 19041 | `os.build` |
78-
| Amount of RAM | | x | Total amount of RAM in MB | 65311 | `memory.total` |
79-
| Number of Sockets | | x | How many sockets system have | 1 | `cpu.sockets.count` |
80-
| Number of Cores | | x | Total number of CPU cores available | 12 | `cpu.logical.count` |
81-
| Volume Capacity | | x | Capacity of a volume where WSLab was run (in GB) | 954 | `volume.size` |
82-
| Disk Model | | x | Friendly name of a disk where volume with WSLab was run | Samsung SSD 970 PRO 1TB | `disk.model` |
83-
| Disk Media Type | | x | Type of the disk where WSLab was run | SSD | `disk.type` |
84-
| Disk Bus type | | x | Bus connection of the disk where WSLab was run | NVMe | `disk.busType` |
85-
86-
### Specific Events for 2_CreateParentDisks.ps1 script
87-
88-
#### CreateParentDisks.Start
89-
When script is started.
84+
These properties are sent with every telemetry event to the Application Insights workspace.
85+
86+
| | Basic | Full |Description| Sample Value | Application Insights property |
87+
|--------------------------|:-----:|:----:|-----------| --- | ---- |
88+
| Application Version | x | x | Version of WSLab Scripts | v20.07.1 | `ai.application.ver` |
89+
| Script name | x | x | Name of the executed script | Deploy.ps1 | `i.cloud.role` |
90+
| Telemetry Level | x | x | Which level of telemetry has been set | Full | `telemetry.level` |
91+
| Product type | x | x | Workstation or Server| Workstation | `os.type` |
92+
| Session ID | x | x | One-way hash (`SHA1`) of `MachineGUID`, `PSScriptRoot` and `ComputerName`. Purpose of this ID is only to sync execution of separate WSLab scripts to the same lab instance. | 482e33a99e6fb41e5f739d9294ac1b339c7c3c60 | `ai.session.id` |
93+
| User ID | x | x | One-way hash (`SHA1`) of `MachineGUID`. This provide option to differentiate multiple lab instances between multiple machines. | 0f3e4472845a50445883666b6f9efe55982bc1d0 | `ai.user.id` |
94+
| Device ID | x | x | Same value as User ID. | 0f3e4472845a50445883666b6f9efe55982bc1d0 | `ai.device.id` |
95+
| Device Type | x | x | PC System Type | Laptop | `ai.device.type` |
96+
| PowerShell Edition | x | x | Desktop or Core | Core | `powershell.edition` |
97+
| PowerShell Version | x | x | version | 7.0.2 | `powershell.version` |
98+
| TotalDuration | x | x | Duration of script run in seconds | 23,62 | `script.duration` |
99+
| OS Build | x | x | OS Build Number | 19041 | `os.build` |
100+
| Device Locale | | x | Locale of Host OS | en-US | `device.locale` |
101+
| Operating System Name | | x | OS SKU and build | Windows 10 Enterprise (10.0.19041.388 | `ai.device.os` |
102+
| Operating System Version | | x | OS Build with patch level | 10.0.19041.388 | `ai.device.osVersion` |
103+
| Amount of RAM | | x | Total amount of RAM in MB of host OS. | 65311 | `memory.total` |
104+
| CPU Model | | x | What CPU model is used to execute WSLab. | Intel(R) Core(TM) i7-8850H CPU @ 2.60GHz | `cpu.sockets.count` |
105+
| Number of Sockets | | x | How many sockets system have. | 1 | `cpu.sockets.count` |
106+
| Number of Cores | | x | Total number of CPU cores available. | 12 | `cpu.logical.count` |
107+
| Volume Capacity | | x | Capacity of a volume where WSLab was run (in GB). | 954 | `volume.size` |
108+
| Volume File system | | x | What file system is on a volume where WSLab was executed. | ReFS | `volume.size` |
109+
| Disk Media Type | | x | Type of the disk where WSLab was run. | SSD | `disk.type` |
110+
| Disk Bus type | | x | Bus connection of the disk where WSLab was run. | NVMe | `disk.busType` |
111+
112+
### Event-specific information
113+
114+
In addition to general properties in the table above, these events include additional information to the telemetry event.
115+
90116
#### CreateParentDisks.Vhd
91-
For each hydrated VHD parent disk.
117+
118+
This event is sent for every newly created VHD file. If any of the VHD files in WSLab folder already exists, it would be skipped.
119+
120+
| | Basic | Full | Description | Sample Value | Application Insights property |
121+
| --------------------------- |:-----:|:----:| ----------- | ------------ | ----------------------------- |
122+
| VHD hydration duration | x | x | How many seconds took to create specific VHD file. | 95,5 | `vhd.duration` |
123+
| VHD name | x | x | Well-known name of the generated VHD file based on the dictionary in WSLab scripts. | Win2019Core_G2.vhdx | `vhd.name` |
124+
| VHD kind | x | x | Type of VHD (Tools disk, Server Core or Full Desktop Experience). | Core | `vhd.kind` |
125+
| Guest OS Build number | x | x | Build number of OS in the generated VHD File. | 17763 | `vhd.os.build` |
126+
| Guest OS Language | | x | Language code of the OS in the generated VHD file. | en-US | `vhd.os.language` |
127+
128+
92129
#### CreateParentDisks.End
93-
When script finished.
94130

95-
### Specific Events to Deploy.ps1 script
131+
This event is sent after Create Parent Disks script finishes and contains summary information about the lab itself.
132+
133+
| | Basic | Full | Description | Sample Value | Application Insights property |
134+
| --------------------------- |:-----:|:----:| ----------- | ------------ | ----------------------------- |
135+
| Applied MSU count | x | x | How many Windows Update packages were applied to image. | 0 | `msu.count` |
136+
| DC Creation time | x | x | How many seconds took to prepare Domain Controller | 375,54 | `dc.duration` |
137+
| DC Already Exists | x | x | True if Domain Controller was already present | false | `dc.exists` |
138+
| DC Edition | x | x | Server Core or Full Desktop Experience as configured in LabConfig | 4 | `dc.edition` |
139+
| Build number of DC | x | x | | 17763 | `dc.build` |
140+
| OS Language of DC | x | x | | en-US | `dc.language` |
141+
| WSLab scripts renamed | x | x | True if user enabled to rename script after deployment | true | `lab.scriptsRenamed` |
142+
| Install SCVMM | x | x | True if SVMM installation was requested in LabConfig | false | `lab.installScvmm` |
143+
| Host OS installation Type | x | x | Server Core of Full Desktop Experience | Server Core | `os.installationType` |
144+
| Server Core VHD - Exists | x | x | True if VHD was already present, otherwise false. | false | `vhd.core.exists` |
145+
| Server Core VHD - Name | x | x | Well-known name of the generated VHD file based on the dictionary in WSLab scripts. | Win2019Core_G2.vhdx | `vhd.core.name` |
146+
| Server Core VHD - Duration | x | x | How many seconds took to create specific VHD file. | 95.5 | `vhd.core.duration` |
147+
| Server Desktop Experience VHD - Exists | x | x | True if VHD was already present, otherwise false. | false | `vhd.full.exists` |
148+
| Server Desktop Experience VHD - Name | x | x | Well-known name of the generated VHD file based on the dictionary in WSLab scripts. | Win2019_G2.vhdx | `vhd.full.name` |
149+
| Server Desktop Experience VHD - Duration | x | x | How many seconds took to create specific VHD file. | 195.5 | `vhd.full.duration` |
150+
| Tools VHD - Exists | x | x | True if VHD was already present, otherwise false. | false | `vhd.tools.exists` |
151+
| Tools VHD - Name | x | x | Well-known name of the generated VHD file based on the dictionary in WSLab scripts. | Tools.vhdx | `vhd.tools.name` |
152+
| Tools VHD - Duration | x | x | How many seconds took to create specific VHD file. | 25.5 | `vhd.tools.duration` |
96153

97-
#### Deploy.Start
98-
When script is started.
99154

100155
#### Deploy.VM
101-
For each provisioned VM.
156+
157+
This event is sent for every provisioned lab VM.
158+
159+
| | Basic | Full | Description | Sample Value | Application Insights property |
160+
| ---------------------------------- |:-----:|:----:| ----------- | ------------ | ----------------------------- |
161+
| VM Configuration type in LabConfig | x | x | What configuration mode is used in LabConfig | S2D | `vm.configuration` |
162+
| VM Unattend type in LabConfig | x | x | What type of domain join is used for the VM in LabConfig | DjoinBlob | `vm.os.installationType` |
163+
| Installation type of OS VM | x | x | What installation type is this VM (Server Core or Desktop Experience) | Server Core | `vm.os.editionId` |
164+
| Edition ID of VM | x | x | What OS Edition | ServerDatacenter | `vm.os.version` |
165+
| VM Provisioning time | x | x | How much time was needed to create a VM instance | 34,7 | `vm.deploymentDuration` |
166+
102167

103168
#### Deploy.End
104-
When script finished.
105169

106-
| |Basic|Full|Description|
107-
|-----------------------------|:---:|:--:|-----------|
108-
|VMDeploymentDuration |x |x |Duration of Deploy.ps1 script|
109-
|Deployed VM OSBuild |x |x |For example 19041|
110-
|Deployed VM InstallationType |x |x |For example Server Core|
111-
|Deployed VM OsVersion |x |x |For example 10.0.17763.1282|
112-
|Deployed VM EditionID |x |x |For example ServerDatacenter|
170+
This event is sent when lab deploment is complete. Provide overall information about the lab instance.
171+
172+
| | Basic | Full | Description | Sample Value | Application Insights property |
173+
| --------------------- |:-----:|:----:| ----------------------------------- | ------------ | ----------------------------- |
174+
| Total VM count | x | x | Total number of VMs in lab. | 8 | `lab.vmsCount.active` |
175+
| New VM count | x | x | How many virtual machines were created by script instance. | 5 | `lab.vmsCount.provisioned` |
176+
| Lab Internet mode | x | x | True if internet is enabled in LabConfig. | true | `lab.internet` |
177+
| Is Incremental deploy | x | x | True if Deploy script was run before and is only adding additional VMs to existing lab. | true | `lab.isncrementalDeployment` |
178+
| Lab Auto Start mode | x | x | What auto-start mode is enabled for the lab. | 2 | `lab.autostartmode` |
179+
180+
181+
#### Cleanup
113182

114-
### Specific to Cleanup.ps1
183+
This event is sent when Cleanup script removes lab virtual machines and contain number of affected virtual machines.
115184

116-
| |Basic|Full|Description|
117-
|-----------|:---:|:--:|-----------|
118-
| lab.removed.count |x |x |Number of removed VMs|
185+
| | Basic | Full | Description | Sample Value | Application Insights property |
186+
| ----------------- |:-----:|:----:| ----------------------------------- | ------------ | ----------------------------- |
187+
| Removed VMs count | x | x | How many VMs were actually removed. | 8 | `lab.removed.count` |
119188

120189

121190

0 commit comments

Comments
 (0)