Automatic Seamless Troubleshooting Tool

book

Article ID: CTX694725

calendar_today

Updated On:

Description

System Requirements

  • Operating System: Windows 10 or later, Windows Server 2016 or later (64-bit x64 architecture)
  • Administrative Rights: Required ONLY for installation, GUI mode, and auto-start registration/unregistration. Basic logging operations do NOT require admin privileges.
  • Hardware: Multi-core CPU (2 GHz+), 8 GB RAM recommended, 2 GB free disk space
  • Dependencies: Microsoft Visual C++ 2015-2022 Redistributable (x64) - typically already installed with Citrix Workspace apps
  • Video Recording Requirements: .NET Framework (required only for video recording functionality; all other features work without it)
  • Built-in Components: Windows Shell, COM/OLE (included with Windows)

 

Installation

  1. Download SetupASTT.exe from https://www.citrix.com/downloads/citrix-tools/citrixtoolspage/AutomaticSeamlessTroubleshootingTool.html 
  2. Right-click the installer and select "Run as administrator"
  3. Follow the on-screen installation prompts
  4. The tool will be installed to your selected directory with all necessary components

User Interface Overview (Optional)

  • Main Configuration Window: Configure logging options, specify when to start collection (session login, immediately, etc.), and set output directory
  • Controller Window: (Optional) Real-time view of session information and logging status, with controls for stopping collection and taking screenshots
  • Tooltip System: Hover information displays for troubleshooting window-related issues

The Controller Window color indicates the current session type for quick visual identification:

  • Blue - Published Application session
  • Maroon - HDX Desktop session
  • Lime - RDP session
  • Red - Other session types

Command Line Usage (Recommended)


Command-line operation is the recommended method for using ASTT due to its simplicity, reliability, and automation capabilities. This approach eliminates the need for GUI interaction and provides precise control over all diagnostic options.

ASTT supports extensive command-line operation for automated deployments and scripting:

SmlsTool.exe [options]
  •  
  • Option Description Admin Required?
    -? Display help dialog with all available options No
    -s Start logging immediately No
    -sPA Start logging for Published App sessions only

    No
    -sCtx Start logging for any Citrix HDX session No
    -f:[path] Specify output folder for logs (absolute path required) No
    -t:[minutes] Set logging duration in minutes (max: system-defined limit) No
    -register Register auto-start for logging with current settings Yes
    -unregister remove auto-start configuration Yes
    -regdetail Show current registration details No
    -dSaveScrn disable screen recording\capture No
    -dExcess Disable window events and attributes detection No
    -dSmlsFlags Disable seamless registry flags checking No
    -dSShell Disable session process and shell state checking No
    -dBProcess Disable background process analysis No
    -dCWMLogs Disable window and message history collection No
    -dToolTip Disable tooltip information windows No
    -dStopBtn Disable Controller Window display No
  •  

  • Command Examples 

  • Regular User Commands (No Admin Required):

    # Start logging immediately with default settings
SmlsTool.exe -s
# Log published apps only, custom folder, 10-minute timeout
SmlsTool.exe -sPA -f:"C:\tools\logs" -t:10
# Minimal logging (no video, no UI popups)
SmlsTool.exe -s -dSaveScrn -dStopBtn -dTooltip -t:10
     

  • Administrator Commands (Admin Required):

  • # Configure auto-start for any login (most common auto-start usage)
SmlsTool.exe -s -register
# Configure auto-start for Citrix sessions with screen recording disabled
SmlsTool.exe -sCtx -dSaveScrn -t:15 -register
# Register minimal logging (no UI, 5 minutes, published apps only)
SmlsTool.exe -sPA -dStopBtn -dTooltip -t:5 -register
# Remove auto-start configuration
SmlsTool.exe -unregister
  •  CRITICAL WARNING: Always run SmlsTool.exe -unregister immediately after completing log collection when using auto-start registration. Leaving auto-start enabled can cause system instability, especially with remote session launches and system-wide configuration changes.
  •  

Quick Start (Recommended)

For most troubleshooting scenarios, this single command is all you need:

SmlsTool.exe -s


This command starts logging immediately for any session type with all default settings enabled.

To configure automatic logging on any type of login (requires admin):

SmlsTool.exe -s -register

How to Use

Recommended Method (Command Line):

For Basic Logging (No Admin Required):

  1. Install ASTT following the installation steps above
  2. Open Command Prompt (regular user mode) and navigate to the installation directory
  3. Run with desired options: Use the regular user command examples above for immediate logging
  4. Review logs: Collection automatically stops after timeout and saves to the specified directory

For Auto-Start Registration (Admin Required):

  1. Open Command Prompt as Administrator
  2. Navigate to the installation directory
  3. Run registration commands: Use -register or -unregister options
  4. Verify registration: Use -regdetail to check current settings
  5. IMPORTANT: Always run SmlsTool.exe -unregister immediately after log collection is complete to prevent system instability

Alternative Method (GUI - Admin Required):

  1. Right-click SmlsTool.exe and "Run as administrator"
  2. Configure settings: Select when to start logging, output directory, and diagnostic options
  3. Start collection: Use GUI "OK" button

Monitoring Progress: Regardless of how logging is started (command line, GUI, or auto-run), you can monitor progress using the Controller Window (if enabled) to view status and take manual screenshots.

Output Structure


All logs are organized in a timestamped folder with the following naming convention:

ASTT_log__Session<sessionID>__<username>_<SessionType>_dd.mm.yyyy_HH-MM-SS

Generated Files and Folders:

  • ScreenCaptures folder — Video recordings and screenshot images
  • Summary.txt — Overview of session information and detected issues
  • WindowReport.txt — Detailed window events and accessibility analysis
  • winhistorylog.txt — Complete window state changes including creation, destruction, style changes, visibility, foreground status, and other window events
  • msghistorylog32.txt / msghistorylog64.txt — Windows message history for 32-bit and 64-bit processes
  • SessionProcessShellReport.txt — Session, process, and shell state analysis
  • SystemParametersInfo.txt — Windows system parameter settings
  • ThemeInfo.txt — Current Windows theme and visual style information
  • Aero.msstyles — Theme file copy for reference
  • InstalledApps.txt — Complete list of installed applications and UWP apps
  • WIN32Services.txt — Windows services state and configuration
  • winhistorylog_tmp.txt — Temporary file (automatically cleaned up on normal exit)

Important: Log files may be incomplete if the tool is forcefully terminated. Always use the Controller Window "Stop" button or allow timeout completion for complete logs.

Log Collection Termination


Log collection automatically stops under these conditions:

  • Specified timeout duration expires
  • User session logs off gracefully
  • Manual stop via Controller Window
  • System shutdown or restart
  • Critical error during collection

Tool Components

  • SmlsTool.exe — Main application and user interface
  • whmhThunk.exe — 32-bit process for loading 32-bit hook libraries
  • whmhhook64.dll / whmhhook.dll — Window and message hook libraries (64-bit/32-bit)
  • Citrix.SuppTools.SRAgent.exe — Video screen recording component
  • SetupASTT.exe — Installation package

Troubleshooting Tips

  • Storage Space: Ensure adequate disk space (especially for video recording)
  • Session Detection: Tool automatically detects Citrix sessions; no manual configuration needed
  • Network Drives: Avoid saving logs to network locations; use local drives for optimal performance
  • Write Permissions: Ensure the user has write access to the specified log output directory

Version Information


This documentation applies to ASTT and its associated components. Tool version information is displayed in the application title bar and included in generated log files.

Auto-Start Registration Safety (CRITICAL)


⚠️ IMPORTANT SAFETY INFORMATION ⚠️

Auto-start registration configures ASTT to automatically begin log collection when specific session types are launched. While powerful for automated troubleshooting, improper use can cause system instability.

Critical Safety Rules:

  1. Always Unregister After Use: Run SmlsTool.exe -unregister immediately after completing your troubleshooting session
  2. Never Leave Auto-Start Enabled: Persistent auto-start registration can interfere with normal system operation
  3. Avoid System Changes: Do not modify system-wide configurations while auto-start is active

Safe Auto-Start Workflow:

# 1. Register for specific troubleshooting session
SmlsTool.exe -sPA -t:10 -register
# 2. Reproduce the issue (auto-logging will start)
# 3. Wait for timeout or issue reproduction
# 4. IMMEDIATELY unregister when done
SmlsTool.exe -unregister
# 5. Verify removal
SmlsTool.exe -regdetail

Environment

These software applications are provided to you as is with no representations, warranties or conditions of any kind. You may use and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the software application may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the software application fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the software application. In no event should the code be used to support of ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SOFTWARE APPLICATION, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.

Issue/Introduction

Overview

ASTT (Automatic Seamless Troubleshooting Tool) is a comprehensive diagnostic tool for Windows environments that automates the collection of logs and troubleshooting data for session-related issues, window management problems, and application behavior analysis for seamless applications. While it includes many features designed specifically for Citrix environments, it is also useful for general Windows platform troubleshooting, helping engineers and advanced users rapidly identify session bottlenecks, misconfigurations, and application windowing problems.

Key Features

  • Automatic Session Detection: Detects and analyzes Citrix HDX sessions, published applications, and local desktop sessions
  • Comprehensive Log Collection: Window history, message history, process/shell state, system parameters, theme information
  • Video and Screenshot Capture: Records session activity with configurable screen capture options
  • Registry Analysis: Checks seamless flags and configuration settings for potential issues
  • Background Process Detection: Identifies processes that may interfere with session logoff
  • Dual Operation Modes: Command-line for automation and GUI for interactive use
  • Auto-start Capabilities: Configure automatic logging on session start/login
  • Real-time Tooltips: Display window information during troubleshooting
Powered by Wolken Software