Logging & Diagnostics

AppPorts has a built-in logging system that records key events, migration operations, system information, and error details during app runtime. When issues arise, you can export a diagnostic package and submit it to the project Issues for troubleshooting.

Logged Content

Startup Session Information

The following information is recorded each time the app starts:

Item	Description
Session ID	Unique identifier for this run (8-character UUID prefix)
Process ID	System process identifier
Bundle ID	App identifier
App Language	Currently selected language code
System Locale	System locale identifier
Timezone	Current timezone identifier
Preferred Language List	System preferred language order

System Diagnostic Information

Item	Description
App Version	Version number and build number
macOS Version	System version and marketing name (e.g., "macOS Sequoia 15.x")
Device Model	Model and friendly name (e.g., "MacBook Pro (14-inch, M3 Pro, 2023)")
Processor Info	Brand string, core count, active core count
Physical Memory	Total memory

External Storage Information

Recorded when selecting an external storage volume:

Item	Description
Volume Name	Storage volume name
Total Capacity / Available Space	Storage space information
File System Format	e.g., APFS, HFS+, exFAT, etc.
Interface Protocol	USB, Thunderbolt, NVMe/SATA
Device Speed	Transfer rate information
Block Size	Storage block size
Volume UUID	Storage volume unique identifier

Migration Operation Events

Each migration operation generates a unique operation ID (e.g., data-migrate-ABCD1234), recording:

• Operation start and end
• Progress of each step (copy, delete original directory, create symbolic link, rollback)
• Path state snapshots before and after steps (existence, permissions, size, symlink target, immutable flag)
• Residual migration data detection and auto-recovery
• File copy progress, errors, and retries

Migration Performance Reports

Item	Description
App Name	Migrated app name
Data Size	Migrated data volume
Duration	Migration duration (seconds)
Transfer Speed	Transfer rate (MB/s)
Source Path / Destination Path	Migration start and end paths

Error Details

Error logs contain structured information:

Field	Description
Error Description	Human-readable error description
Error Type / Domain / Code	NSError structured information
Failure Reason	Detailed failure reason
Recovery Suggestion	System-provided recovery suggestion
File Path	Affected file path
Underlying Error	Nested error recorded recursively

Operation Summary

Each migration operation generates an OperationSummaryRecord, retaining the most recent 100 records:

Field	Description
operationID	Operation unique identifier
category	Operation category (app_move, data-migrate, file-copy, etc.)
result	Result (success, failed, rolled_back, success_with_warning)
errorCode	Error code (if any)
startedAt / endedAt	Start and end time
durationMs	Duration (milliseconds)

Log Configuration

Storage Location

Default log path:

~/Library/Application Support/AppPorts/AppPorts_Log.txt

Can be customized via:

• Menu bar → Logs → Set Log Location
• Settings → Logging Settings → Custom Path

Log Format

[2026-05-08 09:30:00] [INFO] [session:a1b2c3d4] [pid:12345] App started
[2026-05-08 09:30:01] [DIAG] [session:a1b2c3d4] [pid:12345]   app_version: 1.6.1 (123)
[2026-05-08 09:30:05] [PERF] [session:a1b2c3d4] [pid:12345]   Migration complete: 2.3 GB, 45.2 MB/s, 52.1s

Log Levels

Level	Description
INFO	General information
ERROR	Error information (with structured error details)
DIAG	System diagnostic information
DISK	External storage volume information
PERF	Migration performance report
TRACE	Low-level path state and folder monitoring
DEBUG	Debug information (size calculation, nested directory checks)
WARN	Warnings (residual migration data, recovery mode)

Log Rotation

• Default max size: 2 MB (configurable: 1 MB, 5 MB, 10 MB, 50 MB, 100 MB)
• Auto-truncation when exceeded: Discards older half of lines, keeps newer half

Export Diagnostic Package

When issues arise requiring feedback, please export a diagnostic package and attach it to the Issue.

Export Methods

Method 1: Menu Bar

1. Click Menu bar → Logs → Export Diagnostic Package
2. Choose save location
3. System automatically generates a .zip file and opens in Finder

Method 2: Settings Page

1. Open AppPorts → Settings (upper right corner)
2. Find the "Logging Settings" section
3. Click "Export Diagnostic Package" button
4. Choose save location

Diagnostic Package Contents

The exported AppPorts-Diagnostic-<datetime>.zip contains:

File	Format	Description
diagnostic-summary.json	JSON	Metadata (session ID, version, locale, timezone, etc.)
diagnostic-summary.txt	Plain text	Human-readable diagnostic summary
recent-operations.json	JSON	Most recent 100 operation records
recent-failures.json	JSON	Most recent 20 failed/warning operations
AppPorts_Log.share-safe.txt	Plain text	Complete log (redacted)

Privacy Protection

Log files in the diagnostic package are redacted:

Original Content	Replaced With
User home directory path (e.g., /Users/john)	/Users/<redacted-user>
External storage volume name (e.g., /Volumes/MyDrive)	/Volumes/<redacted-volume>
$HOME full path	~

Submitting Issues

After obtaining the diagnostic package, follow these steps to submit:

1. Visit the project Issues page
2. Click "New Issue," select the Bug report template
3. Describe the issue and reproduction steps
4. Drag the diagnostic .zip file to the attachment area to upload
5. Submit the Issue

💡 Improve Feedback Efficiency

Submitting Issues with diagnostic packages can significantly speed up issue resolution. The diagnostic package contains complete operation history, error details, and system environment information, allowing developers to reproduce and analyze issues without repeated communication.