Log Class Reference

Primary logging controller with dual-channel output and caller identification. More...

Collaboration diagram for Log:

Public Member Functions
	constructor (context:vscode.ExtensionContext|undefined=undefined, fullyLoaded:boolean=false)
	Initializes the logging system with environment detection and auto-display.
	updateInitialisationStatus (extensionLoaded:boolean=true)
	Updates the initialization status and manages output channel lifecycle.
	info (message:string, searchDepth:number|undefined=undefined)
	Logs informational messages with automatic caller identification.
	warning (message:string, searchDepth:number|undefined=undefined)
	Records warning conditions requiring attention but not blocking execution.
	error (message:string, searchDepth:number|undefined=undefined)
	Records critical errors requiring immediate attention or investigation.
	debug (message:string, searchDepth:number|undefined=undefined)
	Generates detailed debugging information when debug mode is enabled.

Data Fields
Gui	: Gui = new Gui(this.LI)
	GUI notification logger instance for user-facing messages.

Detailed Description

Primary logging controller with dual-channel output and caller identification.

Serves as the main logging interface for the extension, providing both console output for developers and VS Code output panel integration. Features automatic caller identification, intelligent environment adaptation, and comprehensive formatting for optimal debugging and monitoring experiences.

Architecture Integration:

• Console Output: Direct console.log/warn/error for development debugging
• Output Panel: Dedicated VS Code output channel for structured logging
• GUI Notifications: Embedded Gui instance for user-facing messages
• Caller Attribution: Automatic function name resolution through stack analysis

Output Channel Management: Creates and manages a dedicated VS Code output panel ("OUTPUT" tab) for the extension, providing structured log viewing separate from the debug console. This enables users to review extension activity without developer tools access.

Environment Adaptation: Intelligently adapts logging behavior based on extension execution environment:

• Development Mode: Auto-show output panel + console output for immediate feedback
• Production Mode: Hidden output panel + suppressed console to reduce user noise
• Test Mode: Auto-show output panel + console output for debugging tests

Caller Identification System:

• Stack Trace Analysis: Automatic parsing of JavaScript call stack
• Configurable Depth: Adjustable search depth for complex call chains
• Function Name Resolution: Extraction of calling function names
• Anonymous Function Handling: Graceful degradation for complex scenarios

Performance Optimizations:

• Conditional Output: Environment-aware console logging
• Output Channel Reuse: Single channel instance prevents resource leaks
• Efficient Formatting: Optimized string concatenation for high-frequency logging
• Early Debug Filtering: Debug messages bypassed when debug mode disabled

Thread Safety: All logging operations are synchronous and atomic within VS Code's JavaScript environment. No additional synchronization primitives required.

Integration Points:

• Configuration System: Respects debug and extension name settings
• GUI Notifications: Seamless integration with user notification system
• Extension Context: Adapts to VS Code extension lifecycle and environment

Definition at line 555 of file logger.ts.

Member Function Documentation

constructor()

Log::constructor ( context:vscode.ExtensionContext| undefined = undefined, fullyLoaded:boolean = false )

inline

Initializes the logging system with environment detection and auto-display.

Parameters

context

Optional VS Code extension context for environment detection

Sets up the complete logging infrastructure including utility instances, GUI integration, output channel creation, and environment-specific behavior. The context parameter enables intelligent adaptation to development vs production environments.

Development Mode Features:

• Automatically shows the VS Code output panel for immediate log visibility
• Enables console output for real-time debugging feedback
• Provides enhanced debugging experience during extension development

Production Mode Features:

• Output panel remains hidden until manually opened by users
• Console output is suppressed to reduce noise in user environments
• Focuses on GUI notifications for user interaction

Definition at line 588 of file logger.ts.

debug()

Log::debug ( message:string, searchDepth:number| undefined = undefined )

inline

Generates detailed debugging information when debug mode is enabled.

Parameters

message	Debug message with detailed development information
searchDepth	Optional stack depth override for complex calling scenarios

Returns

Void - Completes logging operation synchronously (early return if debug disabled)

Produces verbose debugging output for development and troubleshooting scenarios. All debug output is conditionally generated based on extension configuration, ensuring zero performance impact in production when debug mode is disabled.

Output Format: ‘[timestamp] ExtensionName DEBUG: <CallerFunction> 'message’`

Debug Content Guidelines:

• Variable states and values
• Function entry/exit points
• Algorithm step progression
• Configuration values
• Performance timing data
• Complex object serialization

Conditional Behavior: Debug messages are completely bypassed when debug mode is disabled, including message formatting and caller identification overhead. This ensures optimal performance in production environments.

Output Destinations:

• VS Code output panel (always)
• Browser console with debug styling (development/test mode only)

Debug Console Integration: Uses console.debug() in development environments for specialized debug styling and filtering capabilities. Most browser developer tools allow filtering by log level, making debug messages easy to isolate during troubleshooting.

Note: This method always outputs to the panel but console output depends on installation state, not debug configuration. Debug filtering occurs at the GUI notification level (Gui.debug method) rather than console level.

Definition at line 848 of file logger.ts.

error()

Log::error ( message:string, searchDepth:number| undefined = undefined )

inline

Records critical errors requiring immediate attention or investigation.

Parameters

message	Error description detailing failure conditions and context
searchDepth	Optional stack depth override for complex calling scenarios

Returns

Void - Completes logging operation synchronously

Generates error-level log entries for critical failures, exceptions, and conditions that prevent normal operation. Uses console.error() for proper browser console styling and error tracking integration.

Output Format: ‘[timestamp] ExtensionName ERROR: <CallerFunction> 'message’`

Error Categories:

• File system operation failures
• Network connectivity issues
• Configuration validation errors
• API call failures
• Resource allocation problems
• Unexpected exception conditions

Output Destinations:

• VS Code output panel (always)
• Browser console with error styling (development/test mode only)

Console Error Styling: Error messages use console.error() in development environments, providing red styling and stack trace integration for immediate developer attention. Production environments rely on output panel and GUI notifications instead.

Integration: Error logs are typically paired with GUI error notifications to ensure users are informed of critical issues requiring their attention, regardless of the console output availability.

Definition at line 792 of file logger.ts.

info()

Log::info ( message:string, searchDepth:number| undefined = undefined )

inline

Logs informational messages with automatic caller identification.

Parameters

message	Information message describing successful operations or status updates
searchDepth	Optional stack depth override for complex calling scenarios

Returns

Void - Completes logging operation synchronously

Generates comprehensive informational log entries with full context attribution. Suitable for tracking normal operation flow, successful completions, and non-critical status updates that aid in debugging and monitoring.

Output Format: ‘[timestamp] ExtensionName INFO: <CallerFunction> 'message’`

Output Destinations:

• VS Code output panel (always)
• Browser console (development/test mode only)

Console Output Logic: Console output is enabled only in development and test environments (when extensionInstalled = false) to provide real-time debugging feedback without cluttering the console in production user environments.

Caller Identification: Automatically resolves the calling function name using stack trace analysis. The searchDepth parameter allows adjustment for wrapper functions or complex call chains where the default depth doesn't capture the desired caller.

Definition at line 694 of file logger.ts.

updateInitialisationStatus()

Log::updateInitialisationStatus ( extensionLoaded:boolean = true )

inline

Updates the initialization status and manages output channel lifecycle.

Parameters

extensionLoaded

Boolean indicating if the extension is fully loaded and operational

Manages the complete lifecycle of the logging system's output infrastructure based on extension initialization state. This method coordinates output channel creation/disposal, GUI notification availability, and development environment auto-display behavior.

Initialization Sequence (extensionLoaded = true):

1. Updates internal loaded state flag
2. Enables GUI notifications through Gui.updateLoadStatus()
3. Creates dedicated VS Code output channel for extension logs
4. Auto-displays output panel in development environments for immediate visibility

Shutdown Sequence (extensionLoaded = false):

1. Updates internal loaded state flag to false
2. Disables GUI notifications to prevent orphaned messages
3. Properly disposes of existing output channel to prevent resource leaks
4. Clears output channel reference for garbage collection

Resource Management:

• Output Channel: Created using CodeConfig.get("moduleName") for consistent naming
• Memory Safety: Proper disposal prevents VS Code output channel accumulation
• Development UX: Auto-show in development mode for immediate log access

State Coordination: Ensures both Log and Gui classes maintain synchronized initialization state, preventing inconsistent behavior between console logging and GUI notifications.

Updates installation state for dynamic environment changes with UI adaptation

Parameters

context

Updated VS Code extension context

Returns

Void - Updates state and UI synchronously

Allows runtime updates to the installation state detection, useful when the extension context becomes available after initial logger creation or when the execution environment changes during extension lifecycle.

Dynamic UI Adaptation: When switching to development mode (extensionInstalled = false), automatically displays the VS Code output panel to provide immediate visibility of log output. This ensures developers have instant access to debugging information when the environment context changes during extension execution.

Use Cases:

• Extension context becomes available after early initialization
• Runtime environment detection updates
• Development workflow transitions
• Testing environment changes

Definition at line 622 of file logger.ts.

warning()

Log::warning ( message:string, searchDepth:number| undefined = undefined )

inline

Records warning conditions requiring attention but not blocking execution.

Parameters

message	Warning description of potential issues or unusual conditions
searchDepth	Optional stack depth override for complex calling scenarios

Returns

Void - Completes logging operation synchronously

Generates warning-level log entries for conditions that may require attention but don't prevent continued operation. Includes automatic caller attribution and uses console.warn() for appropriate browser console styling.

Output Format: ‘[timestamp] ExtensionName WARNING: <CallerFunction> 'message’`

Use Cases:

• Deprecated API usage warnings
• Configuration anomalies
• Performance degradation notices
• Resource availability concerns
• Fallback behavior activations

Output Destinations:

• VS Code output panel (always)
• Browser console with warning styling (development/test mode only)

Console Output Behavior: Warning messages are sent to console.warn() only in development and test environments to maintain clean console output in production while providing appropriate styling (yellow color) for developer attention during debugging.

Definition at line 740 of file logger.ts.

Field Documentation

__pad2__

Gui Log::__pad2__

GUI notification logger instance for user-facing messages.

Definition at line 561 of file logger.ts.

---

The documentation for this class was generated from the following file:

• vscode/asperheader/src/modules/logger.ts