Lightweight MetricKit-based diagnostics reporting

Last update: Dec 26, 2022

Overview

MeterReporter

Lightweight MetricKit-based diagnostics reporting.

MeterReporter will capture MetricKit payloads and relay them to a backend. It uses Meter to process and symbolicate payloads. The resulting data is very close to the MetricKit JSON structure. But, it does add some fields to support the additional features.

Integration

dependencies: [
    .package(url: "https://github.com/ChimeHQ/MeterReporter")
]

Usage

let url = URL(string: "https://my.backend.com/reports")!

var config = MeterReporter.Configuration(endpointURL: url)

config.hostIdentifier = Bundle.main.bundleIdentifier

let reporter = MeterReporter(configuration: config)

reporter.start()

Background Uploads

By default, MeterReporter uses URLSession background uploads for both reliability and performance. However, sometimes these can take hours for the OS to actually execute. This can be a pain if you are just testing things out. To make that easier, you can disable background uploads with another property of MeterReporter.Configuration.

NSException Capture

MeterReporter can capture uncaught NSExceptions on macOS. Unfortunately, AppKit interfers with the flow of runtime exceptions. If you want to get this information about uncaught exceptions, some extra work is required.

The top-level NSApplication instance for your app must be a subclass of ExceptionLoggingApplication.

import MeterReporter

class Application: ExceptionLoggingApplication {
}

and, you must update your Info.plist to ensure that the NSPrincipalClass key references this class with .Application.

I realize this is a huge pain. If you feel so motivated, please file feedback with Apple to ask them to make AppKit behave like UIKit in this respect.

I would also strongly recommend setting the NSApplicationCrashOnExceptions defaults key to true. The default setting will allow your application to continue executing post-exception, virtually guaranteeing state corruption and incorrect behavior.

Submission Request

The request made to the endpoint will be an HTTP PUT. The request will also set some headers.

Content-Type will be application/vnd.chimehq-mxdiagnostic
MeterReporter-Report-Id will be a unique identifier
MeterReporter-Platform
MeterReporter-Host-Id if configuration.hostIdentifier is non-nil

Suggestions or Feedback

We'd love to hear from you! Get in touch via twitter, an issue, or a pull request.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Comments

Prevent crash when MeterReporter is deallocated before upload

If the client calls start() on a MeterReporter instance but does not keep a strong reference to this instance, then it gets deallocated and if any log is available to upload a crash occurs after 10 seconds. Not sure this is the best way to fix this -- maybe intentionally creating a retain cycle is preferable so that clients don't have to retain their MeterReporter.

opened by Clafou 5
Quick way to trigger reports for testing?
I integrated MeterReporter into an app as a replacement for Stacksift, which took just a minute. My prior Stacksift setup did successfully send reports.

But I am now having trouble sending reports so that I can test my backend. I have edited my app with a fatalError() and also tried a forced unwrap crash, but no report is being sent at the next app launch after these crashes, even after 10 seconds when it should kick in. Wells's handleExistingLogs finds no report.

What is the right approach to test the sending of reports?

This is the setup code in my AppDelegate:

var config = MeterReporter.Configuration(endpointURL: URL(string: "https://myendpoint")!) config.hostIdentifier = "Test" config.backgroundIdentifier = nil let reporter = MeterReporter(configuration: config) reporter.start()
opened by Clafou 3
Is there a visualisation tools for Metrics data

The XCode Organizer doesn't show Metrics data when the usage and user count are not enough. I'm able to download Metric payload data through debugging. But the problem is I don't have a tool like XCode Organizer to show the metrics payload in graph. Any idea how to interpret the Metric payload json data? Thanks.

opened by zhouhao27 2
Clarify how to disable background uploads

The README says:

To make that easier, you can disable background uploads with another property of MeterReporter.Configuration.

But there is no detail on what that property is, and it took me a bit of digging (into the Wells code) to figure out that to disable background uploads you need to set backgroundIdentifier = nil -- maybe making that clearer, at least with a comment for that property, would help!

opened by Clafou 1
Enhancement: Document the server endpoint some more

The README does state it's going to be a PUT request and what the expected header data is -- but without writing a script to logg something at that endpoint, I wouldn't know what is being put.

Is it merely JSON (the first paragraph alludes to that)? Will it suffice to store a huge string in a database, or a .json file?

opened by DivineDominion 4