Skip to content
Back to search

diagnostics-report-analyzer-skill

MarketplaceWorks with Claude CodeGitHub

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/avdlee--diagnostics/badge.svg)](/listings/avdlee--diagnostics)

HTML

<a href="/listings/avdlee--diagnostics"><img src="/api/listings/avdlee--diagnostics/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](agent-skill-install-instructions.md) for Claude, Cursor, OpenAI-compatible tools, pi, and manual installation options.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 47 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/marketplace/marketplace.schema.json",
  3. "name": "diagnostics-report-analyzer-skill",
  4. "version": "1.0.0",
  5. "owner": {
  6. "name": "Antoine van der Lee",
  7. "email": "contact@avanderlee.com"
  8. },
  9. "metadata": {
  10. "description": "Analyze AvdLee Diagnostics HTML reports using embedded JSON first, with legacy HTML report fallback."
  11. },
  12. "plugins": [
  13. {
  14. "name": "diagnostics-report-analyzer",
  15. "description": "Support and debugging guidance for AvdLee Diagnostics reports, session logs, app metadata, and MetricKit diagnostics.",
  16. "repository": "https://github.com/AvdLee/Diagnostics",
  17. "version": "1.0.0",
  18. "author": {
  19. "name": "Antoine van der Lee",
  20. "email": "contact@avanderlee.com"
  21. },
  22. "license": "MIT",
  23. "category": "development",
  24. "keywords": [
  25. "diagnostics",
  26. "support",
  27. "debugging",
  28. "logs",
  29. "html-report",
  30. "json",
  31. "swift",
  32. "ios",
  33. "macos"
  34. ],
  35. "tags": [
  36. "diagnostics",
  37. "support",
  38. "debugging",
  39. "logs",
  40. "swift",
  41. "ios",
  42. "macos"
  43. ],
  44. "source": "./"
  45. }
  46. ]
  47. }
README.md · README · 444 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img width="900px" src="Assets/banner.jpg">
  3. </p>
  4. <p align="center">
  5. <img src="https://img.shields.io/badge/language-swift6.0-f48041.svg?style=flat"/>
  6. <img src="https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat"/>
  7. <img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat"/>
  8. </p>
  9. | Example mail composer | Example Report |
  10. | --- | --- |
  11. | ![](Assets/example_composed_email.jpeg) | ![](Assets/example_report.png) |
  12. Diagnostics is a library written in Swift which makes it really easy to share Diagnostics Reports to your support team.
  13. - [Features](#features)
  14. - [Requirements](#requirements)
  15. - [Usage](#usage)
  16. - [Agent-friendly reports](#agent-friendly-reports)
  17. - [Install the Agent Skill](#install-the-agent-skill)
  18. - [Using a custom UserDefaults type](#using-a-custom-userdefaults-type)
  19. - [Filtering out sensitive data](#filtering-out-sensitive-data)
  20. - [Adding your own custom logs](#adding-your-own-custom-logs)
  21. - [Adding your own custom report](#adding-your-own-custom-report)
  22. - [Smart insights](#smart-insights)
  23. - [Communication](#communication)
  24. - [Installation](#installation)
  25. - [Release Notes](#release-notes)
  26. - [License](#license)
  27. ## Features
  28. The library allows to easily attach the Diagnostics Report as an attachment to the `MFMailComposeViewController`.
  29. - [x] Integrated with the `MFMailComposeViewController`
  30. - [x] Default reporters include:
  31. - App metadata
  32. - System metadata
  33. - System logs divided per session
  34. - [x] Possibility to filter out sensitive data using a `DiagnosticsReportFilter`
  35. - [x] A custom `DiagnosticsLogger` to add your own logs
  36. - [x] Agent-friendly single-file HTML reports with embedded structured JSON or standalone JSON output
  37. - [x] Smart insights like _"⚠️ User is low on storage"_ and *"✅ User is using the latest app version"*
  38. - [x] Flexible setup to add your own smart insights
  39. - [x] Flexible setup to add your own custom diagnostics
  40. - [x] Native cross-platform support, e.g. iOS, iPadOS and macOS
  41. ## Usage
  42. The default report already contains a lot of valuable information and could be enough to get you going.
  43. Make sure to set up the `DiagnosticsLogger` as early as possible to catch all the system logs, for example in the `didLaunchWithOptions`:
  44. ```swift
  45. func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  46. do {
  47. try DiagnosticsLogger.setup()
  48. } catch {
  49. print("Failed to setup the Diagnostics Logger")
  50. }
  51. return true
  52. }
  53. ```
  54. Then, simply show the `MFMailComposeViewController` using the following code:
  55. ```swift
  56. import UIKit
  57. import MessageUI
  58. import Diagnostics
  59. class ViewController: UIViewController {
  60. @IBAction func sendDiagnostics(_ sender: UIButton) {
  61. Task { @MainActor in
  62. /// Create the report.
  63. let report = await DiagnosticsReporter.create()
  64. guard MFMailComposeViewController.canSendMail() else {
  65. /// For debugging purposes you can save the report to desktop when testing on the simulator.
  66. /// This allows you to iterate fast on your report.
  67. report.saveToDesktop()
  68. return
  69. }
  70. let mail = MFMailComposeViewController()
  71. mail.mailComposeDelegate = self
  72. mail.setToRecipients(["support@yourcompany.com"])
  73. mail.setSubject("Diagnostics Report")
  74. mail.setMessageBody("An issue in the app is making me crazy, help!", isHTML: false)
  75. /// Add the Diagnostics Report as an attachment.
  76. mail.addDiagnosticReport(report)
  77. present(mail, animated: true)
  78. }
  79. }
  80. }
  81. extension ViewController: MFMailComposeViewControllerDelegate {
  82. func mailComposeController(_ controller: MFMailComposeViewController, didFinishWith result: MFMailComposeResult, error: Error?) {
  83. controller.dismiss(animated: true)
  84. }
  85. }
  86. ```
  87. On macOS you could send the report by using the `NSSharingService`:
  88. ```swift
  89. import AppKit
  90. import Diagnostics
  91. func send(report: DiagnosticsReport) {
  92. let service = NSSharingService(named: NSSharingService.Name.composeEmail)!
  93. service.recipients = ["support@yourcompany.com"]
  94. service.subject = "Diagnostics Report"
  95. let url = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent("Diagnostics-Report.html")
  96. // remove previous report
  97. try? FileManager.default.removeItem(at: url)
  98. do {
  99. try report.data.write(to: url)
  100. } catch {
  101. print("Failed with error: \(error)")
  102. }
  103. service.perform(withItems: [url])
  104. }
  105. ```
  106. ### Agent-friendly reports
  107. Diagnostics reports remain a single `.html` attachment that users can email and open in a browser. New reports also embed a structured JSON payload in:
  108. ```html
  109. <script id="diagnostics-report-data" type="application/json">
  110. ```
  111. Support agents and AI tools should parse that JSON first instead of loading the rendered HTML. The payload contains report metadata, agent hints, structured chapters, session metadata, and log events with levels like `debug`, `system`, `error`, and `crash`.
  112. The browser view is generated from this JSON. Chapters can still include `legacyHTML` when custom formatting is needed, and older on-device log sessions remain readable after users update to a newer Diagnostics version. This repository also includes a reusable analyzer skill in `diagnostics-report-analyzer-skill` for clients that support agent skills/plugins.
  113. If your support workflow consumes JSON directly, create a standalone JSON report instead:
  114. ```swift
  115. let report = await DiagnosticsReporter.create(format: .json)
  116. ```
  117. ### Install the Agent Skill
  118. For the easiest setup, install the analyzer skill with `npx skills`:
  119. ```bash
  120. npx skills add https://github.com/AvdLee/Diagnostics --skill diagnostics-report-analyzer-skill
  121. ```
  122. See [agent-skill-install-instructions.md](agent-skill-install-instructions.md) for Claude, Cursor, OpenAI-compatible tools, pi, and manual installation options.
  123. ### Using a UserDefaultsReporter
  124. In order to use `UserDefaultsReporter`, you need to specify the desired `UserDefaults` instance together with all the keys you would like to read, and use it in `DiagnosticsReporter.create(filename:using:filters:smartInsightsProvider)` to create a `DiagnosticsReport`.
  125. ```swift
  126. let userDefaultsReporter = UserDefaultsReporter(
  127. userDefaults: UserDefaults(suiteName: "a.userdefaults.instance"),
  128. keys: ["key_1"]
  129. )
  130. let diagnosticsReport = await DiagnosticsReporter.create(using: [userDefaultsReporter])
  131. ```
  132. ### Filtering out sensitive data
  133. It could be that your report is containing sensitive data. You can filter this out by creating a `DiagnosticsReportFilter`.
  134. The example project contains an example of this:
  135. ```swift
  136. struct DiagnosticsDictionaryFilter: DiagnosticsReportFilter {
  137. // This demonstrates how a filter can be used to filter out sensible data.
  138. static func filter(_ diagnostics: Diagnostics) -> Diagnostics {
  139. guard let dictionary = diagnostics as? [String: String] else { return diagnostics }
  140. return dictionary.filter { keyValue -> Bool in
  141. if keyValue.key == "App Display Name" {
  142. // Filter out the key with the value "App Display Name"
  143. return false
  144. } else if keyValue.key == "AppleLanguages" {
  145. // Filter out a user defaults key.
  146. return false
  147. }
  148. return true
  149. }
  150. }
  151. }
  152. ```
  153. Which can be used by passing in the filter into the `create(..)` method:
  154. ```swift
  155. let report = await DiagnosticsReporter.create(using: reporters, filters: [DiagnosticsDictionaryFilter.self])
  156. ```
  157. ### Adding your own custom logs
  158. To make your own logs appear in the logs diagnostics you need to make use of the `DiagnosticsLogger`.
  159. ```swift
  160. /// Support logging simple `String` messages.
  161. DiagnosticsLogger.log(message: "Application started")
  162. /// Support logging `Error` types.
  163. DiagnosticsLogger.log(error: ExampleError.missingData)
  164. ```
  165. The error logger will make use of the localized description if available which you can add by making your error conform to `LocalizedError`.
  166. ### Adding a directory tree report
  167. It's possible to add a directory tree report for a given set of URL, resulting in the following output:
  168. ```
  169. └── Documents
  170. +-- contents
  171. | +-- B3F2F9AD-AB8D-4825-8369-181DEAAFF940.png
  172. | +-- 5B9C090E-6CE1-4A2F-956B-15897AB4B0A1.png
  173. | +-- 739416EF-8FF8-4502-9B36-CEB778385BBF.png
  174. | +-- 27A3C96B-1813-4553-A6B7-436E6F3DBB20.png
  175. | +-- 8F176CEE-B28F-49EB-8802-CC0438879FBE.png
  176. | +-- 340C2371-A81A-4188-8E04-BC19E94F9DAE.png
  177. | +-- E63AFEBC-B7E7-46D3-BC92-E34A53C0CE0A.png
  178. | +-- 6B363F44-AB69-4A60-957E-710494381739.png
  179. | +-- 9D31CA40-D152-45D9-BDCE-9BB09CCB825E.png
  180. | +-- 304E2E41-9697-4F9A-9EE0-8D487ED60C45.jpeg
  181. | └── 7 more file(s)
  182. +-- diagnostics_log.txt
  183. +-- Okapi.sqlite
  184. +-- Library
  185. | +-- Preferences
  186. | | └── group.com.swiftlee.app.plist
  187. | └── Caches
  188. | └── com.apple.nsurlsessiond
  189. | └── Downloads
  190. | └── com.swiftlee
  191. +-- Coyote.sqlite-shm
  192. +-- Coyote.sqlite
  193. +-- Coyote.sqlite-wal
  194. +-- Okapi.sqlite-shm
  195. +-- Okapi.sqlite-wal
  196. └── 1 more file(s)
  197. ```
  198. You can do this by adding the `DirectoryTreesReporter`:
  199. ```swift
  200. var reporters = DiagnosticsReporter.DefaultReporter.allReporters
  201. let documentsURL = try! FileManager.default.url(for: .documentDirectory, in: .userDomainMask, appropriateFor: nil, create: false)
  202. let directoryTreesReporter = DirectoryTreesReporter(
  203. directories: [
  204. documentsURL
  205. ]
  206. )
  207. reporters.insert(directoryTreesReporter, at: 1)
  208. ```
  209. ### Adding your own custom report
  210. To add your own report you need to make use of the `DiagnosticsReporting` protocol.
  211. ```swift
  212. /// An example Custom Reporter.
  213. struct CustomReporter: DiagnosticsReporting {
  214. static func report() -> DiagnosticsChapter {
  215. let diagnostics: [String: String] = [
  216. "Logged In": Session.isLoggedIn.description
  217. ]
  218. return DiagnosticsChapter(title: "My custom report", diagnostics: diagnostics)
  219. }
  220. }
  221. ```
  222. You can then add this report to the creation method:
  223. ```swift
  224. var reporters = DiagnosticsReporter.DefaultReporter.allReporters
  225. reporters.insert(CustomReporter.self, at: 1)
  226. let report = await DiagnosticsReporter.create(using: reporters)
  227. ```
  228. ## Smart Insights
  229. ![](Assets/smart-insights.png)
  230. By default, standard Smart Insights are provided:
  231. - `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.
  232. - `DeviceStorageInsight` shows whether the user is out of storage or not
  233. ### Adding your own custom insights
  234. It's possible to provide your own custom insights based on the chapters in the report. A common example is to parse the errors and show a smart insight about an occurred error:
  235. ```swift
  236. struct SmartInsightsProvider: SmartInsightsProviding {
  237. func smartInsights(for chapter: DiagnosticsChapter) -> [SmartInsightProviding] {
  238. guard let html = chapter.diagnostics as? HTML else { return [] }
  239. if html.errorLogs.contains(where: { $0.contains("AppDelegate.ExampleLocalizedError") }) {
  240. return [
  241. SmartInsight(
  242. name: "Localized data",
  243. result: .warn(message: "An error was found regarding missing localisation.")
  244. )
  245. ]
  246. }
  247. return []
  248. }
  249. }
  250. ```
  251. The example project provides the above sample code for you to try out. You can make use of `html.errorLogs`, `.debugLogs`, and `.systemLogs` to quickly access specific logs from the report.
  252. #### Creating a custom HTML formatter for your report
  253. You can make use of the `HTMLFormatting` protocol to customize the way the HTML is reported.
  254. Simply pass in the formatter into the `DiagnosticsChapter` initialiser:
  255. ```swift
  256. DiagnosticsChapter(title: "UserDefaults", diagnostics: userDefaults, formatter: <#HTMLFormatting.Type#>)
  257. ```
  258. ## Communication
  259. - If you **found a bug**, open an issue.
  260. - If you **have a feature request**, open an issue.
  261. - If you **want to contribute**, submit a pull request.
  262. ## Installation
  263. ### Swift Package Manager
  264. The [Swift Package Manager](https://swift.org/package-manager/) is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies.
  265. #### Manifest File
  266. Add Diagnostics as a package to your `Package.swift` file and then specify it as a dependency of the Target in which you wish to use it.
  267. ```swift
  268. import PackageDescription
  269. let package = Package(
  270. name: "MyProject",
  271. platforms: [
  272. .macOS(.v10_15)
  273. ],
  274. dependencies: [
  275. .package(url: "https://github.com/AvdLee/Diagnostics.git", .upToNextMajor(from: "6.0.0"))
  276. ],
  277. targets: [
  278. .target(
  279. name: "MyProject",
  280. dependencies: ["Diagnostics"]),
  281. .testTarget(
  282. name: "MyProjectTests",
  283. dependencies: ["MyProject"]),
  284. ]
  285. )
  286. ```
  287. #### Xcode
  288. To add Diagnostics as a [dependency](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app) to your Xcode project, select *File > Swift Packages > Add Package Dependency* and enter the repository URL: `https://github.com/AvdLee/Diagnostics.git`.
  289. ### Carthage
  290. [Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.
  291. You can install Carthage with [Homebrew](http://brew.sh/) using the following command:
  292. ```bash
  293. $ brew update
  294. $ brew install carthage
  295. ```
  296. To integrate Diagnostics into your Xcode project using Carthage, specify it in your `Cartfile`:
  297. ```ogdl
  298. github "AvdLee/Diagnostics" ~> 6.00
  299. ```
  300. Run `carthage update` to build the framework and drag the built `Diagnostics.framework` into your Xcode project.
  301. ### Manually
  302. If you prefer not to use any of the aforementioned dependency managers, you can integrate Diagnostics into your project manually.
  303. #### Embedded Framework
  304. - Open up Terminal, `cd` into your top-level project directory, and run the following command "if" your project is not initialized as a git repository:
  305. ```bash
  306. $ git init
  307. ```
  308. - Add Diagnostics as a git [submodule](http://git-scm.com/docs/git-submodule) by running the following command:
  309. ```bash
  310. $ git submodule add https://github.com/AvdLee/Diagnostics.git
  311. ```
  312. - Open the new `Diagnostics` folder, and drag the `Diagnostics` folder into the Project Navigator of your application's Xcode project. This will add the SPM package as a local package.
  313. > It should appear nested underneath your application's blue project icon. Whether it is above or below all the other Xcode groups does not matter.
  314. - Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.
  315. - In the tab bar at the top of that window, open the "General" panel.
  316. - Click on the `+` button under the "Embedded Binaries" section.
  317. - Select `Diagnostics.framework`.
  318. - And that's it!
  319. > The `Diagnostics.framework` is automagically added as a target dependency, linked framework and embedded framework in a copy files build phase which is all you need to build on the simulator and a device.
  320. ---
  321. ## Release Notes
  322. See [CHANGELOG.md](https://github.com/AvdLee/Diagnostics/blob/main/Changelog.md) for a list of changes.
  323. ## Projects using Diagnostics
  324. - [RocketSim](https://www.rocketsim.app)
  325. - [Stock Analyzer](https://apps.apple.com/nl/app/stock-analyzer/id1614853142)
  326. - [Helm for App Store Connect](https://apps.apple.com/app/apple-store/id6479357934)
  327. ## Authors
  328. This library was originally created by Antoine van der Lee as part of a WeTransfer hackathon. Process has been reported on [Twitter](https://twitter.com/twannl/status/1201474263200550917?s=20).
  329. Thanks to:
  330. - ["Offie"](https://twitter.com/offinga) for the HTML report
  331. - [Casper](https://twitter.com/_casperlourens) for the awesome logo
  332. - [Antoine](https://www.twitter.com/twannl) for the Swift Library
  333. Also, a little shoutout to [1Password](https://www.1password.com) for [inspiring us](https://twitter.com/twannl/status/1200167786749874176?s=20) to create this library.
  334. ## License
  335. Diagnostics is available under the MIT license. See the LICENSE file for more info.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.