Awesome

Wells

A lightweight diagnostics report submission system.

Integration

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

Getting Started

Wells is just a submission system, and tries not to make any assumptions about the source or contents of the reports it transmits. It contains two main components: WellsReporter and WellsUploader. By default, these work together. But, WellsUploader can be used separately if you need more control over the process.

Because of its flexibility, Wells requires you to do a little more work to wire it up to your source of diagnostic data. Here's what an simple setup could look like. Keep in mind that Wells uploads data using NSURLSession background uploads. This means that the start and end of an upload may not occur during the same application launch.

If you use WellsReporter to submit data, it will manage the cross-launch details itself. But, if you need more control, or want to manage the on-disk files yourself, you'll need to provide it with a ReportLocationProvider that can map identifiers back to file URLs.

import Foundation
import Wells

class MyDiagnosticReporter {
    private let reporter: WellsReporter

    init() {
        self.reporter = WellsReporter()
        
        reporter.existingLogHandler = { url, date in
            // might want to examine date to see how old
            // the date is (and handle errors more gracefully)
            try? submit(url: url)
        }
    }

    func start() throws {
        // submit files, including an identifier unique to each file
        let logURLs = getExistingLogs()

        for url in logURLs {
            try submit(url: url)
        }

        // or, just submit bytes
        let dataList = getExistingData()

        for data in dataList {
            let request = makeURLRequest()
            reporter.submit(data, uploadRequest: request)
        }

    }

    func submit(url: URL) throws {
        let logIdentifier = computeUniqueIdentifier(for: url)
        let request = makeURLRequest()

        try reporter.submit(fileURL: url, identifier: logIdentifier, uploadRequest: request)
    }

    func computeUniqueIdentifier(for url: URL) -> String {
        // this works, but a more robust solution would be based on the content of the data. Note that
        // the url itself *may not* be consistent from launch to launch.
        return UUID().uuidString
    }

    // Finding logs/data is up to you
    func getExistingLogs() -> [URL] {
        return []
    }

    func getExistingData() -> [Data] {
        return []
    }

    func makeURLRequest() -> URLRequest {
        // You have control over the URLRequest that Wells uses. However,
        // some additional metadata will be added to enablee cross-launch tracking.
        let endpoint = URL(string: "https://mydiagnosticservice.com")!

        var request = URLRequest(url: endpoint)

        request.httpMethod = "PUT"
        request.addValue("hiya", forHTTPHeaderField: "custom-header")

        return request
    }
}

Retries

Because that Wells manages submissions across app launches, retry logic can be complex. Wells will do its best to retry unsuccesful submissions. It respects the Retry-After HTTP header and has backoff. But, it is possible that the hosting app is terminated while a backoff delay is pending. In this situation, WellsReporter relies on its existingLogHandler property to avoid needing persistent storage.

By default, if there are files found within the baseURL directory that are older than 2 days, Wells will give up and delete them.

Bottom line: Wells submissions are best effort. Robust retry support means you have to make use of existingLogHandler. There are pathological, if improbable situations that could prevent the submission and retry system from working in a predictable way.

Using With MetricKit

Wells works great for submitting data gathered from MetricKit. In fact, MeterReporter uses it for a full MetricKit-based reporting system.

But, you can also do it yourself. Here's a simple example.

import Foundation
import MetricKit
import Wells

class MetricKitOnlyReporter: NSObject {
    private let reporter: WellsReporter
    private let endpoint = URL(string: "https://mydiagnosticservice.com")!

    override init() {
        self.reporter = WellsReporter()

        super.init()

        MXMetricManager.shared.add(self)
    }

    private func submitData(_ data: Data) {
        var request = URLRequest(url: endpoint)

        request.httpMethod = "PUT"

        // ok, yes, I have glossed over error handling
        try? reporter.submit(data, uploadRequest: request)
    }
}

extension MetricKitOnlyReporter: MXMetricManagerSubscriber {
    func didReceive(_ payloads: [MXMetricPayload]) {
    }

    func didReceive(_ payloads: [MXDiagnosticPayload]) {
        payloads.map({ $0.jsonRepresentation() }).forEach({ submitData($0) })
    }
}

Namesake

Wells is all about reporting, so it seemed logical to name it after a notable journalist.

Suggestions or Feedback

I would love to hear from you! Issues or pull requests work great. A Discord server is also available for live help, but I have a strong bias towards answering in the form of documentation.

I prefer collaboration, and would love to find ways to work together if you have a similar project.

I prefer indentation with tabs for improved accessibility. But, I'd rather you use the system you want and make a PR than hesitate because of whitespace.

By participating in this project you agree to abide by the Contributor Code of Conduct.