Skip to content

LOGGING_TRANSITION.md

Latest commit

 

History

History
145 lines (103 loc) · 5.02 KB

LOGGING_TRANSITION.md

File metadata and controls

145 lines (103 loc) · 5.02 KB

macwmfx Logging System Transition

Overview

Successfully completed the transition from NSLog to Apple's modern os_log system for better performance, categorization, and system integration.

Changes Made

1. Enhanced Logging System (src/shared/macwmfx_logging.h/m)

  • New Categories Added:

    • macwmfx_log_titlebar - For titlebar-related operations
    • macwmfx_log_traffic_lights - For traffic light controls
    • macwmfx_log_shadow - For window shadow operations
    • macwmfx_log_outline - For window outline/border operations
    • Existing: macwmfx_log_server, macwmfx_log_client, macwmfx_log_config, macwmfx_log_window, macwmfx_log_hook, macwmfx_log_cli, macwmfx_log_general

  • Convenience Macros:

    • MACWMFX_LOG_INFO(category, ...) - For informational messages
    • MACWMFX_LOG_ERROR(category, ...) - For error messages
    • MACWMFX_LOG_DEBUG(category, ...) - For debug messages
    • MACWMFX_LOG_WARNING(category, ...) - For warnings
    • MACWMFX_LOG_FAULT(category, ...) - For critical faults

  • Legacy Compatibility:

    • DLog() and VLog() macros now use os_log instead of NSLog
    • Maintains backward compatibility for existing code

2. Updated Files with os_log Implementation

Core Components

  • CLI Tool (src/modules/CLITool.m)

    • Replaced NSLog with MACWMFX_LOG_ERROR for pipe errors
    • Added logging initialization in main()

  • Main Module (src/main/macwmfx.m)

    • Added comprehensive logging for module lifecycle
    • Initialization, start/stop, configuration loading
    • Module loading/unloading tracking

  • Client (src/client/macwmfx_client.m)

    • Added logging initialization
    • Client connection and response logging

Window Features

  • Window Example (src/modules/windows/features/window_example.m)

    • Converted all NSLog calls to appropriate os_log categories
    • Used macwmfx_log_window, macwmfx_log_shadow, macwmfx_log_titlebar

  • Custom Title (src/modules/windows/features/windowTitlebar/ForceCustomTitle.m)

    • Error handling with MACWMFX_LOG_ERROR
    • Info logging with MACWMFX_LOG_INFO
    • Used privacy-aware format strings (%{public}@)

  • Titlebar Controls (src/modules/windows/features/windowTitlebar/DisableTitleBars.m, TitlebarAesthetics.m)

    • Initialization and state change logging
    • Proper categorization with macwmfx_log_titlebar

  • Traffic Lights (src/modules/windows/features/windowTrafficLights/disableTrafficLights.m)

    • Visibility state changes
    • Used macwmfx_log_traffic_lights category

  • Window Shadows (src/modules/windows/features/windowShadow/DisableWindowShadow.m)

    • Shadow state management logging
    • Configuration change tracking
    • Used macwmfx_log_shadow category

3. Updated Global Headers

  • macwmfx_globals.h
    • Removed NSLog-based DLog/VLog macros
    • Added reference to new os_log system
    • Fixed include path for logging header

Benefits of os_log vs NSLog

Performance

  • Lazy Evaluation: os_log only formats strings when logs are actually collected
  • Efficient Storage: Binary format reduces disk I/O
  • Lower CPU Overhead: Especially for debug/verbose logging

System Integration

  • Console.app Integration: Logs appear properly categorized in Console
  • Unified Logging: Integrates with system-wide logging infrastructure
  • Log Streaming: Works with log stream command for real-time monitoring

Privacy & Security

  • Privacy-Aware Formatting: %{public}@ vs %@ for sensitive data
  • Automatic Redaction: Private data automatically redacted in logs
  • Structured Logging: Better parsing and analysis capabilities

Debugging & Monitoring

  • Categorized Logging: Easy filtering by subsystem and category
  • Log Levels: Proper debug, info, error, fault level separation
  • Persistence: Logs persist across reboots and crashes

Usage Examples

Basic Logging

MACWMFX_LOG_INFO(macwmfx_log_window, "Window updated successfully");
MACWMFX_LOG_ERROR(macwmfx_log_config, "Failed to load configuration: %{public}@", error);

Legacy Compatibility

DLog(@"Debug message");  // Now uses os_log_info
VLog(@"Verbose message"); // Now uses os_log_debug

Viewing Logs

# Real-time log streaming
log stream --predicate 'subsystem == "com.aspauldingcode.macwmfx"'

# Filter by category
log stream --predicate 'subsystem == "com.aspauldingcode.macwmfx" AND category == "window"'

# CLI tool log observation
macwmfx --observe-logs

Migration Status

✅ Complete - All NSLog calls converted to os_log ✅ Tested - Compilation successful across all updated files ✅ Backward Compatible - Existing DLog/VLog macros still work ✅ Categorized - Proper logging categories for different subsystems ✅ Initialized - Logging system properly initialized in all entry points

Next Steps

  • Monitor log output during runtime testing
  • Adjust log levels as needed for production vs debug builds
  • Consider adding more specific categories for new features
  • Implement log rotation/cleanup policies if needed