F Expose toggles for SimpleLogger

Add use descriptions

Co-Authored-By: Scott Wierschem <[email protected]>

Author: isidore

approvaltests-util-tests/src/test/java/com/spun/util/logger/SimpleLoggerTest.java

@@ -36,6 +36,17 @@ void testMarkers()
     Approvals.verify(log);
     // end-snippet
   }
+
+  @Test
+  void testToggles() {
+    // begin-snippet: simple_logger_toggles
+    SimpleLogger.get().marker = true;
+    SimpleLogger.get().event = false;
+    SimpleLogger.get().variable = false;
+    SimpleLogger.get().query = true;
+    // end-snippet
+  }
+
   public void sample()
   {
     // begin-snippet: log_nothing

approvaltests-util/docs/how_to/PerformanceProfilingWithSimpleLogger.md

@@ -0,0 +1,19 @@
+<a id="top"></a>
+
+# How to do Performance Profiling using SimpleLogger
+
+toc
+
+## Understanding timings in log output
+When SimpleLogger logs to a file or Standard.out it includes timings (these are turned off by default if you are logging
+to a string as they are inconsistent for testing purposes.)
+
+Here's an example of the output:
+```.text
+[May 20, 2021, 9:44:17 PM ~000002ms] => Sample.methodThatLogs() - IN
+[May 20, 2021, 9:44:17 PM ~000047ms]    => Sample.innerMethod() - IN
+[May 20, 2021, 9:44:17 PM ~000001ms]       Variable: i = '0'
+[May 20, 2021, 9:44:17 PM ~000000ms]    <= Sample.innerMethod() - OUT
+```
+The important part here is `~000047ms` which represents the number of milliseconds that have passed since the previous line SimpleLogger 
+ logged. This allows an easy way to detect bottlenecks by adding log statements and test improvements.

approvaltests-util/docs/reference/SimpleLogger.md

@@ -16,6 +16,29 @@ for test purposes, rather than setting a verbosity level. For example, you could
 or "Show me all the method entries". Also, because SimpleLogger is tagging based on the event type, it has many 
 convenience functions to properly format and call based on that format.
 
+### Differences vs. System.out
+* **Single point of control**  
+  SimpleLogger puts a single place where you can collect all log statements. From here it is trivial to log to a file or
+  string or both. SimpleLogger also allows you to easily turn off types of logging allowing you to control the 
+  signal-to-noise ratio.
+* **Convenience functions for metadata**  
+  SimpleLogger adds formatting and class names making logs consistent and robust after changing method or class names.
+  This helps with both the writing and the reading of the logs.
+* **Time stamps**  
+  SimpleLogger automatically adds timestamps plus time differences to easily detected when a problem happened and where a performance bottleneck is
+### Differences vs. Log4J
+* **Don't need to hold on to logging objects**    
+  The common patter for Log4J is that every class has a field named `LOG`
+  This tends to clutter up your files. SimpleLogger does not do this, opting instead to make all of its calls static.
+* **Finer control over turning off noise**  
+  Log4J will allow you to set a level of output. In practice, this usually means everything, or just warnings.
+  SimpleLogger, instead, allows you to toggle individual event types.
+  For example, the following would allow you to turn on only the queries and where they came from:  
+  snippet: simple_logger_toggles
+* **Can be used concurrently with SimpleLogger**  
+  There is nothing that prevents using both simultaneously
+### Logging method calls
+
 For example, here's how you would log entry and exit from a method:
 <!-- snippet: simple_logger_use_markers -->
 <a id='snippet-simple_logger_use_markers'></a>
@@ -62,6 +85,7 @@ Will produce the following logs:
 
 ## HowTos
 * [How to capture logs for testing](../how_to/CaptureLogs.md#top)
+* [How to do performance profiling](../how_to/PerformanceProfilingWithSimpleLogger.md#top)
 
 ## SimpleLogger.logToNothing()
 

approvaltests-util/src/main/java/com/spun/util/logger/SimpleLogger.java

@@ -121,4 +121,8 @@ public static Appendable getLogTo()
   {
     return log.getLogTo();
   }
+
+  public static SimpleLoggerInstance get() {
+    return log;
+  }
 }