How do I filter out sensitive user data in Diagnostics reports?

Implement the DiagnosticsReportFilter protocol to create custom filters. For example, you can exclude specific UserDefaults keys or app metadata by checking key-value pairs in the diagnostics dictionary, as shown in the README's example.

Can I use Diagnostics on macOS?

Yes, Diagnostics natively supports macOS via NSSharingService for report sharing. The API is consistent with iOS, allowing cross-platform diagnostic reporting with minimal code changes, as demonstrated in the usage section.

How to add custom error logs to Diagnostics?

Use DiagnosticsLogger.log(error:) for errors or log(message:) for strings. Ensure errors conform to LocalizedError for better descriptions in reports, and set up the logger early in the app lifecycle to capture all logs.

Diagnostics vs Crashlytics: which is better for iOS?

Diagnostics is best for in-app, user-initiated report sharing with privacy controls and HTML formatting, while Crashlytics excels at automatic crash reporting and cloud analytics. Use Diagnostics for support workflows; Crashlytics for development monitoring.

What smart insights come with Diagnostics?

Default insights include UpdateAvailableInsight for checking app version updates and DeviceStorageInsight for storage warnings. You can extend these by implementing SmartInsightsProviding to parse logs and add custom insights based on your app's data.

How to install Diagnostics with Swift Package Manager?

Add the package URL in Xcode's Swift Packages or in Package.swift, specifying dependencies and targets. The library integrates seamlessly with SPM, as outlined in the installation section, making dependency management straightforward.

Open-Awesome

Diagnostics

MITSwift6.0.1

A Swift library for generating and sharing diagnostics reports from iOS, iPadOS, and macOS apps to improve bug-fixing workflows.

GitHub

1.2k stars66 forks0 contributors

What is Diagnostics?

Diagnostics is a Swift library that enables developers to generate comprehensive diagnostic reports from their iOS, iPadOS, and macOS applications. It collects app metadata, system logs, and custom data, allowing users to easily share these reports with support teams to streamline bug identification and resolution.

Target Audience

iOS, iPadOS, and macOS developers who need to integrate diagnostic reporting and logging into their apps for improved debugging and user support workflows.

Value Proposition

Developers choose Diagnostics for its seamless integration with native Apple frameworks, extensible architecture for custom data and insights, and built-in privacy features to filter sensitive information, making it a robust tool for enhancing support efficiency.

Overview

Allow users to easily share Diagnostics with your support team to improve the flow of fixing bugs.

Use Cases

Best For

Adding in-app diagnostic reporting for user support
Collecting system logs and app metadata for debugging
Filtering sensitive data from diagnostic reports
Extending logging capabilities with custom insights
Sharing diagnostic reports via email on iOS and macOS
Visualizing directory structures in diagnostic outputs

Not Ideal For

Projects built with cross-platform frameworks like React Native or Flutter that require unified diagnostic tools across multiple platforms
Apps needing real-time, continuous error monitoring or cloud-based crash reporting instead of user-triggered report generation
Teams that prefer integrated cloud services like Firebase Crashlytics or Sentry for automated error tracking and analytics
Simple projects where basic console logging or built-in iOS/macOS tools like os_log suffice without formatted HTML reports

Pros & Cons

Pros

Integrated Email Sharing

Seamlessly attaches HTML reports to MFMailComposeViewController on iOS or NSSharingService on macOS, streamlining user support communication directly from the app.

Extensible Reporting

Supports custom reporters via the DiagnosticsReporting protocol and directory tree visualizations, allowing developers to tailor data collection to specific app needs.

Smart Insights Automation

Includes built-in insights like low storage warnings and app version checks, with a flexible framework for adding custom automated analysis based on report data.

Privacy-Centric Filtering

Provides DiagnosticsReportFilter to exclude sensitive data such as UserDefaults keys, ensuring reports comply with privacy regulations without manual intervention.

Cons

Mail Configuration Dependency

Relies on MFMailComposeViewController, which fails on iOS devices without mail accounts configured; the fallback is limited to saving files on the simulator, hindering real-world testing.

Platform Lock-In

Exclusive to Swift and Apple's iOS, iPadOS, and macOS ecosystems, making it unsuitable for projects using other languages or cross-platform development stacks.

Setup Complexity

Requires early initialization in app lifecycle (e.g., in didLaunchWithOptions) and careful configuration of reporters and filters, adding overhead for simpler logging needs.

Frequently Asked Questions

Related Projects

CocoaLumberjack

A fast & simple, yet powerful & flexible logging framework for macOS, iOS, tvOS, watchOS and visionOS

Stars13,327

Forks2,278

Last commit4 days ago

Pulse

Network logger for Apple platforms

Stars7,060

Forks369

Last commit10 days ago

SwiftyBeaver

Convenient & secure logging during development & release in Swift 4 & 5

Stars6,066

Forks495

Last commit1 year ago

XCGLogger

A debug log framework for use in Swift projects. Allows you to log details to the console (and optionally a file), just like you would have with NSLog() or print(), but with additional information, such as the date, function name, filename and line number.

Stars3,987

Forks476