| Network Working Group | P. M. Hallam-Baker |
| Internet-Draft | Comodo Group Inc. |
| Expires: November 06, 2014 | May 05, 2014 |
JSON Log Format (JSON-L)
draft-hallambaker-jsonl-00
A log file format based on the JSON encoding is described.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 06, 2014.
Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
A log file consists of a sequence of entries. In a JSON-L log file, each entry is a JSON object [RFC7159].
One of the chief drawbacks to using JSON notation as a log file format is that a log file is by definition a sequence of entries and a JSON document MUST contain exactly one object. Further JSON objects and arrays both require start '{[' and end ']}' markers.
Use of the JSON notation as a log file format would thus require a process appending data to a log file to either omit the end markers completely or erase the existing end markers, append the new data the file and write new end markers.
Both approaches are highly unsatisfactory, the first violates the JSON encoding rules and the second introduces a risk of a race condition if two processes attempt to update the same log file at the same time.
An encoding that permits log entries to be appended to the end of a log file without modifying the existing contents is both safer and more efficient. Since writing data to an append only log file is a common requirement, most platforms already provide efficient and robust primitives to effect append-only updates.
Resynchronization is a mechanism that allows a reader to detect the start of a log file entry.
Resynchronization permits a reader to recover in the case that a log entry is corrupted and/or support random access to log file entries.
Log files may grow to thousands or millions of entries. When dealling with log files of such size it is frequently desirable to skip forward or backwards to quickly locate an entry added at a specific time.
Since JSON objects MAY be of variable lengths and MAY include nested JSON objects, a log file viewer that supports such a random access feature requires a simple means of locating the start of the next entry.
A JSON-L log file consists of a sequence of zero or more JSON objects as specified in [RFC7159] separated by white space that includes at least one newline character.
JSON-L-text = *(object x-ws)
x-ws = *ws %x0A *ws
Since control characters are not permitted inside JSON string values and JSON objects MUST be separated by commas inside a JSON array, the sequence '}' *ws LF *ws '{' can only occur at the end of one log entry and the start of the next:'
Boundary = end-object x-ws begin-object
The MIME media type for JSON-Log text is application/json-l.
Type name: application
Subtype name: json-l
Required parameters: n/a
Optional parameters: n/a
Encoding considerations: binary
Security considerations: See [this], Section TBS.
Interoperability considerations: Described in [this]
Published specification: [this]
Applications that use this media type: None (so far)
Additional information:
Magic number(s): n/a
File extension(s): .jsonl
Macintosh file type code(s): TEXT
Person & email address to contact for further information: Phillip Hallam-Baker <phill@hallambaker.com>
Intended usage: COMMON
Restrictions on usage: none
Author: Phillip Hallam-Baker
Change controller: Phillip Hallam-Baker <phill@hallambaker.com>
Note: No "charset" parameter is defined for this registration. Adding one really has no effect on compliant recipients.
This is a minor modification of the JSON encoding developed by Douglas Crockford. Nico Williams provided useful advice on the resynchronization scheme.
| [RFC7159] | Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, March 2014. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |