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
  • Network: Network connectivity for Citrix HDX sessions, when Citrix diagnostics are applicable
  • 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 and 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, opening the log folder when stopped, 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, open the log folder when stopped, 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, including auto-generated and user-requested screenshots. AVI files may require VLC or another compatible player.
  • Summary.txt — Overview of tool version, OS version, session type, HDX/seamless configuration settings, supported and unsupported registry flags, WTS session change events, CtxHook status, and references to crash or hung-window findings when detected.
  • WindowReport.txt — Detailed window events, accessibility analysis, excessive window events, hung app and ghost window report.
  • winhistorylog.txt — Complete window state changes including creation, destruction, style changes, visibility, foreground status, layered window opacity changes, extended window styles, and other window events.
  • msghistorylog32.txt / msghistorylog64.txt — Windows message history for 32-bit and 64-bit processes.
  • SessionProcessShellReport.txt — Session, process, shell, graphic state, loaded module, monitor, DPI, and keyboard information.
  • SystemParametersInfo.txt — Windows system parameter settings, including accessibility settings, animation effects, font smoothing, drag dimensions, menu timing, caret width, foreground flash count, focus border dimensions, and other settings affecting seamless window rendering and positioning.
  • 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.
  • TimezoneInfo.txt — Local time, UTC time, active timezone, UTC offset, daylight saving status, and time synchronization settings captured at the start of log collection.
  • ScheduledTasks.txt — Recursive Task Scheduler dump including task state, run history, action command line, run-as user, triggers, repetition, idle, and power management settings.
  • StartupPrograms.txt — Applications configured to auto-launch at user logon from Run and RunOnce registry keys and Startup folders.
  • CrashedProcesses.txt — Created only when crashes are detected. Includes crash incidents, dump file discovery, debugging recommendations, and Windows Error Reporting configuration.
  • CitrixToolLogs folder — Created only for Citrix ICA desktop or published application sessions. Contains redirected output from available Citrix diagnostic tools such as keyboard/IME, audio, and session information diagnostics.
  • MSToolLogs folder — Created for every session type. Contains supplemental Windows diagnostic output when available.
  • winhistorylog_tmp.txt — Temporary window history cache, automatically cleaned up on normal exit. It may remain if log collection is not terminated gracefully.

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.

Important Detection Notifications

When ASTT detects a high-priority data point, such as unsupported registry flags, it may display a message box to notify the user during troubleshooting. In Citrix HDX sessions, ASTT may also offer to run the CtxHook health-check workflow when Citrix hook-related problems are detected.

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

Important data such as Window/Message history logs and SessionProcessShellReport.txt may not be saved until collection stops gracefully. Do not kill SmlsTool.exe processes unless instructed for troubleshooting.

Tool Components

  • SmlsTool.exe — Main 64-bit 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 and supporting binaries — Video screen recording component, used only when screen recording is enabled
  • CtxHookHealthCheck components — Citrix hook health-check support, used only when ASTT detects hook-related problems in an HDX session and the user chooses to run the check
  • SetupASTT.exe — Installation package

Troubleshooting Tips

  • Storage Space: Ensure adequate disk space, especially when video recording, supplemental diagnostic output, and crash dump discovery are enabled
  • Session Detection: Tool automatically detects Citrix sessions; no manual configuration is needed for most use cases
  • 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
  • Crash Analysis: If CrashedProcesses.txt is generated, review the incident and dump sections before collecting additional data
  • Startup Delays: Review StartupPrograms.txt and ScheduledTasks.txt for third-party software or scheduled tasks that may interfere with session initialization
  • Rendering Issues: Review SystemParametersInfo.txt, ThemeInfo.txt, and layered window entries in winhistorylog.txt

Version Information


This documentation applies to ASTT version 1.5 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.

If Auto-Start Does Not Launch

Some security software may block programs from launching early during user logon or session startup. If SmlsTool.exe -register does not start ASTT automatically on new session launch, use one of these workarounds:

  • Add SmlsTool.exe -s to the user's logon script if that startup method is allowed by the environment's security policy.
  • For published app session log collection only, configure SmlsTool.exe -s as a new published app, launch that published app first, and then launch the application being troubleshot in the same published session.

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, application startup issues, crash events, and application windowing problems.

Version 1.5 expands the original ASTT diagnostics with additional crash, startup, scheduled task, timezone, graphics, network, Citrix HDX, and hook-health investigation data while preserving the same command-line and GUI workflow used in version 1.

Key Features

  • Automatic Session Detection: Detects and analyzes Citrix HDX sessions, published applications, RDP sessions, and local desktop sessions
  • Comprehensive Log Collection: Window history, message history, process/shell state, system parameters, theme information, startup programs, scheduled tasks, timezone information, and services
  • Video and Screenshot Capture: Records session activity with configurable screen capture options
  • Crash Detection: Correlates Application Error and .NET Runtime events with dump files and Windows Error Reporting configuration
  • Registry Analysis: Checks seamless flags and configuration settings for potential issues
  • Citrix Diagnostics: Collects HDX session, keyboard/IME, audio, and related Citrix diagnostic data when available in Citrix sessions
  • Windows Diagnostics: Captures supplemental Windows diagnostic data for every supported session type
  • 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

 

What's New in Version 1.5

  • Enhanced Summary.txt: Adds WTS session change events, crash and hung-window cross references, and 32-bit/64-bit CtxHook loading status.
  • Enhanced winhistorylog.txt: Tracks layered window opacity changes over time and reports additional extended window styles such as WS_EX_COMPOSITED, WS_EX_LAYERED, WS_EX_LAYOUTRTL, WS_EX_NOACTIVATE, WS_EX_NOINHERITLAYOUT, and WS_EX_NOREDIRECTIONBITMAP.
  • New Core Logs: Adds TimezoneInfo.txt, ScheduledTasks.txt, StartupPrograms.txt, and conditional CrashedProcesses.txt.
  • CitrixToolLogs Subfolder: Captures selected Citrix diagnostic tool output for Citrix ICA desktop and published application sessions.
  • MSToolLogs Subfolder: Captures supplemental Windows diagnostic output when available.
  • CtxHook Health Check Components: Includes CtxHook health-check support components that may be launched when ASTT detects Citrix hook-related problems in HDX sessions.
Powered by Wolken Software