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 any Writer that accepts the OutputStreamFormatter 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. The template parameter is a Swift.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 the terminator 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.
    See more

    Declaration

    Swift

    public struct TextFormat : OutputStreamFormatter
  • 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 any Writer that accepts the OutputStreamFormatter 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 the terminator parameter at construction.

    For instance.

    let formatter = JSONFormat(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.

    See more

    Declaration

    Swift

    public struct JSONFormat : OutputStreamFormatter