Formatters
Formatters are instances of an OutputStreamFormatter
and can be used with any OutputStreamWriter
type. TraceLog offer the built in types below but also allows you to create your own.
See also
See the Software Development Kit (SDK) for more information on creating your own.-
The TextFormat is a configurable implementation of a
OutputStreamFormatter
which allows complete control over the fields and format of the output log entry.Since the TextFormat is an instance of
OutputStreamFormatter
it can be used with anyWriter
that accepts theOutputStreamFormatter
on construction.TextFormat has a number of options for configuring it for many use-cases. All options have a default value assigned to them to make it easy to get started without configuration. Should refinement of the default behavior be required, these options give you fine grain control over the output.
Output Templates
The primary control of the formatting is through the
template
parameter which defines the output variables and constants for each logged entry. Thetemplate
parameter is aSwift.String
that allows any constants plus substitution variables that specify the various fields that TraceLog can output.Substitution variables take the form %{variable-name} and are case sensitive. Each variable can be used within the template String as many times as your use-case requires.
- Substitution variables:
- %{date}
- %{timestamp}
- %{level}
- %{tag}
- %{processName}
- %{processIdentifier}
- %{threadIdentifier}
- %{file}
- %{function}
- %{line}
- %{message}
The default template is a human-readable form meant for debugging purposes and excludes extraneous details such as file, function and line. It is defined as:
template: "%{date} %{processName}[%{processIdentifier}:%{threadIdentifier}] %{level}: <%{tag}> %{message}"
Which produces an output similar to this:
1970-01-01 00:00:00.000 ExampleProcess[100:1100] INFO: <ExampleTag> Example message.
You can easily create other output forms such as TAB DELIMITED using this template (and adjusting the number of fields to your requirements).
template: "\"%{date}\",\"%{processName}\",%{processIdentifier},%{threadIdentifier},\"%{level}\",\"%{tag}\",\"%{message}\""
Your output would look similar to this given the same input as above:
"1970-01-01 00:00:00.000","ExampleProcess",50,200,"WARNING","ExampleTag","Example message.”
Control Characters
TraceLog allows you to embed formatting control characters (\r\n\t) into the message when logging messages. The TextFormat allows you to strip those out or escape them so that the output can be more concise or machine readable if required.
Logging a statement like this is great for reading on the console but could cause issues with parsing a format that requires analyzing the entries.
let formatter = TextFormat(options: [.controlCharacters(.strip)]) TraceLog.configure(writers: [ConsoleWriter(format: formatter)]) logInfo { "\n\t\tThis is a message with control characters that spans multiple lines \n\t\tand is indented with several tab characters." }
Using
.controlCharacters(.strip)
will allow you to strip those out before output, giving you the following output in the console or file.1970-01-01 00:00:00.000 ExampleProcess[100:1100] INFO: <ExampleTag> This is a message with control characters that spans multiple lines and is indented with several tab characters.
Using
.controlCharacters(.escape)
will allow you to escape (\
) the characters for output to writers that may require escaping of control characters.1970-01-01 00:00:00.000 ExampleProcess[100:1100] INFO: <ExampleTag> \\n\\t\\tThis is a message with control characters that spans multiple lines \\n\\t\\tand is indented with several tab characters.
Without this option the output would look like this.
1970-01-01 00:00:00.000 ExampleProcess[100:1100] INFO: <ExampleTag> This is a message with control characters that spans multiple lines and is indented with several tab characters.
Note: using this option does not affect the
terminator
output, terminators will still be printed normally.Character Encoding
The default character encoding of the output is
.utf8
which should be suitable for most applications and can encode all the unicode characters.If required, this encoding can be changed by passing a
String.Encoding
value at init to change the output encoding.For instance.
let format = TextFormat(encoding: .utf16)
Any one of the encodings defined by
String.Encoding
can be used but if you’re logging characters outside the range that the encoding can encode, the formatter will alter or drop (replacing with a placeholder character within the encoding) the character.If only logging characters within the Ascii character encoding (characters from 0-127) all encodings accept
.symbol
can be used.If logging characters outside the Ascii range (0-127), it’s recommended that you use a unicode compatible encoding. All the following encodings can completely encode Unicode:
- unicode
- utf8
- utf16
- utf16BigEndian
- utf16LittleEndian
- utf32
- utf32BigEndian
utf32LittleEndian
Note
We don’t find
.symbol
very useful due to it’s limited character range and is not supported on linux..japaneseEUC
is also not supported on Linux.Terminators
Each log entry formatted by the formatter can be terminated with a character sequence. The default value is a newline (
\n
) and can be changed by passing theterminator
parameter at construction.For instance.
let formatter = TextFormat(terminator: "\r\n")
In this case we changed the terminator from the default of
\n
to\r\n
. The characters can be any characters that make sense for your application. Keep in mind that for console or file type output, a newline\n
is required in order to write multiple lines to the screen or file.See also
OutputStreamFormatter
for more information about the base class.Declaration
Swift
public struct TextFormat : OutputStreamFormatter
- Substitution variables:
-
The JSONFormat is a configurable implementation of a
OutputStreamFormatter
which outputs standard JSON as it’s output.Since the JSONFormat is an instance of
OutputStreamFormatter
it can be used with anyWriter
that accepts theOutputStreamFormatter
on construction.JSONFormat has a number of options for configuring it for many use-cases. All options have a default value assigned to them to make it easy to get started without configuration. Should refinement of the default behavior be required, these options give you fine grain control over the output.
Specifying Attributes
All attributes that are output as JSON are configurable. The default output is a set of all attributes TraceLog outputs, these are:
- timestamp
- level
- tag
- message
- processName
- processIdentifier
- threadIdentifier
- file
- function
- line
Special formatting options
JSONFormat has special processing options available for output.
The options available are:
prettyPrint: Add formatting characters to print the output in a more human friendly form.
/* With `.prettyPrint` */ { "timestamp" : 28800.0, "level" : "INFO", "tag" : "TestTag", "message" : "Test message.", "processName" : "TestProcess", "processIdentifier" : 120, "threadIdentifier" : 200, "file" : "JSONFormatTests.swift", "function" : "testAttributeDefaultList()", "line" : 240 } /* Without `.prettyPrint` */ {"timestamp":28800.0,"level":"INFO","tag":"TestTag","message":"Test message.",,"processName":"TestProcess","processIdentifier":120,"threadIdentifier":200,"file":"JSONFormatTests.swift","function":"testAttributeDefaultList()","line":240}
Line terminator
Each log entry formatted by the formatter can be terminated with a character sequence. The default value is a newline (
,\n
) and can be changed by passing theterminator
parameter at construction.For instance.
let formatter = JSONFormat(terminator: "\r\n")
In this case we changed the terminator from the default of
See more,\n
to\r\n
. The characters can be any characters that make sense for your application.Declaration
Swift
public struct JSONFormat : OutputStreamFormatter