Citrix Scout
Introduction
Citrix Scout collects diagnostics and runs health checks. You can use the results to maintain your Citrix Virtual Apps and Desktops deployment. Citrix offers comprehensive, automated analysis of diagnostics collections through Citrix Insight Services. You can also use Scout to troubleshoot issues, on your own or with Citrix Support guidance.
You can upload collection files to Citrix for analysis and guidance from Citrix Support. Or, you can save a collection locally for your own review, and then later upload the collection file to Citrix for analysis.
Scout offers the following procedures:
- Collect: Runs a one-time diagnostics collection on machines that you select in a site. You can then either upload the file to Citrix or save it locally.
- Trace & Reproduce: Starts a manual trace on the machines that you select. Then you re-create issues on those machines. After re-creating the issue, the trace is stopped. Scout then collects other diagnostics and uploads the file to Citrix, or saves the file locally.
- Schedule: Schedules diagnostics collections to occur daily or weekly at a specified time on the machines you select. The file is automatically uploaded to Citrix.
- Health Check: Runs checks that gauge the health and availability of the site and its components. You can run health checks for Delivery Controllers, Virtual Delivery Agents (VDAs), StoreFront servers, and Citrix License Servers. If issues are found during the checks, Scout provides a detailed report. Each time Scout starts, it checks for updated health check scripts. If new versions are available, Scout downloads them automatically, for use the next time health checks are run.
Note:
The Trace & Reproduce, Schedule, and Health Check procedures are currently not available for Linux VDA.
The graphical interface described in this article is the primary way to use Scout. Alternatively, you can use PowerShell to configure one-time or scheduled diagnostic collections and uploads. See Call Home.
Where to run Scout:
- In an on-premises deployment, run Scout from a Delivery Controller to capture diagnostics or run checks on one or more Virtual Delivery Agents (VDAs), Delivery Controllers, StoreFront servers, and License Servers. You can also run Scout from a VDA to collect local diagnostics.
- In a Citrix Cloud environment that uses Citrix DaaS (formerly Citrix Virtual Apps and Desktops service), run Scout from a VDA to collect local diagnostics.
The log for the Scout application is stored in C:\ProgramData\Citrix\TelemetryService\ScoutUI.log
. This file can be used for troubleshooting.
What is collected
The diagnostics collected by Scout include Citrix Diagnostic Facility (CDF) trace log files. A subset of CDF traces called Always-on Tracing (AOT) is also included. AOT information can be helpful when troubleshooting common issues such as VDA registrations and application/desktop launches. No other Event Tracing for Windows (ETW) information is collected.
The collection includes:
- Registry entries created by Citrix Virtual Apps and Desktops under
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix
. - Windows Management Instrumentation (WMI) information under the Citrix namespace.
- Processes that are running.
- Crash dumps of Citrix processes that are stored in %PROGRAMDATA%\Citrix\CDF.
- Citrix policy information, in CSV format.
- Installation and upgrade information. The collection can include the full product metainstaller log, failing MSI logs, output from the MSI log analyzer, StoreFront logs, Licensing compatibility check logs, and results from preliminary site upgrade tests.
About trace information:
- The trace information is compressed as it is collected, keeping a small footprint on the machine.
- On each machine, the Citrix Telemetry Service keeps compressed recent trace information for a maximum of eight days.
- Beginning with Citrix Virtual Apps and Desktops 7 1808, AOT traces are saved to the local disk by default. (In earlier versions, traces were held in memory.) Default path =
C:\Users\CitrixTelemetryService\AppData\Local\CitrixAOT
. - Beginning with Citrix Virtual Apps and Desktops 7 1811, AOT traces saved to network shares are collected with other diagnostics.
- You can modify the maximum size (default = 10 MB) and slice duration, using the
Enable-CitrixTrace
cmdlet or theHKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Telemetry DefaultListen
registry string. - Traces append to the file until the file reaches 10% of
MaxSize
.
For a list of the datapoints that Scout collects, see Call Home key datapoints.
Scout configuration
Scout can be configured to work on Linux VDAs. For more information on Linux VDA and telemetry, see Integrate with the Citrix Telemetry Service
The Linux VDA might automatically change the ctxtelemetry
socket port or the port for telemetry service. If so, you must configure the port manually.
- Navigate to C:\Program Files\Citrix\Telemetry Service
- Open the ScoutUI.exe.config file.
- Change the value for LinuxVDATelemetryServicePort or LinuxVDATelemetryWakeupPort to what was configured on the Linux VDA:
<add key="LinuxVDATelemetryServicePort" value="7502"/>
<add key="LinuxVDATelemetryWakeupPort" value="7503"/>
- Save the changes and close the file.
- Open Scout again to ensure it loads the latest configuration.
About health checks
Health check data is stored in folders under C:\ProgramData\Citrix\TelemetryService\
.
Site health checks
Site health checks are included in the Environment Test Service, which provides a comprehensive evaluation of the FlexCast Management Architecture (FMA) services. In addition to checking for service availability, these checks look for other health indicators such as database connections.
Site health checks run on Delivery Controllers. Depending on your site’s size, these checks can take up to an hour to complete.
Delivery Controller configuration checks
As part of the site health checks. Delivery Controller configuration checks verify whether the following issues exist, based on Citrix recommendations for Virtual Apps and Desktops sites:
- One or more Delivery Controllers are in a failed state.
- There is only one Delivery Controller in the site.
- Delivery Controllers are of different versions.
In addition to meeting the permissions and requirements for health checks, Delivery Controller configuration checks require:
- At least one Controller powered on.
- The Broker Service running on a Controller.
- A working connection from the Controller to the site database.
VDA health checks
VDA health checks identify possible causes for common VDA registration, session launch, and time zone redirection issues.
For registration on the VDA, Scout checks:
- VDA software installation
- VDA machine domain membership
- VDA communication port availability
- VDA service status
- Windows firewall configuration
- Communication with Controller
- Time sync with Controller
- VDA registration status
For session launches on VDAs, Scout checks:
- Session launch communication port availability
- Session launch services status
- Session launch Windows firewall configuration
- VDA Remote Desktop Services Client Access Licenses
- VDA application launch path
- Session launch registry settings
For time zone redirection on VDAs, Scout checks:
- Windows hotfix installation
- Citrix hotfix installation
- Microsoft group policy settings
- Citrix group policy settings
For Profile Management on VDAs, Scout checks:
- Hypervisor detection
- Provisioning detection
- Citrix Virtual Apps and Desktops
- Personal vDisk configuration
- User store
- Profile Management Service status detection
- Winlogon.exe hooking test
To run checks on Profile Management, you must install and enable Profile Management on the VDA. For more information on Profile Management configuration checks, see Knowledge Center article CTX132805.
StoreFront health checks
StoreFront checks verify:
- Citrix Default Domain service is running
- Citrix Credential Wallet service is running
- Connection from the StoreFront server to Active Directory port 88
- Connection from the StoreFront server to Active Directory port 389
- Base URL has a valid FQDN
- Correct IP address from the base URL can be retrieved
- IIS application pool is using .NET 4.0
- Whether the certificate is bound to the SSL port for the host URL
- Whether the certificate chain is complete
- Whether the certificates have expired
- Whether a certificate is expiring soon (within 30 days)
License Server checks
License Server checks verify:
- License Server connection from the Delivery Controller
- License Server firewall remote access status
- Citrix Licensing service status
- License Server License caching mode state
- License Server ports connection
- Whether the Citrix vendor daemon (CITRIX) is running
- Whether system clocks are synchronized
- Whether the Citrix Licensing service is running under the Local Service account
- Presence of the
CITRIX.opt
file - Customer Success Services eligibility date
- Citrix License Server Update
- Whether the License Server certificate is in the Delivery Controller’s trusted root store
In addition to meeting the permissions and requirements for health checks, the License Server must be joined to a domain. Otherwise, the License Server is not discovered.
Run health checks
The Health Check procedure comprises selecting machines, starting the checking, and then reviewing the results report.
- Launch Scout. From the machine’s Start menu, select Citrix > Citrix Scout. On the opening page, click Health Check.
-
Select machines. Click Find machine to discover machines. The Select machines page lists all the VDAs, Delivery Controllers, and License Servers discovered in the site. You can filter the display by machine name. Select the checkbox next to each machine that you want to collect diagnostics from, and then click Continue.
To add other component types (such as StoreFront servers and VDA machines), see Add machines manually and Import VDA machines. You cannot manually add Citrix Provisioning Servers or License Servers.
Scout automatically launches verification tests on each selected machine, making sure it meets the criteria listed in Verification tests. If verification fails, a message is posted in the Status column, and that machine’s checkbox is cleared. You can either:
- Resolve the issue and then select the machine’s checkbox again. This triggers a retry of the verification tests.
- Skip that machine (leave its checkbox unselected). Health checks are not run for that machine.
When the verification tests complete, click Continue.
-
Run the health checks on the selected machines. The summary lists the machines where the tests run (the machines you selected that passed the verification tests). Click Start Checking.
During and after checking:
- The Status column indicates the current checking state for a machine.
- To stop all in-progress checks, click Stop Checking in the lower right corner of the page. (You can’t cancel a single machine’s health check, only all selected machines. Information from machines that have completed the checks is kept.
- When the checks complete for all selected machines, the Stop Checking button in the lower right corner changes to Done.
- If a check fails, you can click Retry in the Action column.
- If a check completes with no issues found, the Action column is empty.
- If a check finds issues, click View Details to show the results.
- After the check completes for all selected machines, don’t click Back. (If you do, the check results are lost.)
- When the checks complete, click Done to return to the Scout opening page.
Heath check results
For report-generating Citrix checks, the reports contain:
- Time and date when the results report was generated
- Machines that were checked
- Conditions that the check looked for on the targeted machines
Permissions and requirements
Permissions:
-
To collect diagnostics:
- You must be a local administrator and domain user for each machine from which you’re collecting diagnostics.
- You must have permission to write to the LocalAppData directory on each machine.
-
To run health checks:
- You must be a member of the domain users group.
- You must be either a full administrator or have a custom role with read-only and Run Environment Tests permissions for the site.
- Set the script execution policy to at least
RemoteSigned
to allow the scripts to run. For example:Set-ExecutionPolicy RemoteSigned
. Note: other script execution privileges can work as well.
-
Use Run as administrator when launching Scout.
For each machine from which you collect diagnostics or run health checks:
- Scout must be able to communicate with the machine.
- File and printer sharing must be turned on.
- PSRemoting and WinRM must be enabled. The machine must also be running PowerShell 3.0 or later.
- The Citrix Telemetry Service must be running on the machine.
- Windows Management Infrastructure (WMI) access must be enabled on the machine.
- To set a schedule for diagnostic collection, the machine must be running a compatible Scout version.
Do not use the dollar sign ($) in user names specified in pathnames. It prevents the collection of diagnostic information.
Scout runs verification tests on the machines that you select, to make sure these requirements are met.
The Telemetry Service for Windows runs on Network Service.
The AOT Trace Folder is saved in C:\ProgramData\Citrix\TelemetryService\CitrixAOT
.
Only users in the Administrator group, System, and Telemetry Service SID have permission to access the HKEYLOCALMACHINE:SOFTWARE\Citrix\Telemetry
registry.
The Telemetry Service SID remains in the Performance Log Users group after uninstalling the Telemetry Service, but you can remove it manually.
Verification tests
Before a diagnostic collection or health check starts, verification tests run automatically for each selected machine. These tests make sure that the requirements are met. If a test fails for a machine, Scout displays a message with suggested corrective actions.
-
Scout cannot reach this machine - Ensure that:
- The machine is powered-on.
- The network connection is working properly. (This can include verifying that your firewall is properly configured.)
- File and printer sharing is turned on. See the Microsoft documentation for instructions.
-
Enable PSRemoting and WinRM - You can enable PowerShell remoting and WinRM at the same time. Using Run as administrator, run the
Enable-PSRemoting
cmdlet. For details, see the Microsoft help for the cmdlet. - Scout requires PowerShell 3.0 (minimum) - Install PowerShell 3.0 (or later) on the machine, and then enable PowerShell remoting.
- Unable to access LocalAppData directory on this machine - Ensure that the account has permission to write to the LocalAppData directory on the machine.
- Cannot locate Citrix Telemetry Service - Ensure that the Citrix Telemetry Service is installed and started on the machine.
- Cannot get schedule - Upgrade the machine to (minimum) XenApp and XenDesktop 7.14.
- WMI is not running on the machine - Ensure that Windows Management Instrumentation (WMI) access is enabled.
- WMI connections blocked - Enable WMI in the Windows Firewall service.
- Newer version of Citrix Telemetry Service required - (Version is checked only for Collect and Trace & Reproduce.) Upgrade the Telemetry Service version on the machine (see Install and upgrade). If you do not upgrade the service, that machine is not included in the Collect or Trace & Reproduce actions.
-
Scout cannot connect to the systemd socket on this machine - Ensure that:
- Port 7503 is open. Verify that the
systemd ctxtelemetry.socket
is listening on port 7503 on the machine. The port might be different if thectxtelemetry.socket
port has been changed. See Scout configuration to adjust ports. - The network connection is working properly. (This might include verifying that your firewall is properly configured.)
- Port 7503 is open. Verify that the
-
The Linux VDA Telemetry Service is not started on this machine - Ensure that:
- Port 7502 is open. Verify that the Linux VDA Telemetry Service is installed and started on the machine. The port might be different if the telemetry service port has been changed. See Scout configuration to adjust ports.
- The network connection is working properly. (This might include verifying that your firewall is properly configured.)
Version compatibility
This version of Scout (3.x) is intended to be run on Citrix Virtual Apps and Desktops (or minimum XenApp and XenDesktop 7.14) Controllers and VDAs.
An earlier version of Scout is provided with XenApp and XenDesktop versions earlier than 7.14. For information about that earlier version, see CTX130147.
If you upgrade a Controller or VDA earlier than 7.14 to version 7.14 (or a later supported version), the earlier version of Scout is replaced with the current version.
Feature | Scout 2.23 | Scout 3.0 |
---|---|---|
Support Citrix Virtual Apps and Desktops (plus XenApp and XenDesktop 7.14 through 7.18) | Yes | Yes |
Support XenDesktop 5.x, 7.1–7.13 | Yes | No |
Support XenApp 6.x, 7.5 to 7.13 | Yes | No |
Delivered with product | 7.1–7.13 | Beginning with 7.14 |
Can be downloaded from CTX article | Yes | No |
Capture CDF traces | Yes | Yes |
Capture Always-on-Traces (AOT) | No | Yes |
Allow collection of diagnostic data | Up to 10 machines at once (by default) | Unlimited (subject to resource availability) |
Allow diagnostic data to be sent to Citrix | Yes | Yes |
Allow diagnostic data to be saved locally | Yes | Yes |
Support Citrix Cloud credentials | No | Yes |
Support Citrix credentials | Yes | Yes |
Support proxy server for uploads | Yes | Yes |
Adjust schedules | N/A | Yes |
Script support | Command line (local Controller only) | PowerShell using Call Home cmdlets (any machine with the Telemetry Service installed) |
Health checks | No | Yes |
Data Masking | No | Beginning with 3.17 |
Install and upgrade
By default, Scout is installed or upgraded automatically as part of the Citrix Telemetry Service when you install or upgrade a VDA or a Controller.
If you omit the Citrix Telemetry Service when you install a VDA, or remove the service later, run TelemetryServiceInstaller_xx.msi
from the x64\Virtual Desktop Components
or x86\Virtual Desktop Components
folder on the Citrix Virtual Apps and Desktops installation media.
When you select the Collect or Trace & Reproduce action, you’re notified if a machine is running an older version of the Citrix Telemetry Service. Citrix recommends using the latest supported version. If you don’t upgrade the Telemetry Service on that machine, it is not included in the Collect or Trace & Reproduce actions. To upgrade the Telemetry Service, use the same procedure as installing it.
Upload authorization
If you plan to upload diagnostic collections to Citrix, you must have a Citrix or Citrix Cloud account. (These are the credentials that you use to access Citrix downloads or access the Citrix Cloud Control Center.) After your account credentials are validated, a token is issued.
If you authenticate with a Citrix account or a Citrix Cloud account, click a link to access Citrix Cloud using HTTPS with your default browser. After you enter your Citrix Cloud credentials, the token is displayed. Copy the token and then paste it into Scout. You can then continue in the Scout wizard.
The token is stored locally on the machine where you’re running Scout. To enable use of that token the next time you run Collect or Trace & Reproduce, select the Store token and skip this step in the future checkbox.
You must reauthorize each time you select Schedule on the Scout opening page. You cannot use a stored token when creating or changing a schedule.
Use a proxy for uploads
If you want to use a proxy server to upload collections to Citrix, you can instruct Scout to use the proxy settings configured for your browser’s Internet Properties. Alternatively, you can specify the proxy server’s IP address and port number.
Find machine
For the Collect, Trace & Reproduce, and Schedule procedures, Scout lists the Controllers and VDAs it discovers automatically.
When you run Scout Health Check from the Delivery Controller, click Find machine to discover machines, including delivery controllers, VDAs, license servers, and StoreFront servers.
When you run Scout Health Check from a domain-joined machine which is not an Delivery Controller, Scout cannot discover machines automatically. You need to add machines manually or import VDA machines.
Add machines manually
After Scout lists the Controllers and VDAs it discovers, you can manually add other machines in the deployment, such as StoreFront servers, License Servers, and Citrix Provisioning servers.
When running health checks:
- Citrix License Servers in the domain are discovered automatically. You cannot add License Servers manually.
- Health checks do not currently support Citrix Provisioning servers.
On any Scout page that lists the discovered machines, click + Add machine. Type the FQDN of the machine that you want to add, and then click Continue. Repeat to add other machines, as needed. (Although entering a DNS alias instead of an FQDN can appear valid, the health checks might fail.)
Manually added machines always appear at the top of the machines list, above the discovered machines.
An easy way to identify a manually added machine is the red delete button on the right end of the row. Only manually added machines have that button. Discovered machines don’t.
To remove a manually added machine, click the red button on the right end of the row. Confirm the deletion. Repeat to delete other manually added machines.
Scout remembers manually added machines until you remove them. When you close and then reopen Scout, the manually added machines are still listed at the top of the list.
CDF traces are not collected when using Trace & Reproduce on StoreFront servers. However, all other trace information is collected.
Import VDA machines
You can import VDA machines in the deployment when running health checks.
-
On Delivery Controller or Connector, generate the machine list file with the PowerShell command. On Connector, you must input Citrix credentials and select the customer in the pop-up dialog.
Get-BrokerMachine| foreach { $_.DnsName } | out-file C:\machineList.txt
- Copy the machineList.txt file to the domain-joined machine that you want to launch Scout Health Check.
- On the Scout Health Check page, click Add Machine.
- Select the Windows VDA machine type.
- Click Import VDA machines.
- Select the machineList.txt file.
- Click Open.
The imported VDA machines are listed on the Scout Health Check page.
Collect diagnostics
The Collect procedure comprises selecting machines, starting the diagnostics collection, and then uploading the file containing the collection to Citrix or saving it locally.
-
Launch Scout. From the machine’s Start menu, select Citrix > Citrix Scout. On the opening page, click Collect.
-
Select machines.
- On a Controller, the Select machines page lists all the VDAs and Controllers in the site. You can filter the display by machine name. To add other machines manually (such as StoreFront or Citrix Provisioning servers), see Add machines manually.
- On other components (such as VDA servers), the Select machines page lists only the local machine. Manually adding machines is not supported.
Select the checkbox next to each machine you want to collect diagnostics from, and then click Continue.
Scout automatically launches verification tests on each selected machine, ensuring it meets the criteria listed in Verification tests. If verification fails, a message is posted in the Status column, and that machine’s checkbox is unselected. You can either:
- Resolve the issue and then select the machine’s checkbox again. This triggers a retry of the verification tests.
- Skip that machine (leave its checkbox unselected). Diagnostics won’t be collected from that machine.
When the verification tests complete, click Continue.
-
Collect diagnostics. The summary lists all the machines from which diagnostics are collected (the machines you selected that passed the verification tests). Click Start Collecting.
During collection:
- The Status column indicates the current collection state for a machine.
- To stop an in-progress collection on a single machine, click Cancel in the Action column for that machine.
- To stop all in-progress collections, click Stop Collection in the lower right corner of the page. Diagnostics from machines that have completed collection are kept. To resume the collection, click Retry in the Action column for each machine.
- When the collection completes for all selected machines, the Stop Collection button in the lower right corner changes to Continue.
- To collect diagnostics again, click Collect Again in that machine’s Action column. The newer collection overwrites the earlier.
- If a collection fails, you can click Retry in the Action column. Only successful collections are uploaded or saved.
- After the collection completes for all selected machines, don’t click Back. (If you click it, the collection is lost.)
When the collection completes, click Continue.
-
Save or upload the collection. Choose whether to upload the file to Citrix, or save it on the local machine.
If you choose to upload the file now, continue with Step 5.
If you choose to save the file locally:
- A Windows Save dialog box appears. Navigate to the desired location.
- When the local save completes, the pathname of the file is displayed and linked. You can view the file. You can upload the file later to Citrix. See CTX136396.
Click Done to return to the Scout opening page. You don’t need to complete any further steps in this procedure.
-
Authenticate for uploads and optionally specify a proxy. For details, see Upload authorization.
- If you haven’t authenticated through Scout, continue with this step.
- If you have authenticated through Scout, the stored authorization token is used by default. If this is what you want to do, select this option and click Continue. You aren’t prompted for credentials for this collection. Continue with Step 6.
- If you authenticated previously, but want to reauthorize and get a new token, click Change/Reauthorize and continue with this step.
Choose whether you want to use Citrix credentials or Citrix Cloud credentials to authenticate the upload. Click Continue. The credentials page appears only if you’re not using a stored token.
On the credentials page:
- If you want to use a proxy server for the file upload, click Configure proxy. You can instruct Scout to use the proxy settings configured for your browser’s internet properties. Or, you can enter the proxy server’s IP address and port number. Close the proxy dialog box.
- For a Citrix Cloud account, click Generate token. Your default browser launches to a Citrix Cloud page where a token is displayed. Copy the token, and then paste it on the Scout page.
- For a Citrix account, enter your credentials.
When you’re done, click Continue.
-
Enter information about the upload.
- The name field contains the default name for the file for the collected diagnostics. This suffices for most collections, although you can change the name. (If you delete the default name and leave the name field empty, the default name is used.)
- Optionally, specify an 8-digit Citrix Support case number.
- In the optional Description field, describe the issue and indicate when the issue occurred, if applicable.
When you’re done, click Start Upload.
During the upload, the lower left portion of the page approximates the percentage of the upload that has completed. To cancel an in-progress upload, click Stop Upload.
When the upload completes, the URL of its location is displayed and linked. You can follow the link to the Citrix location to view the analysis of the upload, or you can copy the link.
Click Done to return to the Scout opening page.
Trace and reproduce
The Trace and Reproduce procedure comprises selecting machines, starting a trace, reproducing issues, completing the diagnostics collection, and then uploading the file to Citrix, or saving it locally.
This procedure is similar to the standard Collect procedure. However, it allows you to start a trace on machines and then re-create issues on those machines. All diagnostics collections include AOT trace information. This procedure adds CDF traces to help troubleshooting.
-
Launch Scout. From the machine’s Start menu, select Citrix > Citrix Scout. On the opening page, click Trace & Reproduce.
-
Select machines. The Select machines page lists all the VDAs and Controllers in the site. You can filter the display by machine name. Select the checkbox next to each machine you want to collect traces and diagnostics from. Then click Continue.
To add other machines manually (such as StoreFront or Citrix Provisioning servers), see Add machines manually.
Scout automatically launches verification tests on each selected machine, making sure it meets the criteria listed in Verification tests. If verification fails for a machine, a message is posted in the Status column, and that machine’s checkbox is unselected. You can either:
- Resolve the issue and then select the machine’s checkbox again. This triggers a retry of the verification tests.
- Skip that machine (leave its checkbox unselected). Diagnostics and traces are not collected from that machine.
When the verification tests complete, click Continue.
-
Start the trace. The summary lists all the machines from which traces are collected. Click Start Tracing.
On one or more of the selected machines, reproduce the issues you experienced. Trace collection continues while you’re doing that. When you’re done reproducing the issue, click Continue in Scout. That stops the trace.
After you stop the trace, indicate whether you reproduced the issue during the trace.
-
Collect diagnostics from machines. Click Start Collecting. During collection:
- The Status column indicates the current collection state for a machine.
- To stop an in-progress collection on a single machine, click Cancel in the Action column for that machine.
- To stop all in-progress collections, click Stop Collection in the lower right corner of the page. Diagnostics from machines that have completed collection are kept. To resume the collection, click Retry in the Action column for each machine.
- When the collection completes for all selected machines, the Stop Collection button in the lower right corner changes to Continue.
- To collect diagnostics again from a machine, click Collect Again in that machine’s Action column. The newer collection overwrites the earlier.
- If a collection fails, you can click Retry in the Action column. Only successful collections are uploaded or saved.
- After the collection completes for all selected machines, don’t click Back. (If you do, the collection is lost.)
When the collection completes, click Continue.
-
Save or upload the collection. Choose whether to upload the file to Citrix or save it locally.
If you choose to upload the file now, continue with Step 6.
If you choose to save the file locally:
- A Windows Save dialog box appears. Select the desired location.
- When the local save completes, the pathname of the file is displayed and linked. You can view the file. Remember: You can upload the file later from Citrix; see CTX136396 for Citrix Insight Services.
Click Done to return to the Scout opening page. You don’t need to complete any further steps in this procedure.
-
Authenticate for uploads and optionally specify a proxy. Review Upload authorization for details of this process.
- If you haven’t authenticated through Scout, continue with this step.
- If you authenticated through Scout, the stored authorization token is used by default. If this what you want to do, choose this option and click Continue. You aren’t prompted for credentials for this collection. Continue with Step 7.
- If you previously authenticated, but want to reauthorize and get a new token, click Change/Reauthorize and continue with this step.
Choose whether you want to use Citrix credentials or Citrix Cloud credentials to authenticate the upload. Click Continue. The credentials page appears only if you’re not using a stored token.
On the credentials page:
- If you want to use a proxy server for the file upload, click Configure proxy. You can instruct Scout to use the proxy settings configured for your browser’s Internet Properties. Or, you can enter the proxy server’s IP address and port number. Close the proxy dialog box.
- For a Citrix Cloud account, click Generate token. Your default browser launch to a Citrix Cloud page where a token is displayed. Copy the token, and then paste it on the Scout page.
- For a Citrix account, enter your credentials.
When you’re done, click Continue.
-
Provide information about the upload.
Enter upload details:
- The name field contains the default name for the file for the collected diagnostics. This suffices for most collections, although you can change the name. (If you delete the default name and leave the name field empty, the default name is used.)
- Optionally, specify an 8-digit Citrix Support case number.
- In the optional Description field, describe the issue and indicate when the issue occurred, if applicable.
When you’re done, click Start Upload.
During the upload, the lower left portion of the page approximates what percentage of the upload has completed. To cancel an in-progress upload, click Stop Upload.
When the upload completes, the URL of its location is displayed and linked. You can follow the link to the Citrix location to view the analysis of the upload, or you can copy the link.
Click Done to return to the Scout opening page.
Scout supports TraceLogging provider
Previously, Scout supported only the Windows performance provider, which required extra decoding files and traced only sessions and events from a single session for the same provider.
Starting with the Citrix Virtual Apps and Desktops version 2411, Scout supports the TraceLogging provider. This provider does not require extra decoding files and can enable and receive events from up to eight trace sessions for the same provider. This feature is enabled by default.
Enable additional log collection
The Enable additional log collection function lets you use the trace and reproduce function with more tools, like perfmon, Netsh, DebugView, and Wireshark.
Starting with the 2407 release, when you enable another log collection, Scout automatically detects the CDC-related tools installed on your machine and auto collects the CDC tool-related trace logs in the zip package. You can customize these zip file and attach it to Scout. With this automation, you can use Citrix Scout more effectively and this helps you to diagnose the issues quickly.
Note:
This only applies to local machines.
To set up additional log collection:
- Launch Citrix Scout.
- Click the Settings gear.
- Click Enable additional log collection with more tools.
- Click Save.
To collect additional logs:
- On the Scout home page, click Trace & Reproduce.
- On the Select machines page, click the gear on the right side of the local machine.
- Follow the Trace and Reproduce instructions.
- After completion, check the logs in the zip file. The logs are zipped in the folder CDCLogs.
Note:
If the Procmon Tool is selected for tracing, Process Monitor logs can grow large quickly. Ensure you select only what tools are needed. You can also monitor the size of the logs under %temp%\Scout-CDC-Log.
Schedule collections
Note:
You can currently schedule collections, but not health checks.
The Schedule procedure comprises selecting machines and then setting or canceling the schedule. Scheduled collections are automatically uploaded to Citrix. (You can save scheduled collections locally using the PowerShell interface. See Citrix Call Home.)
-
Launch Scout. From the machine’s Start menu, select Citrix > Citrix Scout. On the opening page, click Schedule.
-
Select machines. All the VDAs and Controllers in the site are listed. You can filter the display by machine name.
When you installed VDAs and Controllers using the graphical interface, if you set a Call Home schedule (see Citrix Call Home), Scout displays those settings, by default. You can use this version of Scout to start scheduled collections for the first time, or change a previously configured schedule.
Although you enabled/disabled Call Home on a per-machine basis during component installation, a schedule configured in Scout affects all the machines you select.
Select the checkbox next to each machine that you want to collect diagnostics from, and then click Continue.
To add other machines manually (such as StoreFront or Citrix Provisioning servers), see Add machines manually.
Scout automatically launches verification tests on each of the selected machines, making sure it meets the criteria in Verification tests. If verification fails for a machine, a message is posted in the Status column, and that machine’s checkbox is unselected. You can either:
- Resolve the issue and then select the machine’s checkbox again. This triggers a retry of the verification tests.
- Skip that machine (leave its checkbox unselected). Diagnostics (or traces) are not collected from that machine.
When the verification tests complete, click Continue.
The summary page lists the machines to which schedules are applied. Click Continue.
-
Set the schedule. Indicate when you want diagnostics to be collected. Remember: The schedule affects all selected machines.
- To configure a weekly schedule for the selected machines, click Weekly. Choose the day of the week. Enter the time of day (24-hour clock) for the collection to begin.
- To configure a daily schedule for the selected machines, click Daily. Enter the time of day (24-hour clock) for the collection to begin.
- To cancel an existing schedule for the selected machines (and not replace it with another), click Off. This cancels any schedule that was previously configured for those machines.
Click Continue.
-
Authenticate for uploads and optionally specify a proxy. Review Upload authorization for details of this process. Remember: You cannot use a stored token to authenticate when working with a Scout schedule.
Choose whether you want to use Citrix credentials or Citrix Cloud credentials to authenticate the upload. Click Continue.
On the credentials page:
- If you want to use a proxy server for the file upload, click Configure proxy. You can instruct Scout to use the proxy settings configured for your browser’s Internet Properties. Or, you can enter the proxy server’s IP address and port number. Close the proxy dialog box.
- For a Citrix Cloud account, click Generate token. Your default browser launches to a Citrix Cloud page where a token is displayed. Copy the token, and then paste it on the Scout page.
- For a Citrix account, enter your credentials.
When you’re done, click Continue.
Review the configured schedule. Click Done to return to the Scout opening page.
During a collection, each selected machine’s Windows application log contains entries about the collection and upload.
Data masking
The diagnostic information collected using Citrix Scout might contain security-sensitive information. The Citrix Scout data masking feature allows you to mask sensitive data in diagnostics files before uploading them to Citrix.
Scout data masking is configured to mask the IP address, machine names, domain names, user names, hypervisor names, Delivery Group names, catalog names, application names, and SIDs.
Note:
CDF traces are encrypted and cannot be masked.
Linux VDA logs are compressed to
.tar.gz2
format and cannot be masked.
Collect new diagnostics and perform data masking
To use the Citrix Scout data masking feature, launch Scout from the command line.
- In Windows, open the command prompt as an administrator.
- Go to the directory where Scout is installed:
cd C:\Program Files\Citrix\Telemetry Service
. - Launch Scout:
ScoutUI.exe datamasking
. - Click Collect or Trace & Reproduce to collect diagnostics.
- After the collection completes, select Enable data masking. This option is enabled by default.
- Configure the data mask. You can use the default rules or customize the rules.
- Select whether to upload or save the diagnostics collection.
- If you select Upload the diagnostics collection to Citrix, masked diagnostics files are uploaded to Citrix.
- If you select Save the diagnostics collection on your local machine, both the original and masked diagnostics are saved to the specified location.
Perform data masking on existing diagnostics
- In Windows, open the command prompt as an administrator.
- Go to the directory where Scout is installed:
cd C:\Program Files\Citrix\Telemetry Service
. - Launch Scout directly in data masking mode:
ScoutUI.exe datamasking filePath
. - Select “Enable data masking” to continue. This option is enabled by default.
- Configure the data mask. You can run data masking with the default rules or customize the rules.
- Select whether to upload or save the diagnostics collection.
- If you select Upload the diagnostics collection to Citrix, masked diagnostics files are uploaded to Citrix.
- If you select Save the diagnostics collection on your local machine, both the original and masked diagnostics are saved to the specified location.
Masked data file and mapping file locations
After you have uploaded or saved the diagnostics collection, click the link to open the original and masked diagnostics, and open the mapping information file.
Usage data collection
When you use Scout, Citrix uses Google Analytics to collect anonymous usage data to be used for future product features and improvements. Data collection is enabled by default.
To change usage data collection and upload, click the Settings gear in the Scout UI. You can then choose whether to send the information by selecting Yes or No and then clicking Save.
Command-line interfaces for Scout functionalities
You can now use command-line interfaces for Scout functionalities, enabling you to collect needed logs and data without opening the Scout UI. This feature provides convenience for advanced users to automate the log or trace process locally or remotely for target machines or sites. This feature is enabled by default.
Commands are added for the following functionalities:
Note:
When running the remote trace session, the new telemetry version must be installed on both VDA and DDC. This installation is required because the Scout Command-line is supported starting from Citrix Virtual Apps and Desktops version 2411, and older versions of
TelemetryService
do not support this feature.
The following table describes the newly added commands:
Help
Command-line interface | Description | Example |
---|---|---|
ScoutCLI.exe -h
|
Displays context-sensitive help.
|
ScoutCLI.exe -h |
ScoutCLI.exe -help |
Command for collect diagnostics
Command-line interface | Description | Example |
---|---|---|
ScoutCLI.exe Collect -exclude <collector> |
Excludes the diagnostics from the specified collectors (Windows Management Instrumentation (WMI) process, registry, crash report, header, trace, msi , vcu , tool telemetry, and local data). |
ScoutCLI.exe collect -exclude wmi, localdata -output "C:/Logs/mydata.zip"
|
ScoutCLI.exe Collect -output <filename> |
Specifies where to save the output log file with .zip as the suffix. |
|
ScoutCLI.exe Collect -fqdn <hostname> |
Collects diagnostics on specified machines in a site. | ScoutCLI.exe collect -fqdn hostname -exclude wmi, localdata -output "C:/Logs/mydata.zip" |
Start trace
Command-line interface | Description | Example |
---|---|---|
ScoutCLI.exe StartTrace -guids <filename (xxx.ctl)> |
Collects target modules’ logs for the specified GUIDs. | Example for local machine trace start - ScoutCLI.exe StartTrace -guids C:\Logs\provider1.ctl -output C:\Logs\xxx.etl -name session1 -level 16 -max 50 ; Example for remote machine trace start - ScoutCLI.exe StartTrace -fqdn hostname -guids C:\Logs\provider1.ctl -output C:\Logs\xxx.etl -name session1 -level 16 -max 50 |
ScoutCLI.exe StartTrace -output <filename> |
Specifies where to save the output log file with .etl as the suffix. | |
ScoutCLI.exe StartTrace -name <session name> |
Defines the name of the tracing session. | |
ScoutCLI.exe StartTrace -level <value> |
Selects the log level to log target diagnostic details. The default value is 16. | |
ScoutCLI.exe StartTrace -max <value> |
Specifies the maximum log file size in MB. The default value is 50. | |
ScoutCLI.exe StartTrace -fqdn <hostname> |
Starts tracing on specified machines in a site. |
Stop trace
Command-line interface | Description | Example |
---|---|---|
ScoutCLI.exe StopTrace -name <session name> |
Stop the specified tracing session. | ScoutCLI.exe StopTrace -name session1 |
ScoutCLI.exe StopTrace -fqdn <hostname> |
Stops tracing on specified machines in a site. -o option is needed to assign the local path where the remote .etl is copied to. |
ScoutCLI.exe StopTrace -fqdn hostname -name session1 -output C:\Logs\xxx.etl
|
ScoutCLI.exe StopTrace -output <filename> |
Specifies where to save the output log file with .etl as the suffix. |
List ongoing trace sessions
Command-line interface | Description | Example |
---|---|---|
ScoutCLI.exe ListSession -name <session name> |
Shows details for the specified tracing session. If no name is specified, shows details for all running tracing sessions. | ScoutCLI.exe ListSession -name session1 |
ScoutCLI.exe ListSession -fqdn <hostname> |
Shows tracing details on specified machines in a site. | ScoutCLI.exe ListSession -fqdn hostname -name session1 |
Start and stop CDC
Command-line interface | Description | Example |
---|---|---|
ScoutCLI.exe StartCDC -config <filename> |
Specifies the JSON configuration file for the Citrix Diagnostic Collectors (CDC) tool parameters. |
ScoutCLI.exe StartCDC -config xxx.json -path C:\Logs
|
ScoutCLI.exe StartCDC -path <folder> |
Specifies where the output log files are saved. | |
ScoutCLI.exe StopCDC |
Stop the collection of CDC tools. | ScoutCLI.exe StopCDC |
In this article
- Introduction
- What is collected
- Scout configuration
- About health checks
- Run health checks
- Permissions and requirements
- Verification tests
- Version compatibility
- Install and upgrade
- Upload authorization
- Find machine
- Add machines manually
- Import VDA machines
- Collect diagnostics
- Trace and reproduce
- Enable additional log collection
- Schedule collections
- Data masking
- Usage data collection
- Command-line interfaces for Scout functionalities