Merge branch 'tech/frizlab/readme' into develop

Author: Frizlab

Package.swift

@@ -15,7 +15,7 @@ let package = Package(
 		.target(name: "JSONLogger", dependencies: [
 			.product(name: "GenericJSON",   package: "generic-json"),
 			.product(name: "Logging",       package: "swift-log"),
-		], path: "Sources"),
+		], path: "Sources", exclude: ["JSONLogger+WithSendable.swift"]),
 		.testTarget(name: "JSONLoggerTests", dependencies: ["JSONLogger"]),
 	]
 )

[email protected]

@@ -24,7 +24,7 @@ let package = Package(
 		.target(name: "JSONLogger", dependencies: [
 			.product(name: "GenericJSON",   package: "generic-json"),
 			.product(name: "Logging",       package: "swift-log"),
-		], path: "Sources", swiftSettings: swiftSettings),
+		], path: "Sources", exclude: ["JSONLogger+NoSendable.swift"], swiftSettings: swiftSettings),
 		.testTarget(name: "JSONLoggerTests", dependencies: ["JSONLogger"], swiftSettings: swiftSettings),
 	]
 )

Readme.adoc

@@ -0,0 +1,106 @@
+# 📄 JSONLogger
+
+<picture><img alt="Compatible from Swift 5.1 to 6." src="https://img.shields.io/badge/Swift-6.0_%7C_5.10--5.1-blue"></picture>
+<picture><img alt="Compatible with macOS, iOS, visionOS, tvOS and watchOS." src="https://img.shields.io/badge/Platforms-macOS_%7C_iOS_%7C_visionOS_%7C_tvOS_%7C_watchOS-blue"></picture>
+<picture><img alt="Compatible with Linux, Windows, WASI and Android." src="https://img.shields.io/badge/Platforms-Linux_%7C_Windows_%7C_WASI_%7C_Android-blue"></picture>
+[![](<https://img.shields.io/github/v/release/xcode-actions/json-logger>)](<https://github.com/xcode-actions/json-logger/releases>)
+
+A simple [swift-log](<https://github.com/apple/swift-log>)-compatible logger which logs in JSON, one entry per line.
+
+## Usage 🤓
+
+Bootstrap the LoggingSystem with `JSONLogger` before creating any logger:
+```swift
+LoggingSystem.bootstrap(JSONLogger.init, metadataProvider: nil/* or whatever you want */)
+```
+
+To stream JSONSeq (RFC 7464), you can use a convenience initializer:
+```swift
+LoggingSystem.bootstrap(JSONLogger.initForJSONSeq, metadataProvider: nil/* or whatever you want */)
+```
+
+## Log Format 📖
+
+The JSONs generated by `JSONLogger` have the following fields:
+- `level`: The level of the log.
+Value is a `Logger.Level` (`trace`, `debug`, `info`, `notice`, `warning`, `error` or `critical`).
+- `message`: The message of the log (`String` value).
+- `metadata`: The structured metadata of the logs (`JSON` object value).
+The structure of the metadata values are kept as much as possible.
+- `date` or `date-1970`: The date of the log.
+If the log can be encoded properly using a `JSONEncoder` the `date` field is present and the value comes from the encoder.
+If there is an error encoding the log, the `date-1970` fallback is used with the value being a `Double` representing the time interval since January 1, 1970 (UNIX time).
+- `label`: The label of the logger (`String` value).
+- `source`: The source of the log (`String` value).
+- `file`: The file from which the log has been generated (`String` value).
+- `function`: The function from which the log has been generated (`String` value).
+- `line`: The line from which the log has been generated (`UInt` value).
+
+The JSONs should not have any newlines, however there are no _actual_ guarantees from `JSONEncoder`.
+In particular you can configure the encoder to pretty print the JSONs…
+
+## Configuration 🛠️
+
+### Output FileHandle
+
+By default `JSONLogger` logs on `stdout`.
+You can configure it to log on any file descriptor using the `fileHandle` parameter at init time.
+
+### Line Prefix, Suffix and Separator
+
+`JSONLogger` allows you to choose:
+- A suffix for the JSON payload (the “newline separator;” defaults to `[0x0a]`, aka. a single UNIX newline);
+- A prefix (defaults to `[]`);
+- An inter-message separator (defaults to `[]`).
+
+The inter-message separator is logged after a JSON message, but only when a new message arrives,
+ as opposed to the suffix which is logged after _every_ JSON message.
+ 
+As an example, if you log two messages, you’ll get the following output:
+```text
+prefix JSON1 suffix  separator  prefix JSON2 suffix
+```
+ 
+An interesting configuration is to set the prefix to `[0x1e]` and the suffix to `[0x0a]`, which generates a JSONSeq stream.
+ 
+Another interesting configuration is to set the inter-JSON separator to `[0xff]` or `[0xfe]` (or both), and set the prefix and suffix to an empty array.
+The `0xff` and `0xfe` bytes should never appear in valid UTF-8 strings and can be used to separate JSON payloads (JSON requires UTF-8 encoding).
+
+I’m not sure why JSONSeq does not do that but there must be a good reason (probably because the resulting output would not be valid UTF-8 anymore).
+
+### JSON Encoder
+
+In order to log messages, `JSONLogger` will create a `LogLine` struct for every message, then encode this struct using a `JSONEncoder`.
+
+This encoder is customizable.
+
+All JSON messages generated by `JSONLogger` should be decodable by a `JSONDecoder` matching the configuration of the encoder.
+
+#### When the Encoder Fails
+
+When there is a problem encoding a log line (e.g. a date formatter fails), `JSONLogger` will fallback to manually encoding the log message.
+
+The manually encoded JSON differs slightly from the normal output:
+- The metadata are stripped and replaced by:
+```json
+{
+   "JSONLogger.LogInfo": "Original metadata removed (see JSONLogger doc)",
+   "JSONLogger.LogError": ERROR_MESSAGE
+}
+```
+- The log message is prefixed by `MANGLED LOG MESSAGE (see JSONLogger doc) -- `;
+- Instead of a `date` field, there is a `date-1970` field whose value is the `timeIntervalSince1970` of the date of the message.
+This ensures the encoding of the message _cannot_ fail.
+
+The modified log message should still be parsable by a `JSONEncoder` as a `LogLine`.
+
+### JSON Coders for `StringConvertible`s
+
+The type of the value of a metadata entry can be either a `String`, an `Array`, a `Dictionary` or `any StringConvertible`.
+
+The `String`, `Array` and `Dictionary` types are straightforward to encode in a JSON message.
+
+For the string convertibles, `JSONLogger` will use a pair of `JSONEncoder`/`JSONDecoder` if present.
+The encoder will be used to encode the given object, and the decoder will be used to decode the resulting JSON into a generic `JSON` object, that will then be put in the `LogLine` struct.
+
+If the encoder/decoder pair is set to `nil`, the String representation of the string convertible is used.

Readme.md

@@ -0,0 +1,19 @@
+import Foundation
+
+import Logging
+
+
+
+extension JSONLogger {
+	
+	public init(label: String, metadataProvider: Logger.MetadataProvider? = LoggingSystem.metadataProvider) {
+		/* The fileHandle argument should be present to avoid infinite recursion
+		 *  but its value should be the same as the default value of the initializer we’re calling (for API consistency). */
+		self.init(label: label, fileHandle: .standardOutput, metadataProvider: metadataProvider)
+	}
+	
+	public static func initForJSONSeq(label: String, metadataProvider: Logger.MetadataProvider? = LoggingSystem.metadataProvider) -> JSONLogger {
+		Self.forJSONSeq(label: label, metadataProvider: metadataProvider)
+	}
+	
+}

Sources/JSONLogger+NoSendable.swift

@@ -0,0 +1,24 @@
+import Foundation
+
+import Logging
+
+
+
+/* The @Sendable attribute is only available starting at Swift 5.5.
+ * We make these methods only available starting at Swift 5.8 for our convenience (avoids creating another Package@swift-... file)
+ *  and because for Swift <5.8 the non-@Sendable variants of the methods are available. */
+extension JSONLogger {
+	
+	@Sendable
+	public init(label: String, metadataProvider: Logger.MetadataProvider? = LoggingSystem.metadataProvider) {
+		/* The fileHandle argument should be present to avoid infinite recursion
+		 *  but its value should be the same as the default value of the initializer we’re calling (for API consistency). */
+		self.init(label: label, fileHandle: .standardOutput, metadataProvider: metadataProvider)
+	}
+	
+	@Sendable
+	public static func initForJSONSeq(label: String, metadataProvider: Logger.MetadataProvider? = LoggingSystem.metadataProvider) -> JSONLogger {
+		Self.forJSONSeq(label: label, metadataProvider: metadataProvider)
+	}
+	
+}

Sources/JSONLogger+WithSendable.swift

@@ -6,7 +6,7 @@ import Logging
 
 
 /**
- A logger that logs it’s messages to stdout in the JSON format, one log per line.
+ A logger that logs its messages to stdout in the JSON format, one log per line.
 
  The end of line separator is actually customizable, and can be any sequence of bytes.
  By default it’s “`\n`”.

Sources/JSONLogger.swift

@@ -29,7 +29,7 @@ final class JSONLoggerTests : XCTestCase {
 	}()
 
 	override class func setUp() {
-		LoggingSystem.bootstrap{ JSONLogger(label: $0) }
+		LoggingSystem.bootstrap(JSONLogger.init, metadataProvider: nil)
 	}
 
 	/* From <https://apple.github.io/swift-log/docs/current/Logging/Protocols/LogHandler.html#treat-log-level-amp-metadata-as-values>. */