Merge pull request #77 from inkade/master

Update README.md

Author: oxinabox

README.md

@@ -8,35 +8,20 @@
 
 # Discussion: Compositional Loggers
 
-LoggingExtras is designs around allowing you to build arbitrarily complicated
-systems for "log plumbing". That is to say basically routing logged information to different places.
-It is built around the idea of simple parts which are composed together,
-to allow for powerful and flexible definition of your logging system.
-Without you having to define any custom loggers by subtyping `AbstractLogger`.
-When we talk about composability we mean to say that the composition of any set of Loggers is itself a Logger.
-LoggingExtras is a composable logging system.
-
-Loggers can be broken down into 4 types:
- - *Sinks*: Sinks are the final end point of a log messages journey. They write it to file, or display it on the console, or set off a red flashing light in the laboratory. A Sink should never decide what to accept, only what to do with it.
- - *Filters*: Filters wrap around other loggers and decide whether or not to pass on a message. They can further be broken down by when that decision occurs (See `ActiveFilteredLogger` vs `EarlyFilteredLogger`).
- - *Transformers*: Transformers modify the content of log messages, before passing them on. This includes the metadata like severity level. Unlike Filters they can't block a log message, but they could drop its level down to say `Debug` so that normally noone would see it.
- - *Demux*: There is only one possible Demux Logger. and it is central to log routing. It acts as a hub that receives 1 log message, and then sends copies of it to all its child loggers. Like in the diagram above, it can be composed with Filters to control what goes where.
-
-This is a basically full taxonomy of all compositional loggers.
-This package implements the full set. So you shouldn't need to build your own routing components, just configure the ones included in this package.
-
-It is worth understanding the idea of logging purity.
-The loggers defined in this package are all pure.
-The Filters, only filter, the Sinks only sink, the transformers only Transform.
-
-We can contrast this to the the `ConsoleLogger` (the standard logger in the REPL).
-The `ConsoleLogger` is an impure sink.
-As well as displaying logs to the user (as a Sink);
-it uses the log content, in the form of the `max_log` kwarg to decide if a log should be displayed (Active Filtering);
-and it has a min_enabled_level setting, that controls if it will accept a message at all
-(Early Filtering, in particular see `MinLevelLogger`).
-If it was to be defined in a compositional way,
-we would write something along the lines of:
+LoggingExtras allows routing logged information  to different places when constructing complicated "log plumbing" systems. Built upon the concept of simple parts composed together, subtyping `AbstractLogger` provides a powerful and flexible definition for your logging system without a need to define any custom loggers. When we talk about composability, the composition of any set of Loggers is itself a Logger, and LoggingExtras is a composable logging system.
+
+Loggers break down into four types:
+ - *Sinks*: Sinks are the endpoint of a log message journey. They write it to file or display it on the console or set off a red flashing light in the laboratory. A Sink should never decide what to accept, only what to do with it.
+ - *Filters*: Filters wrap around other loggers and decide whether or not to pass on a message. When that decision occurs, they can be further broken down (See `ActiveFilteredLogger` vs `EarlyFilteredLogger`).
+ - *Transformers*: Transformers modify the content of log messages before passing them on, including metadata, such as severity level. Unlike Filters, they can't block a log message, but they could drop its level down to say Debug so that usually no one would see it.
+ - *Demux*: There is only one possible Demux Logger, and it is central to log routing. It acts as a hub that receives one log message and then sends copies to all its child loggers. Like in the diagram above, it can be composed with Filters to control what goes where.
+
+This is a complete taxonomy of all compositional loggers, with this package implementing the entire set. As such, there should be no need to build routing components when configuring the ones included in this package.    
+
+It is worth understanding the idea of logging purity. The loggers defined in this package are all pure. The Filters only filter, the Sinks only sink, and the transformers only Transform.
+
+We can contrast this to the `ConsoleLogger` (the standard logger in the REPL). The `ConsoleLogger` is an impure sink. As well as displaying logs to the user (as a Sink); it uses the log content, in the form of the `max_log`, to decide whether to display a log (Active Filtering); and it has a min_enabled_level setting that controls if it will accept a message at all (Early Filtering, in particular, see `MinLevelLogger`).
+If defined in a compositional way, we would write something along the lines of:
 ```julia
 ConsoleLogger(stream, min_level) =
     MinLevelLogger(
@@ -49,14 +34,14 @@ ConsoleLogger(stream, min_level) =
 
 
 # Usage
-Load the package with `using LoggingExtras`.
+Load the package `using LoggingExtras`.
 For convenience, this also re-exports the `Logging` standard library.
 
 
 ### Basics of working with loggers
 For full details, see the [Julia documentation on Logging](https://docs.julialang.org/en/v1/stdlib/Logging/index.html)
 
-To use a `logger` in a given scope do
+To use a `logger` in a given scope, do
 ```julia
 with_logger(logger) do
     #things
@@ -80,45 +65,44 @@ logger = global_logger()
 
 
 # Loggers introduced by this package:
-This package introduces 8 new loggers.
-The `TeeLogger`, the `TransformerLogger`, 3 types of filtered logger, the `FileLogger`,
+This package introduces eight new loggers;
+the `TeeLogger`, the `TransformerLogger`, and three types of filtered logger, the `FileLogger`,
 the `DatetimeRotatingFileLogger` and the `FormatLogger`.
 All of them, except `FormatLogger`, just wrap existing loggers.
  - The `TeeLogger` sends the logs to multiple different loggers.
- - The 3 filter loggers are used to control if a message is written or not
-     - The `MinLevelLogger` only allows messages to pass that are above a given level of severity
-     - The `EarlyFilteredLogger` lets you write filter rules based on the `level`, `module`, `group` and `id` of the log message
-     - The `ActiveFilteredLogger` lets you filter based on the full content
+ - The filter loggers control whether to write a message or not.
+     - The `MinLevelLogger` only allows messages to pass above a given severity level.
+     - The `EarlyFilteredLogger` lets you write filter rules based on the log message's `level`, `module`, `group` and `id`.
+     - The `ActiveFilteredLogger` lets you filter based on the full content.
  - The `TransformerLogger` applies a function to modify log messages before passing them on.
  - The `FileLogger` is a simple logger sink that writes to file.
  - The `DatetimeRotatingFileLogger` is a logger sink that writes to file, rotating logs based upon a user-provided `DateFormat`.
- - The `FormatLogger` is a logger sink that simply formats the message and writes to the logger stream.
+ - The `FormatLogger` is a logger sink that formats the message and writes to the logger stream.
  - The `LevelOverrideLogger` for overriding the log level of other loggers
 
-By combining `TeeLogger` with filter loggers you can arbitrarily route log messages, wherever you want.
+By combining `TeeLogger` with filter loggers, you can arbitrarily route log messages wherever you want.
 
 
 ## `TeeLogger` (*Demux*)
 
 The `TeeLogger` sends the log messages to multiple places.
 It takes a list of loggers.
 You often want to pass the `current_logger()` or `global_logger()`
-as one of those inputs so it keeps going to that one as well.
+as one of those inputs, so it also keeps going to that one.
 
-It is up to those loggers to determine if they will accept it.
-Which they do using their methods for `shouldlog` and `min_enabled_level`.
-Or you can do, by wrapping them in a filtered logger  as discussed below.
+It is up to those loggers to determine if they will accept it, which they do by using their methods for `shouldlog` and `min_enabled_level`.
+Or you can wrap them in a filtered logger, as discussed below.
 
 ## `ActiveFilteredLogger` (*Filter*)
 
-The `ActiveFilteredLogger` exists to give more control over which messages should be logged.
-It warps any logger, and before sending messages to the logger to log,
+The `ActiveFilteredLogger` exists to give more control over the messages logged.
+It warps any logger and, before sending messages to the logger to log,
 checks them against a filter function.
 The filter function takes the full set of parameters of the message.
 (See it's docstring with `?ActiveFilteredLogger` for more details.)
 
 ### Demo
-We want to filter to only log strings staring with `"Yo Dawg!"`.
+We want to filter only log strings starting with `"Yo Dawg!"`.
 
 ```julia
 julia> function yodawg_filter(log_args)
@@ -141,8 +125,9 @@ end
 
 ### Respecting `maxlog` convention
 
-An `ActiveFilterLogger` can be used to wrap another logger to obey `maxlog` directives, for example,
-similar to the `make_throttled_logger` example below,
+An `ActiveFilterLogger` can be used to wrap another logger to obey `maxlog` directives; for example,
+similar to the `make_throttled_logger` example below, it wraps another logger to filter logs that have already fired `maxlog` many times.
+See <https://docs.julialang.org/en/v1/stdlib/Logging/#Logging.@logmsg> for more on `maxlog`.
 ```julia
 function make_maxlog_logger(logger)
     counts = Dict{Any,Int}()
@@ -160,22 +145,21 @@ function make_maxlog_logger(logger)
     end
 end
 ```
-wraps another logger to filter logs that have already fired `maxlog` many times.
-See <https://docs.julialang.org/en/v1/stdlib/Logging/#Logging.@logmsg> for more on `maxlog`.
+
 
 ## `EarlyFilteredLogger` (*Filter*)
 
-The `EarlyFilteredLogger` is similar to the `ActiveFilteredLogger`,
-but it runs earlier in the logging pipeline.
-In particular it runs before the message is computed.
-It can be useful to filter things early if creating the log message is expensive.
+The `EarlyFilteredLogger` is similar to the `ActiveFilteredLogger`
+but runs earlier in the logging pipeline.
+In particular, it runs before the computation of the message.
+It can be useful to filter things early if creating the log message is expensive,
 E.g. if it includes summary statistics of the error.
 The filter function for early filter logging only has access to the
 `level`, `_module`, `id` and `group` fields of the log message.
-The most notable use of it is to filter based on modules,
+Its most notable use is filtering based on modules;
 see the HTTP example below.
 
-Another example is using them to stop messages every being repeated within a given time period.
+Another example is using them to stop repeated messages within a given period.
 
 ```julia
 using Dates, LoggingExtras
@@ -214,8 +198,8 @@ end
 ```
 
 ## `MinLevelLogger` (*Filter*)
-This is basically a special case of the early filtered logger,
-that just checks if the level of the message is above the level specified when it was created.
+This is a special case of the early filtered logger
+that checks if the message level is above the level specified when created.
 
 ### Demo: filter out all the log messages that are less severe than `Error`
 
@@ -235,12 +219,12 @@ julia> with_logger(error_only_logger) do
 
 ## `TransformerLogger` (*Transformer*)
 The transformer logger allows for the modification of log messages.
-This modification includes such things as its log level, and content,
+This modification includes its log level, content,
 and all the other arguments passed to `handle_message`.
 
-When constructing a `TransformerLogger` you pass in a transformation function,
-and a logger to be wrapped.
-The  transformation function takes a named tuple containing all the log message fields,
+When constructing a `TransformerLogger` you pass in a transformation function
+and a logger to wrap.
+The  transformation function takes a named tuple containing all the log message fields
 and should return a new modified named tuple.
 
 A simple example of its use is truncating messages.
@@ -267,26 +251,26 @@ end
 [ Info: Not like this one, that is is short
 ```
 
-It can also be used to do things such as change the log level of messages from a particular module (see the example below).
+`TransformerLogger` can also be used to do things such as change the log level of messages from a particular module (see the example below).
 Or to set common properties for all log messages within the `with_logger` block,
-for example to set them all to the same `group`.
+for example, to set them all to the same `group`.
 
 ## `FileLogger` (*Sink*)
 The `FileLogger` does logging to file.
-It is just a convenience wrapper around the base julia `SimpleLogger`,
-to make it easier to pass in a filename, rather than a stream.
-It is really simple.
+It is just a convenience wrapper around the base Julia `SimpleLogger`,
+to make it easier to pass in a filename rather than a stream.
+It is straghtforward:
  - It takes a filename,
- - a kwarg to check if should `always_flush` (default: `true`).
- - a kwarg to `append` rather than overwrite (default `false`. i.e. overwrite by default)
-The resulting file format is similar to that which is shown in the REPL.
+ - It uses a kwarg to check if it should `always_flush` (default: `true`).
+ - Uses a kwarg to `append` rather than overwrite (default `false`. i.e. overwrite by default).
+The resulting file format is similar to that shown in the REPL.
 (Not identical, but similar)
 
-**NOTE**: To print to the file in a specific format, e.g. to create a JSON log, use
+**NOTE**: To print the file in a specific format, e.g. to create a JSON log, use
 `FormatLogger` instead.
 
 ### Demo: `TeeLogger` and `FileLogger`
-We are going to log info and above to one file,
+We will log info and above to one file,
 and warnings and above to another.
 
 ```julia
@@ -322,8 +306,8 @@ shell>  cat info.log
 
 ## `DatetimeRotatingFileLogger` (*Sink*)
 Use this sink to rotate your logs based upon a given `DateFormat`, automatically closing one file and opening another
-when the `DateFormat` would change the filename.  Note that if you wish to have static portions of your filename, you must
-escape them so they are not interpreted by the `DateFormat` code.  Example:
+when the `DateFormat` changes the filename.  Note that if you wish to have static portions of your filename, you must 
+escape them to prevent interpretation by the `DateFormat` code.  Example:
 
 ```julia
 julia> using LoggingExtras
@@ -342,19 +326,19 @@ julia> filter(f -> endswith(f, ".log"), readdir(pwd()))
  "access-2020-07-13-13-25.log"
 ```
 
-The user implicitly controls when the files will be rolled over based on the `DateFormat` given.
-To post-process the newly rotated file pass `rotation_callback::Function` as a keyword argument.
+The user implicitly controls when the files are rolled over based on the `DateFormat` given.
+To post-process the newly rotated file, pass `rotation_callback::Function` as a keyword argument.
 See the docstring with (`?DatetimeRotatingFileLogger` in the REPL) for more details.
 
-To control the logging output it is possible to pass a formatter function as the first argument
-in the constructor. See `FormatLogger` for the requirements on the formatter function.
+To control the logging output, passing a formatter function as the first argument in the constructor
+is possible. See FormatLogger for the requirements on the formatter function.
 
 ## `FormatLogger` (*Sink*)
-The `FormatLogger` is a sink that formats the message and prints to a wrapped IO.
-Formatting is done by providing a function `f(io::IO, log_args::NamedTuple)`.
+The `FormatLogger` is a sink that formats the message and prints it to a wrapped IO
+with formatting provided by providing a function `f(io::IO, log_args::NamedTuple)`.
 
-`FormatLogger` can take as its second argument either a writeable `IO` or a filepath. The `append::Bool` keyword
-argument determines whether the file is opened in append mode (`"a"`) or truncate mode (`"w"`).
+`FormatLogger` can take either a writeable `IO` or a filepath as its second argument. The `append::Bool` keyword
+argument determines whether to open the file in append mode (`"a"`) or truncate mode (`"w"`).
 
 ```julia
 julia> using LoggingExtras
@@ -378,9 +362,10 @@ Main | [Warn] This is a warning, should take a look.
 ## `LevelOverrideLogger` (*Filter*)
 Allows overriding the minimum log level set by the logger it wraps.
 Useful when debug logging
-and used in conjuction with `Logging.with_logger` or `LoggingExtras.withlevel` to
+and used in conjunction with `Logging.with_logger` or `LoggingExtras.withlevel` to
 temporarily modify the current logger with a custom level.
-More generally useful if you want to use the current/global logger as a _sink_ but don't know if it is going to have a problematically high min log level set (as julia's default logger sets min level to `Info`).
+More generally applicable if you want to use the current/global logger as a _sink_ 
+but don't know if it will have a problematically high min log level set (as julia's default logger sets min level to `Info`).
 
 ```julia
 julia> using LoggingExtras
@@ -395,24 +380,24 @@ julia> with_logger(logger) do
 ```
 This is roughly complementary to the `MinLevelFilterLogger`.
 The `MinLevelFilterLogger` lets you effectively *raise* the level of any logger it wraps to meet the level you specify.
-The `LevelOverrideLogger` lets you *lower* (or *raise*) the level of the wrapped logger as it bypasses checks on it entirely.
+The `LevelOverrideLogger` enables you to *lower* (or *raise*) the level of the wrapped logger as it bypasses checks on it entirely.
 
 # Utilities
 
 ## Verbosity macros
-Sometimes when logging, it is desirable to be able to specify a verbosity level along with
-the log level, and to be able to filter on verbosity levels. For example, you may want multiple levels
-of verbosity for `Debug` log statements. LoggingExtras.jl exports verbosity macros that act like their
-non-verbose counterparts, but allow specifying a verbosity level as well:
+Sometimes when logging, it is desirable to specify a verbosity level along with
+the log level and to be able to filter on verbosity levels. For example, you may want multiple 
+verbosity levels for `Debug` log statements. LoggingExtras.jl exports verbosity macros that act like their
+non-verbose counterparts but allow specifying a verbosity level as well:
   * `@debugv N msg`
   * `@infov N msg`
   * `@warnv N msg`
   * `@errorv N msg`
 
-For verbosity filtering, the `LoggingExtras.withlevel(f, Info; verbosity=0)` utlility is provided
-for temporarily (i.e. while `f()` is executed) allowing log messages with `level` and `verbosity`.
-This is very handy for allowing finer grained control in debug logging for long-running or complex user API function
-calls. For example:
+For verbosity filtering, the `LoggingExtras.withlevel(f, Info; verbosity=0)` utility is provided, 
+temporarily (i.e. while `f()` is executed) allowing log messages with `level` and `verbosity`.
+This is very handy for allowing finer-grained debug logging control for long-running or complex user API function calls.
+For example:
 
 ```julia
 using LoggingExtras