====== 12 Formatters ======

The //Formatter// class is responsible for converting a Log Record into a String representation. For example, the //FileHandler// uses the function ''Format LogRecord.vi'' of the Formatter class.


===== Available Formatters =====

The HSE Logger ships with three Formatter classes:

==== HSE_v2_Formatter ====

An improved version of the Default Formatter.

**Example output:**

  - Simple error
  - Error from the Error Cluster from Error Code VI with extra call chain
  - Error from the Error Cluster from Error Code VI with extra call chain and DQMH error hint

<code>
2024-03-05 14:59:32.608 - DEBUG    - Normal log message - Logging with Helper-VIs.vi
2024-03-05 15:00:07.338 - DEBUG    - Log message with error - Logging with Helper-VIs.vi
                        => Error 42: Some error.
2024-02-20 15:33:58.253 - DEBUG    - Log Message - UT_Formatter.lvlib:Test HSE_v2 Format String.vi
                        => Error 42: Some error
                        => Source call chain
                            > Navigation.lvlib:Button Manager.lvclass:Get Object by Name.vi
                            > Navigation.lvlib:Main.vi
                            > Navigation.lvlib:Main.vi.ACBRProxyCaller.724000A7
                        => DQMH error hint
                            > MHL Frame: Set Disabled State
</code>


==== Original Formatter ====

The original, slightly improved format of the FileHandler (//HSE_v1_Formatter//) and default if no specific Formatter is given.

**Example output:**

  - Simple error
  - Error from the Error Cluster from Error Code VI with extra call chain
  - Error from the Error Cluster from Error Code VI with extra call chain and DQMH error hint

<code>
# 
2024-02-20 12:46:00.341 - DEBUG    - Test error - UT_Formatter.lvlib:Test Clean Source String.vi - 42 - Some error |  | 

# Error from the Error Cluster from Error Code VI with extra call chain
2024-02-20 12:46:00.341 - DEBUG    - Test error - UT_Formatter.lvlib:Test Clean Source String.vi - 42 - Some error | UT_Formatter.lvlib:ECFEC Wrapper.vi => UT_Formatter.lvlib:Test Clean Source String.vi | 

# Error from the Error Cluster from Error Code VI with extra call chain and DQMH error hint
2024-02-20 12:46:00.341 - DEBUG    - Test error - UT_Formatter.lvlib:Test Clean Source String.vi - 42 - Some error | Navigation.lvlib:Button Manager.lvclass:Get Object by Name.vi => Navigation.lvlib:Main.vi => Navigation.lvlib:Main.vi.ACBRProxyCaller.724000A7 | MHL Frame: Set Disabled State
</code>


==== JSONLFormatter ====

Log in JSON format so that log entries can be parsed by other tools (e.g. fluent-bit log forwarder) without the need to write a custom log parser.

**Example JSON lines structured log:**

    {"time": "2023-10-04 08:55:12.964","log_level": "INFO","message": "Application initialized.","call_chain": "Experiment Pane.lvlib:Main.vi:4140011->Experiment Pane.lvlib:Main.vi.ACBRProxyCaller.C3000E8","error_code": "0"}
    {"time": "2023-10-04 08:55:12.964","log_level": "DEBUG","message": "Running Self-Tests","call_chain": "Experiment Pane.lvlib:Main.vi:4140011->Experiment Pane.lvlib:Main.vi.ACBRProxyCaller.C3000E8","error_code": "0"}
    {"time": "2023-10-04 08:55:12.964","log_level": "WARNING","message": "Self-Test A failed","call_chain": "Experiment Pane.lvlib:Main.vi:4140011->Experiment Pane.lvlib:Main.vi.ACBRProxyCaller.C3000E8","error_code": "1234"}
    {"time": "2023-10-04 08:55:12.964","log_level": "ERROR","message": "VISA Could not load resource.","call_chain": "Experiment Pane.lvlib:Main.vi:4140011->Experiment Pane.lvlib:Main.vi.ACBRProxyCaller.C3000E8","error_code": "5678"}


**Features:**

  * Follows JSONlines format - https://jsonlines.org/
  * One log entry per line
  * Each log entry is JSON formatted
  * Each line is separated by line feed
  * Can expand single-line JSON using built in formatters in most text IDEs (i.e. VSCode, Shift+Alt+F)
  * Scalable - can easily include nested JSON structures

---- 

===== Custom Formatter =====

You can implement your own, specific child class of the Default Formatter to adjust the conversion. To inject a Formatter use the corresponding terminal of the "Create Handler" method or the ''Set Formatter.vi'' of the Handler (or the property node). 

<note important>Only Handlers which produce a formatted string output support Formatters.</note>

{{:code:open-source:hse-logger:screenshot_2024-03-05_144409.png|}}