Add documentation covering all current aspects of the configuration file (#308)

* Add documentation covering all current aspects of the configuration file

* ci: add lint workflow

* chore: review markdown

* docs: Add the configuration doc to docs.rs

* chore: review comments. Bump min rust version

* chore(docs): bump rust version in readme

* fix(docs): markdown lint fixes for new doc and README

* fix: missing newline

* fix(ci): Resolve clippy issues

* chore: move config docs, dedub section, add examples link

Author: Bryan Conn

.github/workflows/main.yml

@@ -11,7 +11,7 @@ on:
     - devel
 
 jobs:
-  lint:
+  rust-lint:
     name: Lint
     runs-on: ubuntu-latest
     steps:
@@ -37,7 +37,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        rust_versions: ["stable", "1.56"]
+        rust_versions: ["stable", "1.57"]
         os: [ubuntu-latest, windows-latest]
     steps:
       - name: Checkout the source code
@@ -81,7 +81,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        rust_versions: ["stable", "1.56"]
+        rust_versions: ["stable", "1.57"]
     steps:
       - name: Checkout the source code
         uses: actions/checkout@master
@@ -93,3 +93,13 @@ jobs:
 
       - name: Rotation with backgrounded rotation
         run: cargo bench  --features gzip,background_rotation
+
+  docs-lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Markdown Linting Action
+        uses: avto-dev/markdown-lint@v1.5.0
+        with:
+          config: .markdownlint.yml
+          args: docs/Configuration.md README.md

.markdownlint.yml

@@ -0,0 +1 @@
+line-length: false

Cargo.toml

@@ -8,7 +8,7 @@ repository = "https://github.com/estk/log4rs"
 readme = "README.md"
 keywords = ["log", "logger", "logging", "log4"]
 edition = "2018"
-rust = "1.56"
+rust = "1.57"
 
 [features]
 default = ["all_components", "config_parsing", "yaml_format"]
@@ -58,7 +58,7 @@ chrono = { version = "0.4", optional = true }
 flate2 = { version = "1.0", optional = true }
 fnv = "1.0"
 humantime = { version = "2.0", optional = true }
-log = { version = "0.4.0", features = ["std"] }
+log = { version = "=0.4.17", features = ["std"] }
 log-mdc = { version = "0.1", optional = true }
 serde = { version = "1.0", optional = true, features = ["derive"] }
 serde-value = { version = "0.7", optional = true }

README.md

@@ -9,7 +9,7 @@
 log4rs is a highly configurable logging framework modeled after Java's Logback
 and log4j libraries.
 
-### Warning
+## Warning
 
 If you are using the file rotation in your configuration there is a known substantial performance issue so listen up!
 By default the `gzip` feature is enabled and when rolling files it will zip log archives automatically. This is a problem
@@ -27,6 +27,7 @@ For more information see the PR that added [`background_rotation`](https://githu
 ## Quick Start
 
 log4rs.yaml:
+
 ```yaml
 refresh_rate: 30 seconds
 appenders:
@@ -52,6 +53,7 @@ loggers:
 ```
 
 lib.rs:
+
 ```rust
 use log::{error, info, warn};
 use log4rs;
@@ -67,7 +69,7 @@ fn main() {
 
 ## Rust Version Requirements
 
-1.46
+1.57
 
 ## Building for Dev
 
@@ -79,8 +81,9 @@ fn main() {
 ## License
 
 Licensed under either of
- * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
+* MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
 
 at your option.
 

docs/Configuration.md

@@ -0,0 +1,240 @@
+# Configuration
+
+log4rs can be configured programmatically by using the builders in the `config`
+module to construct a log4rs `Config` object, which can be passed to the
+`init_config` function.
+
+The more common configuration method, however, is via a separate config file.
+The `init_file` function takes the path to a config file as well as a
+`Deserializers` object which is responsible for instantiating the various
+objects specified by the config file. The following section covers the exact
+configuration syntax. Examples of both the programatic and configuration files
+can be found in the
+[examples directory](https://github.com/estk/log4rs/tree/master/examples).
+
+## Common Fields
+
+### LevelFilter's
+
+- Off
+- Error
+- Warn
+- Info
+- Debug
+- Trace
+
+### Filters
+
+The only accepted `filter` is of kind threshold with a level. The level must
+be a [LevelFilter](#levelfilters). One to many filters are allowed.
+
+i.e.
+
+```yml
+filters:
+   - kind: threshold
+     level: info
+```
+
+### Encoder
+
+An `encoder` consists of a kind: the default which is pattern, or json. If
+pattern is defined, the default pattern `{d} {l} {t} - {m}{n}` is used unless
+overridden. Refer to
+[this documentation](https://docs.rs/log4rs/latest/log4rs/encode/pattern/index.html#formatters)
+for details regarding valid patterns.
+
+> Note that the json encoder does not have any additional controls such as the
+> pattern field.
+
+i.e.
+
+```yml
+encoder:
+   kind: pattern
+   pattern: "{h({d(%+)(utc)} [{f}:{L}] {l:<6} {M}:{m})}{n}"
+```
+
+## Loggers
+
+A map of logger configurations.  
+
+### Logger Configuration
+
+The _name_ of the logger is the yml tag.
+
+The _level_ of the logger is optional and defaults to the parents log level.
+The level must be a [LevelFilter](#levelfilters).
+
+The _appenders_ field is an optional list of [appenders](#appenders) attached
+to the logger.
+
+The _additive_ field is an optional boolean determining if the loggers parent
+will also be attached to this logger. The default is true.
+
+i.e.
+
+```yml
+loggers:
+   my_logger:
+      level: info
+      appenders:
+         - my_appender
+      additive: true
+```
+
+## The Root Logger
+
+Root is the required logger. It is the parent to all children loggers. To
+configure the Root, refer to [the logger section](#logger-configuration).
+
+> Note: The root logger has no parent and therefore cannot the _additive_
+field does not apply.
+
+```yml
+root:
+   level: info
+   appenders:
+      - my_appender
+```
+
+## Appenders
+
+All appenders require a unique identifying string for each
+[appender configuration](#appender-config).
+
+### Appender Config
+
+Each Appender Kind has it's own configuration. However, all accept
+[filters](#filters). The `kind` field is required in an appender configuration.
+
+#### The Console Appender
+
+The _target_ field is optional and accepts `stdout` or `stderr`. It's default
+value is stdout.
+
+The _tty_only_ field is an optional boolean and dictates that the appender must
+only write when the target is a TTY. It's default value is false.
+
+The _encoder_ field is optional and can consist of multiple fields. Refer to
+the [encoder](#encoder) documention.
+
+```yml
+my_console_appender:
+   kind: console
+   target: stdout
+   tty_only: false
+```
+
+#### The File Appender
+
+The _path_ field is required and accepts environment variables of the form
+`$ENV{name_here}`. The path can be relative or absolute.
+
+The _encoder_ field is optional and can consist of multiple fields. Refer to
+the [encoder](#encoder) documention.
+
+The _append_ field is an optional boolean and defaults to `true`. True will
+append to the log file if it exists, false will truncate the existing file.
+
+```yml
+my_file_appender:
+   kind: file
+   path: $ENV{PWD}/log/test.log
+   append: true
+```
+
+#### The Rolling File Appender
+
+The rolling file configuration is by far the most complex. Like the
+[file appender](#the-file-appender), the path to the log file is required
+with the _append_ and the _encoders_ optional fields.
+
+i.e.
+
+```yml
+my_rolling_appender:
+   kind: rolling_file
+   path: "logs/test.log"
+   policy:
+      kind: compound
+      trigger:
+         kind: size
+         limit: 1mb
+      roller:
+         kind: fixed_window
+         base: 1
+         count: 5
+         pattern: "logs/test.{}.log"
+```
+
+The new component is the _policy_ field. A policy must have `kind` like most
+other components, the default (and only supported) policy is `kind: compound`.
+
+The _trigger_ field is used to dictate when the log file should be rolled. The
+only supported trigger is  `kind: size`. There is a required field `limit`
+which defines the maximum file size prior to a rolling of the file. The limit
+field requires one of the following units in bytes, case does not matter:
+
+- b
+- kb/kib
+- mb/mib
+- gb/gib
+- tb/tib
+
+i.e.
+
+```yml
+trigger:
+   kind: size
+   limit: 10 mb
+```
+
+The _roller_ field supports two types: delete, and fixed_window. The delete
+roller does not take any other configuration fields. The fixed_window roller
+supports three fields: pattern, base, and count. The most current log file will
+always have the _base_ index.
+
+The _pattern_ field is used to rename files. The pattern must contain the
+double curly brace `{}`. For example `archive/foo.{}.log`. Each instance of
+`{}` will be replaced with the index number of the configuration file. Note
+that if the file extension of the pattern is `.gz` and the `gzip` Cargo
+feature is enabled, the archive files will be gzip-compressed.
+
+> Note: This pattern field is only used for archived files. The `path` field
+of the higher level `rolling_file` will be used for the active log file.
+
+The _base_ field is the starting index used to name rolling files.
+
+The _count_ field is the exclusive maximum index used to name rolling files.
+However, be warned that the roller renames every file when a log rolls over.
+Having a large count value can negatively impact performance.
+
+i.e.
+
+```yml
+roller:
+   kind: fixed_window
+   base: 1
+   count: 5
+   pattern: "archive/journey-service.{}.log"
+```
+
+or
+
+```yml
+roller:
+   kind: delete
+```
+
+## Refresh Rate
+
+The _refresh_rate_ accepts a u64 value in seconds. The field is used to
+determine how often log4rs will scan the configuration file for changes. If a
+change is discovered, the logger will reconfigure automatically.
+
+i.e.
+
+```yml
+refresh_rate: 30 seconds
+```

src/append/console.rs

@@ -199,7 +199,7 @@ impl ConsoleAppenderBuilder {
             writer,
             encoder: self
                 .encoder
-                .unwrap_or_else(|| Box::new(PatternEncoder::default())),
+                .unwrap_or_else(|| Box::<PatternEncoder>::default()),
             do_write,
         }
     }

src/append/file.rs

@@ -106,7 +106,7 @@ impl FileAppenderBuilder {
             file: Mutex::new(SimpleWriter(BufWriter::with_capacity(1024, file))),
             encoder: self
                 .encoder
-                .unwrap_or_else(|| Box::new(PatternEncoder::default())),
+                .unwrap_or_else(|| Box::<PatternEncoder>::default()),
         })
     }
 }

src/append/rolling_file/mod.rs

@@ -264,7 +264,7 @@ impl RollingFileAppenderBuilder {
             append: self.append,
             encoder: self
                 .encoder
-                .unwrap_or_else(|| Box::new(PatternEncoder::default())),
+                .unwrap_or_else(|| Box::<PatternEncoder>::default()),
             policy,
         };
 

src/append/rolling_file/policy/compound/roll/delete.rs

@@ -56,6 +56,6 @@ impl Deserialize for DeleteRollerDeserializer {
         _: DeleteRollerConfig,
         _: &Deserializers,
     ) -> anyhow::Result<Box<dyn Roll>> {
-        Ok(Box::new(DeleteRoller::default()))
+        Ok(Box::<DeleteRoller>::default())
     }
 }