Citrix Scout
Introduction
Citrix Scout collects diagnostics that can be used for proactive maintenance in your XenApp and XenDesktop deployment. Citrix offers comprehensive, automated analysis through Citrix Insight Services. You can also use Scout to troubleshoot issues, either on your own or with guidance from Citrix Support. 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 three main procedures:
- Collect: Runs a one-time diagnostics collection on machines you select in a Site. Then, you either upload the file containing the collection to Citrix or save it locally.
- Trace & Reproduce: Starts a manual trace on machines you select. Then you re-create issues on those machines. After re-creating the issue, the trace is stopped. Then, Scout collects other diagnostics and uploads the file containing the trace and the collection to Citrix, or saves the file locally.
- Schedule: Schedules diagnostics collections to occur daily or weekly at a specified time on machines you select. The file containing each collection is automatically uploaded to Citrix.
The graphical interface described in this article is the primary way to use Scout. Alternatively, you can use the PowerShell interface to configure one-time or scheduled diagnostic collections and uploads. See Call Home.
Where to run Scout:
- In an on-premises XenApp and XenDesktop deployment, run Scout from a Delivery Controller to capture diagnostics from one or more Virtual Delivery Agents (VDAs) and Delivery Controllers. You can also run Scout from a VDA to collect local diagnostics.
- In a Citrix Cloud environment that uses the XenApp and XenDesktop Service, run Scout from a VDA to collect local diagnostics.
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.
Collected information includes:
- Registry entries created by XenApp and XenDesktop 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 %PROGRAM DATA%\Citrix\CDF.
About trace information:
- The trace information is compressed as it is collected, maintaining a small footprint on the machine.
- On each machine, the Citrix Telemetry Service retains a maximum of 10 MB of compressed recent trace information, with a maximum time limit of eight days.
- Traces are held in memory to avoid IOPs on provisioned machines.
- The trace buffer uses a circular mechanism to retain traces in memory.
For a list of the datapoints that Scout collects, see Scout key datapoints.
Prerequisites and considerations
Permissions
- 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.
- Use Run as administrator when launching Scout.
For each machine from which you collect diagnostics:
- 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.
- To set a schedule for diagnostic collection, the machine must be running a Scout version provided with XenApp and XenDesktop 7.14 or a later supported version.
Scout runs verification tests on the machines you select to ensure these requirements are met.
Verification tests
Before a diagnostic collection starts, verification tests run automatically for each selected machine. These tests ensure that the requirements listed above are met. If a test fails for a machine, Scout displays a message, with suggested corrective actions.
| Error message | Corrective action |
|---|---|
| Scout cannot reach this machine | Ensure that the machine is powered-on. Ensure that the network connection is working properly. (This can include verifying that your firewall is properly configured.) Ensure that 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 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. |
Version compatibility
This version of Scout (3.x) is intended to be run on (minimum) XenApp and XenDesktop 7.14 Controllers and VDAs.
An earlier version of Scout is provided with earlier XenApp and XenDesktop deployments. 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 XenApp and XenDesktop 7.14 (minimum) | Yes | Yes |
| Support XenDesktop 5.x, 7.1 to 7.13 | Yes | No |
| Support XenApp 6.x, 7.5 to 7.13 | Yes | No |
| Delivered with product | 7.1 to 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 resources 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 telemetry installed) |
Install
By default, Scout is installed automatically as part of the Citrix Telemetry Service when you install 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 XenApp or XenDesktop ISO.
Upload authorization
If you plan to upload diagnostic collections to Citrix, you must have a Citrix or Citrix Cloud account. (These are the credentials 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, the token-issuing process is not visible. You simply enter your account credentials. After Citrix validates the credentials, you are allowed to continue in the Scout wizard.
- If you authenticate with a Citrix Cloud account, you click a link to access Citrix Cloud using HTTPS with your default browser. After entering your Citrix Cloud credentials, the token is displayed. Copy the token and then paste it into Scout. You are then allowed to continue in the Scout wizard.
The token is stored locally on the machine where you’re running Scout. If you want to use that token the next time you select Collect or Trace & Reproduce, select the Store token and skip this step in the future check box.
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, or you can specify the proxy server’s IP address and port number.
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.
Step 1. Launch Scout.
From the machine’s Start menu: Citrix > Citrix Scout. On the opening page, click Collect.
Step 2. 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 check box next to each machine you want to collect diagnostics from, and then click Continue.
Scout automatically launches verification tests on each machine you selected, ensuring it meets the criteria listed in Verification tests. If verification fails, a message is posted in the Status column, and that machine’s check box is unselected. You can either:
- Resolve the issue and then select the machine’s check box again. This triggers a retry of the verification tests.
- Skip that machine (leave its check box unselected). Diagnostics will not be collected from that machine.
When the verification tests complete, click Continue.
Step 3. Collect diagnostics from machines.
The summary lists all the machines from which diagnostics will be 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 comp;leted collection are retained. 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.
- If a collection for a machine succeeds and you want 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, do not click Back. If you click that button and confirm the prompt, the collection is lost.
When the collection completes, click Continue.
Step 4. Save or upload the collection.
Choose whether to upload the file containing the collected diagnostics 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 from Citrix; see CTX136396 for Citrix Insight Services, or Smart Tools support.
Click Done to return to the Scout opening page. You do not need to complete any further steps in this procedure.
Step 5. Authenticate for uploads and optionally specify proxy.
Review Upload authorization for details of this process.
- If you have not previously authenticated through Scout, continue with this step.
- If you previously authenticated through Scout, the stored authorization token is used by default. If this is OK with you, choose this option and click Continue. You are not prompted for credentials for this collection; continue with Step 6.
- If you previously authenticated, but want to reauthorize and have a new token issued, 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 will 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.
Step 6. Provide information about the upload.
Enter upload details:
- The name field contains the default name for the file that will contain the collected diagnostics. This should suffice for most collections, although you can change the name. (If you delete the default name and leave the name field empty, the default name will be 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.
Trace and reproduce
The Trace and Reproduce procedure comprises selecting machines, starting a trace on those machines, reproduce issues on those machines, completing the diagnostics collection, and then uploading the file containing the traces and collection 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.
Step 1. Launch Scout.
From the machine’s Start menu: Citrix > Citrix Scout. On the opening page, click Trace & Reproduce.
Step 2. 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 check box next to each machine you want to collect traces and diagnostics from, and then click Continue.
Scout launches verification tests on each of the machines you selected, ensuring 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 check box is unselected. You can either:
- Resolve the issue and then select the machine’s check box again. This triggers a retry of the verification tests.
- Skip that machine (leave its check box unselected). Diagnostics and traces will not be collected from that machine.
When the verification tests complete, click Continue.
Step 3. Trace.
The summary lists all the machines from which traces will be 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.
Step 4. 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 retained. 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.
- If a collection for a machine succeeds and you want 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, do not click the Back button. If you click that button and confirm the prompt, the collection is lost.
When the collection completes, click Continue.
Step 5. Save or upload the collection.
Choose whether to upload the file containing the collected diagnostics to Citrix, or save it on the local machine.
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, or Citrix Smart Tools.
Click Done to return to the Scout opening page. You do not need to complete any further steps in this procedure.
Step 6. Authenticate for uploads and optionally specify proxy.
Review Upload authorization for details of this process.
- If you have not previously authenticated through Scout, continue with this step.
- If you previously authenticated through Scout, the stored authorization token is used by default. If this is OK with you, choose this option and click Continue. You are not prompted for credentials for this collection; continue with Step 7.
- If you previously authenticated, but want to reauthorize and have a new token issued), 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 will 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.
Step 7. Provide information about the upload.
Enter upload details:
- The name field contains the default name for the file that will contain the collected diagnostics. This should suffice for most collections, although you can change the name. (If you delete the default name and leave the name field empty, the default name will be 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 lik 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.
Schedule collections
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.)
Step 1. Launch Scout.
From the machine’s Start menu: Citrix > Citrix Scout. On the opening page, click Schedule.
Step 2. Select machines.
The Select machines page lists all the VDAs and Controllers in the Site. You can filter the display by machine name.
When you installed VDAs and Controllers using the graphical interface, you were offered the opportunity to participate in Call Home. For details, see Citrix Call Home. (Call Home includes scheduling functionality equivalent to Scout.) 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.
Keep in mind that although you enabled/disabled Call Home on a per-machine basis, setting a schedule in Scout uses the same commands, but affects all the machines you select.
Select the check box next to each machine you want to collect diagnostics from, and then click Continue.
Scout launches verification tests on each of the machines you selected, ensuring 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 check box is unselected. You can either:
- Resolve the issue and then select the machine’s check box again. This triggers a retry of the verification tests.
- Skip that machine (leave its check box unselected). Diagnostics (or traces) will not be collected from that machine.
When the verification tests complete, click Continue.
The summary page lists the machines to which schedules will be applied Click Continue.
Step 3. Set schedule.
Indicate when you want diagnostics to be collected. Remember: The schedule affects all the selected machines.
- To configure a weekly schedule for the selected machines, click Weekly. Choose the day of the week and enter the time of day (24-hour clock) when the diagnostics collection will begin.
- To configure a daily schedule for the selected machines, click Daily. Enter the time of day (24-hour clock) when the diagnostics collection will 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.
Step 4. Authenticate for uploads and optionally specify 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 will 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.
Review the configured schedule. Click Done to return to the Scout opening page.
When each scheduled collection occurs, each selected machine’s Windows application log contains entries about the collection and upload.