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

> Debug Palmier Pro apps effectively with OS-level crash handlers, categorized os.Logger logs, SwiftUI preview diagnostics, and Xcode integration for complete visibility.

- Repository: [Palmier/palmier-pro](https://github.com/palmier-io/palmier-pro)
- Tags: how-to-guide
- Published: 2026-06-23

---

**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`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/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:

```bash
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`](https://github.com/palmier-io/palmier-pro/blob/main/Log.swift)).

### Initializing the Logger

Call `Log.bootstrap()` from your app entry point immediately after launch, as implemented in [`Sources/PalmierPro/App/main.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/App/main.swift):

```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`:

```swift
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`](https://github.com/palmier-io/palmier-pro/blob/main/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:

```swift
Telemetry.isEnabled = false

```

## SwiftUI Preview Diagnostics

The preview infrastructure leverages the same logging system for canvas debugging. In [`Sources/PalmierPro/Preview/VideoEngine.swift`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/Telemetry/Telemetry.swift)
- **SwiftUI previews** use `Log.preview` for canvas diagnostics, as seen in [`VideoEngine.swift`](https://github.com/palmier-io/palmier-pro/blob/main/VideoEngine.swift) line 133 and [`TransformOverlayView.swift`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/VideoEngine.swift) and [`TransformOverlayView.swift`](https://github.com/palmier-io/palmier-pro/blob/main/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.