Wells

A lightweight diagnostics report submission system

Integration

Swift Package Manager:

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

Carthage:

github "stacksift/Wells"

CocoaPods:

pod '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 it's 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.

import Foundation
import Wells

class MyDiagnosticReporter {
    private let reporter: WellsReporter

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

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

        for url in logURLs {
            let logIdentifier = computeUniqueIdentifier(for: url)
            let request = makeURLRequest()

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

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

        for data in dataList {
            let request = makeURLRequest()
            reporter.submit(data, 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
    }
}

Using With MetricKit

Wells works great for submitting data gathered from MetricKit. 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

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.

Clafou/Wells

README