Citrix Scout

September 19, 2018

Introduction

Citrix Scout collects diagnostics that can be used for proactive maintenance in your Citrix Virtual Apps and Desktops 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 Citrix Virtual Apps and Desktops 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 Citrix Virtual Apps and Desktops 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 Citrix Virtual Apps and Desktops under HKEY_LOCAL_MACHINE\SOFTWARE\CITRIX.

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 compressed recent trace information for a maximum time limit of eight days.

As of 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.

You can modify the maximum size (default = 10 MB) and slice duration, using the Enable-CitrixTrace cmdlet or the HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Telemetry DefaultListen registry string.

Prerequisites and considerations

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 Citrix Virtual Apps and Desktops (or XenApp and XenDesktop 7.14-7.18).

Do not use the dollar sign ($) in usernames specified in pathnames. It prevents the collection of diagnostic information.

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.

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.

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 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 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 Citrix Virtual Apps and Desktops 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.

Add machines manually

After Scout lists the Controllers and VDAs it discovers, you can manually add other machines used in the Citrix Virtual Apps and Desktops deployment, such as StoreFront servers and Citrix Provisioning servers.

On any Scout page that lists the discovered machines, click + Add machine. Type the FQDN of the machine you want to add, and then click Continue. Repeat to add additional machines, as needed. 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 do not.

To remove a manually added machine, click the red button on the right end of the row. Confirm the deletion. Repeat to delete additional manually added machines.

Scout remembers manually added machines until you remove them. After you add machines, if 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.)

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.

The summary page lists the machines to which schedules will be applied Click Continue.

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.

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.

The official version of this content is in English. Some of the Citrix documentation content is machine translated for your convenience only. Citrix has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Citrix product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Citrix, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Citrix will not be held responsible for any damage or issues that may arise from using machine-translated content.

THIS SERVICE MAY CONTAIN TRANSLATIONS POWERED BY GOOGLE. GOOGLE DISCLAIMS ALL WARRANTIES RELATED TO THE TRANSLATIONS, EXPRESS OR IMPLIED, INCLUDING ANY WARRANTIES OF ACCURACY, RELIABILITY, AND ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.