HTTP JSON Endpoint

The LXHTTPJSONEndpoint uploads Log Entries to an HTTP service. The Entries are serialized in JSON format.

Upload and retry management are handled automatically by this Endpoint. Log Entries that do not successfully upload will be queued for another attempt at a later time. Entries are persisted to disk until they are successfully uploaded, including between application runs, so that extended network outages do not cause Log Entries to be lost.

This Endpoint attempts to deliver Log Entries in the order in which they were generated, but because network performance is very unpredictable, this is not guaranteed. The JSON HTTP Endpoint may attempt to improve network performance by uploading multiple Log Entries in the same request.

The HTTP JSON Endpoint is safe to be used in environments featuring concurrency. This Endpoint does some of its work asynchronously to allow better logging performance. Because the HTTP JSON Endpoint takes advantage of asynchronous technologies, Log Entries written to this Endpoint may not appear until slightly after execution has moved on. In other words, if your application attempts to create a Log Entry directly before it crashes, it may not be delivered before the crash occurs. While debugging your application, if the asynchronous nature of this Endpoint is problematic, consider using a synchronous Console Endpoint in addition.

JSON Structure

The JSON HTTP Endpoint serializes Log Entries in a way that allows multiple Entries to be uploaded at once. The body of each upload request consists of a JSON dictionary. Log Entries are included in an array, found under the entries key of the dictionary. Each individual Log Entry is serialized as a dictionary (see Entry Formatting below).

Note: This behavior is different than in LogKit 1, which uploaded Entries individually. Developer beware.

Regardless of the number of Log Entries ready for upload, the HTTP JSON Endpoint will always deliver uploads in this format.

{
    "entries": [
        {...entry_1...},
        {...entry_2...},
        ...
    ]
}

Entry Formatting

The HTTP JSON Endpoint is hard-coded to include a special entryFormatter that converts each Log Entry to a dictionary, then JSON serializes it for upload. This formatter includes all properties of a Log Entry, including the Entry’s userInfo. Each Log Entry property becomes a top-level item in the dictionary, including userInfo. userInfo items, therefore, are located in a sub-dictionary under the userInfo key.

Note: The behavior for serializing userInfo described above is a change from LogKit 1. Developer beware.

It is the application developer’s duty to ensure that all userInfo items are JSON-serializable if this Endpoint is in use. A non-JSON-serializable item will cause the Log Entry to be skipped in a shipping application (though in a test build, the application will abort).

Additionally, the HTTP JSON Endpoint includes the LXDateFormatter.ISO8601DateTimeFormatter() date formatter as its default dateFormatter. This is a different default than other Endpoints include.

Here is an example Log Entry serialized to JSON (not all properties are shown for brevity):

{
    "message": "Hello Internet!",
    "userInfo": {
        "my_property": 1,
        "other_property": 2,
    },
    "dateTime": "2015-10-06T02:44:21.112000Z",
    "timestamp": 1444099461.112487,
    "level": "Debug",
    ...
}

Usage

Initializers

The following initializers are available for LXHTTPJSONEndpoint:

init(request: successCodes: sessionConfiguration: minimumPriorityLevel: dateFormatter: )

Parameters

`request`	Type: `NSURLRequest` Required	The request that will be used when submitting uploads
`successCodes`	Type: `Set<Int>` Default: `{200, 201, 202, 204}`	The set of HTTP status codes the server might respond with to indicate a successful upload
`sessionConfiguration`	Type: `NSURLSessionConfiguration` Default: `.defaultSessionConfiguration()`	The configuration to be used when initializing this Endpoint’s URL session
`dateFormatter`	Type: `LXDateFormatter` Default: `.ISO8601DateTimeFormatter()`	The formatter to be used to convert an Entry’s `dateTime` to a string
`minimumPriorityLevel`	Type: `LXPriorityLevel` Default: `.All`	The minimum Priority Level a Log Entry must meet to be accepted by this Endpoint

Developers must supply an NSURLRequest when initializing this Endpoint. This request object will be copied and used to upload each Log Entry to the HTTP service.

Returns an initialized HTTP JSON Endpoint instance. This Endpoint uses a specialized entryFormatter described above.

convenience init(URL: HTTPMethod: successCodes: sessionConfiguration: minimumPriorityLevel: dateFormatter: )

Parameters

`URL`	Type: `NSURL` Required	The URL to upload Log Entries to
`HTTPMethod`	Type: `String` Required	The HTTP request method to be used when uploading Log Entries
`successCodes`	Type: `Set<Int>` Default: `{200, 201, 202, 204}`	The set of HTTP status codes the server might respond with to indicate a successful upload
`sessionConfiguration`	Type: `NSURLSessionConfiguration` Default: `.defaultSessionConfiguration()`	The configuration to be used when initializing this Endpoint’s URL session
`dateFormatter`	Type: `LXDateFormatter` Default: `.ISO8601DateTimeFormatter()`	The formatter to be used to convert an Entry’s `dateTime` to a string
`minimumPriorityLevel`	Type: `LXPriorityLevel` Default: `.All`	The minimum Priority Level a Log Entry must meet to be accepted by this Endpoint

This convenience initializer allows developers to supply a URL and request method when initializing this Endpoint. The Endpoint will create a basic application/json NSURLRequest object to be used for all Log Entry uploads. Developers that require more flexibility in configuring upload requests should use the designated initializer above, or determine whether supplying a customized NSURLSessionConfiguration meets their needs.

Returns an initialized HTTP JSON Endpoint instance. This Endpoint uses a specialized entryFormatter described above.