User Diagnostics Reports: Solving app bugs faster with AI Agents

Developer Aviel Grossfeld released an open-source library called Diagnostics that generates detailed HTML reports to help solve app bugs faster by attaching system logs, session details, and device info to user support emails. The tool, used by apps from companies like WeTransfer, eliminates back-and-forth questioning by automatically including OS version, app version, language, storage, and device type, with JavaScript-based filtering for error logs. Grossfeld also introduced AI agent support for Diagnostics, enabling automated analysis of user issues through agentic development.

A user diagnostics report that helps you solve bugs and improve user support at the same time. I’ve been writing apps since 2009, and the Diagnostics repository is an outcome of all that experience. Used by major apps from companies like WeTransfer, it has proven its value time after time. I’ve seen consistent inefficiency at many companies: a user reports a bug, and the first thing you need to ask is which version they’re running on. This is just one of the example questions one might ask. I’ve leveled up the quality of support for my developer tool, RocketSim https://www.rocketsim.app , by introducing Diagnostics Reports. With Diagnostics supporting agentic development, it’s becoming even easier to analyze user issues. Share your AI agent’s work with your team https://display.dev/?utm source=swiftlee&utm medium=newsletter&utm campaign=swiftlee sponsor Your agent generates a report, dashboard, or prototype as HTML or Markdown. display.dev turns it into a secure URL your team can open with their existing work login, comment on inline, and send back to any agent through MCP. Works with Cursor, Codex, Claude Code, and more. No viewer accounts, no seat management, no vendor lock-in. Learn more https://display.dev/?utm source=swiftlee&utm medium=newsletter&utm campaign=swiftlee sponsor . The common issue with App Support channels You’ve built your app, set up a support channel, and you’re receiving more and more feedback. This is all great, since feedback means an opportunity for improvement. However, many of the requests you get also involve exceptional bugs that are hard to reproduce: you need more information. Instead of solving the bug right away, you first need to go back and forth with the user to get more details. It’s likely you’re asking questions like: - What OS version are you using? - Did you update to the latest version of the app? While there are many solutions that give you these answers straightaway, I didn’t find any solution that would combine this with smart insights, system- and debug logs, combined with all kinds of session details. Introducing an Open Source library: Diagnostics I’m happy to introduce you to my open source library, Diagnostics https://github.com/AvdLee/Diagnostics . It’s built on my experience building apps and supporting bug fixes since 2009. The library offers an in-app way to report issues and attaches a so-called Diagnostics Report: a detailed HTML file. Whenever a user shares feedback within the app, they can write an email and share their story. The detailed HTML report will be attached and will provide the necessary technical information. A detailed look at the standard HTML report The standard HTML report contains answers to common questions, such as the OS and app version. It also provides insights into system details, such as language, storage, and device type. The session logs are where the real magic happens. You can see this as your Xcode console: it contains all the system and debug logs you’re used to when debugging. This is extremely helpful as a developer, as you can narrow down an issue in detail. The HTML report even offers JavaScript-based filtering of the system logs, so you can directly look into errors: In this case, for RocketSim, I could tell the user we’re not supporting Stage Manager yet. With just one email reply, I’ve been able to inform the user and reference the related GitHub issue. FREE 5-Day Email Course: The Swift Concurrency Playbook A FREE 5-day email course revealing the 5 biggest mistakes iOS developers make with with async/await that lead to App Store rejections And migration projects taking months instead of days even if you've been writing Swift for years A better collaboration with your Support team What’s great about these diagnostic reports is that they’re consistent. Each user who reaches out will provide the same technical information. I’ve been working together with support teams and trained them to read these reports themselves. This is another friction point solved, making the support process more streamlined. The support team does not have to bother developers with each support issue, and developers can maintain their focus and productivity. Before a support agent reaches out to a developer, they’ve at least ensured users are using the latest app and/or OS version. Known issues related to a specific error log could be detected by a support agent from the session logs. This is a win-win in many parts: - Users get a better answer, more quickly - Support agents are less dependent on input from developers - Developers can stay focused on writing code instead of helping out on support tickets But that’s not all: we still had to inform support agents of known issues. If your support team is big, this can quickly become cumbersome. Therefore, we’ve introduced a feature called Smart Insights . Using Smart Insights Smart insights are basically insights after processing logs. Diagnostics allows you to process each log line and return a Smart Insight accordingly: struct SmartInsightsProvider: SmartInsightsProviding { func smartInsights for chapter: DiagnosticsChapter - SmartInsightProviding { guard let html = chapter.diagnostics as? HTML else { return } if html.errorLogs.contains where: { $0.contains "Window is too small, likely due to Stage Manager switch" } { return SmartInsight name: "Stage Manager Issue Detected", result: .warn message: "An error was found regarding missing support for Stage Manager. Inform the user about this if needed." } return } } A dedicated report chapter will show up with the Stage Manager issue insight. The support agent no longer has to navigate through all sessions to find out about the user’s issue. By default, standard Smart Insights are provided: UpdateAvailableInsight uses your bundle identifier to fetch the latest available app version. An insight will be shown whether an update is available to the user or not. DeviceStorageInsight shows whether the user is out of storage or not An example smart insights section could look as follows: Solving user bugs faster using agents A user diagnostics report becomes even more valuable when an agent can read it directly. Diagnostics 7.0 keeps the same single HTML attachment you could already send to your support team, but now embeds structured JSON data inside the report. This means your users can still share a report as before, while agents can inspect the underlying data without having to parse rendered HTML. The report contains structured chapters, session metadata, log events, and crash diagnostics. In other words, the information you need to solve a user-specific bug becomes easier to parse and reason about. An agent skill for parsing Diagnostics For token-efficient report parsing, I’ve created a dedicated agent skill. This skill knows how to handle HTML reports by reading the embedded structured JSON rather than parsing the rendered HTML. Agents become much more useful when they have access to both your project’s code and the diagnostics report, since they can connect user logs directly to the implementation. For the easiest setup, install the analyzer skill with npx skills : npx skills add https://github.com/AvdLee/Diagnostics --skill diagnostics-report-analyzer-skill See agent-skill-install-instructions.md https://github.com/AvdLee/Diagnostics/blob/main/agent-skill-install-instructions.md for Claude, Cursor, OpenAI-compatible tools, pi, and manual installation options. Exporting as JSON instead of HTML The default API still creates a user-friendly HTML report: js let report = await DiagnosticsReporter.create If your support workflow consumes structured data directly, you can create a standalone JSON report instead: js let report = await DiagnosticsReporter.create format: .json This allows you to send a user report based on Diagnostics to your custom server or to Linear and attach it to an issue. No need to email the HTML report: you’ll work directly with the structured JSON instead. This makes it a great solution for AI-optimized workflows. Can I see Diagnostics in action? Well, you’re an app developer, so I invite you to install RocketSim from the Mac App Store https://apps.apple.com/app/apple-store/id1504940162?pt=117264678&ct=diagnostics report article&mt=8 and report an issue from the status bar menu. Diagnostics supports iOS, iPadOS, and macOS. This is a win-win, as RocketSim offers 30+ utilities for Xcode’s Simulator Share your AI agent’s work with your team https://display.dev/?utm source=swiftlee&utm medium=newsletter&utm campaign=swiftlee sponsor Your agent generates a report, dashboard, or prototype as HTML or Markdown. display.dev turns it into a secure URL your team can open with their existing work login, comment on inline, and send back to any agent through MCP. Works with Cursor, Codex, Claude Code, and more. No viewer accounts, no seat management, no vendor lock-in. Learn more https://display.dev/?utm source=swiftlee&utm medium=newsletter&utm campaign=swiftlee sponsor . Conclusion Diagnostics is a game-changer when it comes to offering support in apps. The HTML report provides answers to common questions and reduces friction. As a developer, it’s likely you’ll be less annoyed by support agents. The framework offers much more flexibility, so I would like you to look into the open-source repository’s README https://github.com/AvdLee/Diagnostics . If you like to learn more tips on debugging, check out the debugging category page https://www.avanderlee.com/category/debugging/ . Feel free to contact me /cdn-cgi/l/email-protection fe9d91908a9f9d8abe9f889f909a9b8c929b9bd09d9193 or tweet to me on Twitter https://www.twitter.com/twannl if you have any additional tips or feedback. Thanks