How to Debug Palmier Pro Applications: OS-Level Crashes, Categorized Logs, and Xcode Integration

Palmier Pro combines OS-level crash handlers that capture signals and exceptions, a categorized logging system built on os.Logger, SwiftUI preview diagnostics, and standard Xcode tooling to provide comprehensive debugging visibility across the entire application stack.

The palmier-io/palmier-pro repository provides a robust debugging infrastructure designed for professional media applications. Understanding how to debug Palmier Pro applications requires familiarity with its multi-layered approach that spans from signal-handling crash capture to high-level SwiftUI instrumentation. This guide examines the four core debugging layers implemented in the source code: the CrashHandler, CategoryLog subsystems, preview diagnostics, and Xcode integration points.

OS-Level Crash Handling and Signal Capture

When the application launches, Log.bootstrap() immediately installs a CrashHandler that intercepts uncaught Objective-C exceptions and fatal Unix signals. The handler registration occurs in Sources/PalmierPro/Utilities/Log.swift at lines 42-45, where the system calls CrashHandler.install() before UI initialization.

The handler opens a dedicated file descriptor to ~/Library/Logs/PalmierPro/crash.log and registers signal handlers for SIGSEGV, SIGABRT, and other fatal signals using NSSetUncaughtExceptionHandler. Implementation details at lines 90-104 in Log.swift show how the system uses backtrace and backtrace_symbols_fd to generate a safe stack trace from within the signal handler context.

To inspect crash logs after termination:

cat ~/Library/Logs/PalmierPro/crash.log

Categorized Logging Runtime

Palmier Pro wraps Apple's os.Logger with a CategoryLog system that organizes output by functional subsystem. Each category exposes methods like notice, warning, error, fault, and debug that automatically write to both the unified logging system and stderr for immediate console visibility (lines 58-85 in Log.swift).

Initializing the Logger

Call Log.bootstrap() from your app entry point immediately after launch, as implemented in Sources/PalmierPro/App/main.swift:

@main
struct PalmierProApp {
    static func main() {
        Log.bootstrap()  // Installs crash handler and configures logging
        Telemetry.start()
        // UI initialization follows...
    }
}

Category-Specific Log Instances

Access pre-configured loggers through static properties on Log:

Log.editor.notice("User opened file", metadata: ["id": fileId])
Log.preview.debug("Seek state invalidated to \(newState)")
Log.app.warning("Memory pressure detected")

Each category routes to a specific os.Logger subsystem, enabling filtered searches in Console.app using the category identifier (e.g., "editor", "preview", "app").

Telemetry Integration

When enabled in Sources/PalmierPro/Settings/PrivacyPane.swift, the Telemetry system bridges log calls to remote error tracking. Methods like Log.editor.warning(_:telemetry:data:) dispatch breadcrumbs via Telemetry.breadcrumb while maintaining local console output. Disable telemetry during intensive local debugging to eliminate network latency:

Telemetry.isEnabled = false

SwiftUI Preview Diagnostics

The preview infrastructure leverages the same logging system for canvas debugging. In Sources/PalmierPro/Preview/VideoEngine.swift (line 133), the engine emits diagnostic messages through Log.preview when resetting seek states or handling geometry changes.

For UI debugging, TransformOverlayView.swift logs warnings about collapsed video rectangles using the preview category, helping identify layout issues in the SwiftUI canvas without running the full application.

Xcode Debugging Tools Integration

Beyond application-specific logging, Palmier Pro supports standard Xcode instrumentation:

Breakpoints and Exceptions — Enable "All Objective-C Exceptions" in Xcode's breakpoint navigator to catch issues before they reach the CrashHandler, pausing execution at the throw site rather than the signal handler.

LLDB Console Commands — When paused, use po variableName to inspect Swift objects or expression to modify state at runtime. The crash handler's log file remains accessible via cat ~/Library/Logs/PalmierPro/crash.log while LLDB is active.

Instruments Profiling — Use "Time Profiler" or "Metal System Trace" templates to analyze performance in VideoEngine.swift and rendering components. The categorized logs provide markers that correlate with Instruments timelines.

View Hierarchy Debugging — Pause the app and select "Debug View Hierarchy" to visualize SwiftUI layout alongside the geometry warnings emitted by Log.preview.

Summary

• CrashHandler captures uncaught exceptions and signals (SIGSEGV, SIGABRT) to ~/Library/Logs/PalmierPro/crash.log during Log.bootstrap() in Sources/PalmierPro/Utilities/Log.swift
• CategoryLog provides subsystem-specific loggers (Log.editor, Log.preview) that mirror to stderr and support telemetry integration via Sources/PalmierPro/Telemetry/Telemetry.swift
• SwiftUI previews use Log.preview for canvas diagnostics, as seen in VideoEngine.swift line 133 and TransformOverlayView.swift
• Xcode tools including exception breakpoints, LLDB, and Instruments work seamlessly with the built-in logging infrastructure to debug Palmier Pro applications at every layer

Frequently Asked Questions

Where are Palmier Pro crash logs stored?

Crash logs are written to ~/Library/Logs/PalmierPro/crash.log by the CrashHandler installed during Log.bootstrap(). The file contains backtraces generated by backtrace_symbols_fd along with exception names and reasons, readable via Console.app or command-line tools.

How do I enable categorized logging in my Palmier Pro application?

Call Log.bootstrap() in your App.main entry point before UI initialization, as implemented in Sources/PalmierPro/App/main.swift. This configures the CategoryLog instances and installs signal handlers. Use Log.<category>.<level>() methods to emit messages that automatically route to both the unified logging system and standard error output.

What is the difference between Log.preview and Log.editor categories?

Log.preview targets the video preview and rendering subsystem (used in VideoEngine.swift and TransformOverlayView.swift), while Log.editor handles asset manipulation and timeline operations. Both use the same underlying os.Logger infrastructure but with different category identifiers, allowing you to filter Console.app output to isolate specific functional areas.

Can I use Palmier Pro's crash handler alongside Xcode's debugger?

Yes. Set breakpoints on "All Objective-C Exceptions" in Xcode to catch issues before they reach the signal handler. When running outside Xcode, the CrashHandler provides the safety net, writing stack traces to disk for post-mortem analysis. The two systems operate at different layers and do not conflict.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}