Generate custom usage reports for Amazon WorkSpaces

Amazon WorkSpaces provides different options to monitor the service usage for your workload. These available metrics offer different ways to monitor your WorkSpaces connections. These metrics are all emitted at the service level, so granular in-session metrics are not available. With WorkSpaces Streaming Protocol (WSP) adopting NICE DCV as its desktop streaming mechanism, customers unlock an array of session metrics provided by DCV. Customers leverage these DCV metrics to build custom WSP WorkSpaces in-session usage reports. These reports provide the same reporting for any WorkSpaces client the user is accessing with.

In this blog, you deploy a PowerShell script to generate granular WSP usage reports for Windows users. The report is invoked by Windows Task Scheduler on a schedule. The report generated by the script is a daily CSV file that tracks each user WSP session with exact times the user connects and disconnects. The script calculates the total time of each session so administrators have visibility into how long and when the user was connected. The walkthrough of this blog will illustrate how to deploy the reporting on a single WorkSpace. For details on how to build onto the report and how to apply it throughout your environment, see the Conclusion section.

Prerequisites

To follow this blog, you need to have a deployed WSP WorkSpace running a Windows-based operating system. On this WorkSpace, you will need to have administrator rights to the operating system. These administrator rights are delegated through Active Directory or the WorkSpaces service.

Walkthrough

Step 1: Deploy your usage reports PowerShell script

In this step, you create a PowerShell script that is invoked to generate the usage reports locally on the WorkSpace.

1. Retrieve the Build-WSPUsageReports.ps1 script from the DCV Samples Github repository within the AWS Samples.
2. Connect to your WSP WorkSpace with any WorkSpaces client.
   • If you are not the owner of the WorkSpace, you need to have administrator rights in Active Directory and connect via RDP. If you are the owner, you need administrator rights delegated through Active Directory or the WorkSpaces service.
3. Within File Explorer, navigate to C:\ProgramData\Amazon\WSP\. Create a new folder called UsageReports.
   • Note that the folder paths used for this walkthrough can be changed to a different location.
4. Save the Build-WSPUsageReports.ps1 script file into this folder location.

Step 2: Create your scheduled task to invoke the usage reports

In this step, you will create a local scheduled task to routinely invoke the script. For this walkthrough, the task is created locally on a single machine. See the Conclusion section on how to scale this to your entire WorkSpaces environment.

1. On the WSP WorkSpace, open Task Scheduler. This is found within the Windows Administrative Tools folder on the Start Menu.
2. Within the Task Scheduler Library window, select Create Task….
3. In the Name field, name your task WSPUsageReports.
4. Select the Change User or Group… button.
5. Within the search window, input SYSTEM and select Check Names. The name becomes underlined when it is found and then select OK.
6. Toggle the Run with highest privileges checkbox.
7. On the Configure for: dropdown, select the operating system that is supported by your WorkSpace. For example, if you are running Windows Server 2019, select that from the dropdown.
8. Select the Triggers tab and then select New….
9. The task trigger will default to On a schedule. Select the Repeat task every: dropdown and choose 5 minutes. Optionally, by selecting the highlighted 5 minutes text, you may change to 1 minutes so the task is invoked every minute.
10. On the for a duration of: dropdown, select Indefinitely.
11. Select OK on the New Trigger window.
12. Select the Actions tab and select New….
13. Ensure the Action: dropdown is set to Start a program.
14. On the Program/script text box, enter powershell. Within the Add arguments (optional): text box, enter the following:
    • -noprofile -ExecutionPolicy Unrestricted -file "C:\ProgramData\Amazon\WSP\UsageReports\Build-WSPUsageReports.ps1" -usageReportsFolder "C:\ProgramData\Amazon\WSP\UsageReports"
    • Note that the -usageReportsFolder can be modified to a different reporting storage location.
15. On the WSPUsageReports Properties window, select OK.

Step 3: Test your usage reporting

In this step, you validate that your reporting task is being invoked properly. To test the functionality, you will login and logout to generate session inputs to the reporting. If you do not see the reports generating, Task Scheduler will provide an error code when it fails. Running the script manually in PowerShell is an additional troubleshooting step.

1. Navigate to your Usage Reports folder that you configured in Step 1. Within the folder, there is a CSV file with the current date (mm-dd-yyyy). Open this file to see the reporting on your current session. The script will record five different entries: Hostname, LogonTime, LogoffTime, User, SessionTime. LogoffTime is blank and SessionTime will record as 00:00:00 as the session is still active.
   • Note, if you do not see the report, the scheduled task has not been invoked yet. The time of its next invocation can be found in the Task Scheduler Library window. Alternatively, you can manually invoke the task by alternative-selecting the task and then Run.
2. Disconnect from your session. For information on how to disconnect your client, see your client page’s Disconnect section.
3. After a couple minutes, reconnect to your WSP session. This will simulate the reporting for a user disconnecting to get a cup of coffee.
4. Within your CSV report, the LogoffTime and SessionTime has been appended to the report. The next connection is recorded since you have reconnected. SessionTime is recorded as hours-minutes-seconds. Note that all times recorded are in UTC.

Cleanup

By following this blog, you did not incur any additional costs. The reporting mechanism does use a small amount of disk space on the WorkSpace. To cleanup your WorkSpace, delete the scheduled task and the UsageReports folder.

Conclusion

In this walkthrough, you utilized DCV metrics on a WSP WorkSpace to generate a custom usage report. The provided script can act as a foundation to build additional reporting within the report. For instance, you can capture the applications the user opens or lock screen events, since a locked screen does not disconnect the session. All of the interactions to create the report rely on DCV and the Windows operating system.

The reporting you implemented during this walkthrough was on a single WorkSpace. If you plan to apply this reporting to all of your WorkSpaces, you may enforce the reporting via GPOs. The two GPOs you will need to apply are:

1. Distribute the reporting script to all of the WorkSpaces within the Organizational Unit you configure the GPO for.
2. Create the scheduled task you manually created in Step 2 via GPO.
   • Note, when enforcing via GPO you will not have a GUI option to modify the trigger to 1 minute. This can be done by modifying the Policy within your Active Directories SYSVOL.
   • For an example procedure on creating scheduled tasks through GPO, refer to the Dynamically set NICE DCV session permissions at Windows logon blog post.

With the walkthrough, the usage reports are stored locally on the WorkSpace. In a production scenario, it is simpler to handle the reports if they are consolidated to a single location, like a network file share. Once consolidated, the reports can be ingested into a log analysis platform. For example, the logs can be ingested into Amazon QuickSight to get a visual representation of the log results. If you have questions or requests for the provided script, you can open issues on the dcv-samples Github repository.

Andrew came to AWS in 2019 from a large datacenter environment where he specialized in VMware, Cisco UCS, and automation. Through his time at AWS, he developed a passion for visualization workloads. In 2022, he started his current role as a Sr. Developer Advocate for DCV.