tty-logger 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdcb294c5428dc04d50845cb289e13bd679d78343e3557f7de4423798475c0af
-  data.tar.gz: 600425284bc08e004523363bdc78ee4a4b8a37b05f0930a2eef4d0b013eb7b38
+  metadata.gz: 31142537abe01781e199d8b551eea32bdc802c1e9a46bec7947b3240249df798
+  data.tar.gz: 33b6816da36b2c41651452a9efa82b8e69b62eef6dbdfdc136c5195140b76d4b
 SHA512:
-  metadata.gz: 465c8e6fabae9d94f2b884715350ad3bbc1182f132d8e8b504d6b4b62a84669765d05ae60815bc79ffc83749ed43ab67a099f820708f1e1e3c3526b1de470258
-  data.tar.gz: d583794d9e15390b86138778cf5371a7401f1f1436af4c2fd15162dee2fdef54d9de663a96396915f5fd0c0139b1b42b8b20eda461f013903dcd6c831be6670a
+  metadata.gz: d5b65cbbe0a3c9cefcb3fe082242a47e6090626c41531fbd6f97dfc528e795b2e2f56f2ce5f27f1a0404620ce2a12139745e028a9d3a31a6bf630bb7c600f3fb
+  data.tar.gz: 9e19ee528817ea3ef0d4ccf5c4a9601857b69e3b2120ad8ca7b5715ca57ea164a346ecd7cd90ad253cc81b707820098a019b77ea54dff547e12e8384b7154477

data/CHANGELOG.md

@@ -1,7 +1,20 @@
 # Change log
 
+## [v0.2.0] - 2019-09-30
+
+### Added
+* Add ability to add structured data inside logging block
+* Add ability to filter sensitive data
+* Add ability to define custom log types
+* Add ability to temporarily log at different level
+* Add performance tests
+
+### Changed
+* Change to dynamically define log types
+
 ## [v0.1.0] - 2019-07-21
 
 * Initial implementation and release
 
+[v0.2.0]: https://github.com/piotrmurach/tty-logger/compare/v0.1.0..v0.2.0
 [v0.1.0]: https://github.com/piotrmurach/tty-logger/compare/v0.1.0

data/README.md

@@ -2,7 +2,7 @@
   <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://cdn.rawgit.com/piotrmurach/tty/master/images/tty.png" alt="tty logo" /></a>
 </div>
 
-# TTY::Logger
+# TTY::Logger [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
 
 [![Gem Version](https://badge.fury.io/rb/tty-logger.svg)][gem]
 [![Build Status](https://secure.travis-ci.org/piotrmurach/tty-logger.svg?branch=master)][travis]
@@ -30,6 +30,8 @@
 * Intuitive console output for an increased readability
 * Ability to stream data to any IO object
 * Supports structured data logging
+* Filters sensitive data
+* Allows to define custom log types
 * Formats and truncates messages to avoid clogging logging output
 * Customizable styling of labels and symbols for console output
 * Includes metadata information: time, location, scope
@@ -58,17 +60,21 @@ Or install it yourself as:
 * [2. Synopsis](#2-synopsis)
   * [2.1 Logging](#21-logging)
     * [2.1.1 Exceptions](#211-exceptions)
+    * [2.1.2 Types](#212-types)
   * [2.2 Levels](#22-levels)
+    * [2.2.1 Scoped Level](#22-scoped-levels)
   * [2.3 Structured Data](#23-structured-data)
   * [2.4 Configuration](#24-configuration)
     * [2.4.1 Metadata](#241-metadata)
-  * [2.5 Handlers](#25-handlers)
-    * [2.5.1 Console Handler](#251-console-handler)
-    * [2.5.2 Stream Handler](#252-stream-handler)
-    * [2.5.3 Custom Handler](#253-custom-handler)
-    * [2.5.4 Multiple Handlers](#254-multiple-handlers)
-  * [2.6 Formatters](#26-formatters)
-  * [2.7 Output streams](#27-output-streams)
+    * [2.4.2 Filters](#242-filters)
+  * [2.5 Cloning](#25-cloning)
+  * [2.6 Handlers](#26-handlers)
+    * [2.6.1 Console Handler](#261-console-handler)
+    * [2.6.2 Stream Handler](#262-stream-handler)
+    * [2.6.3 Custom Handler](#263-custom-handler)
+    * [2.6.4 Multiple Handlers](#264-multiple-handlers)
+  * [2.7 Formatters](#27-formatters)
+  * [2.8 Output streams](#28-output-streams)
 
 ## 1. Usage
 
@@ -78,7 +84,7 @@ Create logger:
 logger = TTY::Logger.new
 ```
 
-And log information using any of the logger [types](#21-types):
+And log information using any of the logger [built-in types](#212-types):
 
 ```ruby
 logger.info "Deployed successfully"
@@ -89,7 +95,7 @@ logger.info { "Dynamically generated info" }
 Include structured data:
 
 ```ruby
-logger.info "Deployed successfully", myapp: "myapp", env: "prod"
+logger.success "Deployed successfully", myapp: "myapp", env: "prod"
 # =>
 # ✔ success Deployed successfully     app=myapp env=prod
 ```
@@ -105,7 +111,7 @@ logger.info "Deployed successfully", myapp: "myapp", env: "prod"
 # [2019-07-17] [23:21:55.287] › ℹ info    Info about the deploy     app=myapp env=prod
 ```
 
-Or change structured data [formatting](#26-formatters) display to `JSON`:
+Or change structured data [formatting](#27-formatters) display to `JSON`:
 
 ```ruby
 logger = TTY::Logger.new do |config|
@@ -148,13 +154,23 @@ logger.success "Deployed", "successfully"
 
 You can delay message evaluation by passing it inside a block:
 
+```ruby
+logger.success { "Dynamically generated info" }
+# =>
+# ✔ success Dynamically generated info
 ```
-logger.info { "Dynamically generated info" }
+
+Similar to regular logging, you cal split your message into chunks inside a block:
+
+```ruby
+logger.success { ["Dynamically", "generated", "info"] }
 # =>
-# ✔ success Deployed successfully
+# ✔ success Dynamically generated info
 ```
 
-### 2.1.1 Exceptions
+The above comes handy when paired with [structured data](#23-structured-data).
+
+#### 2.1.1 Exceptions
 
 You can also report on exceptions.
 
@@ -164,7 +180,7 @@ For example, let's say you caught an exception about incorrect data format and u
 begin
   raise ArgumentError, "Wrong data"
 rescue => ex
-  logger.fatal("Error:", error)
+  logger.fatal("Error:", ex)
 end
 ```
 
@@ -178,6 +194,51 @@ This will result in a message followed by a full backtrace:
 #    rspec-core-3.8.2/lib/rspec/core/example.rb:257:in `block in run'
 ```
 
+#### 2.1.2 Types
+
+You can define custom log types via the `types` configuration option:
+
+For example, if you want to add `thanks` and `done` log types, you need to provide their names along with logging levels. You can further customise the `:console` output with your desired styling:
+
+```ruby
+logger = TTY::Logger.new do |config|
+  config.types = {
+    thanks: {level: :info},
+    done: {level: :info}
+  }
+  config.handlers = [
+    [:console, {
+      styles: {
+        thanks: {
+          symbol: "❤️ ",
+          label: "thanks",
+          color: :magenta,
+          levelpad: 0
+        },
+        done: {
+          symbol: "!!",
+          label: "done",
+          color: :green,
+          levelpad: 2
+        }
+      }
+    }]
+  ]
+end
+```
+
+Once defined, you can call new log types:
+
+```ruby
+logger.thanks("Great work!")
+logger.done("Work done!")
+# =>
+# ❤️  thanks Great work!
+# !! done   Work done!
+```
+
+![](assets/tty-logger-custom-log-types.png)
+
 ### 2.2 Levels
 
 The supported levels, ordered by precedence, are:
@@ -192,17 +253,17 @@ So the order is: `:debug` < `:info` < `:warn` < `:error` < `:fatal`
 
 For example, `:info` takes precedence over `:debug`. If your log level is set to `:info`, `:info`, `:warn`, `:error` and `:fatal` will be printed to the console. If your log level is set to `:warn`, only `:warn`, `:error` and `:fatal` will be printed.
 
-You can set level using the `level` configuration option. The value can be a symbol, a string or level constant. For example, `:info`, `INFO` or `TTY::Logger::INFO_LEVEL` will quality as valid level value.
+You can set level using the `level` configuration option. The value can be a symbol, a string or level constant. For example, `:info`, `INFO` or `TTY::Logger::INFO_LEVEL` will qualify as valid level value.
 
 ```ruby
 TTY::Logger.new do |config|
-  config.level = :info # or "INFO" / TTY::Logger::INFO_LEVEL
+  config.level = :info # or "INFO" or TTY::Logger::INFO_LEVEL
 end
 ```
 
 Or you can specific level for each log events handler.
 
-For example, to log messages above info level to a stream and only error level events to the console do:
+For example, to log messages above `:info` level to a stream and only `:error` level events to the console do:
 
 ```ruby
 logger = TTY::Logger.new do |config|
@@ -213,7 +274,34 @@ logger = TTY::Logger.new do |config|
 end
 ```
 
-You can also change the [output streams](#27-output-streams) for each handler.
+You can also change the [output streams](#28-output-streams) for each handler.
+
+#### 2.2.1 Scoped Level
+
+You can temporarily change level, raise it or lower it by using the `log_at` call. By default messages are logged at `:info` level, but you can change this for the duration of a block:
+
+```ruby
+logger = TTY::Logger.new
+
+logger.info("not logged")
+
+logger.log_at :debug do
+  logger.debug("logged")
+end
+# =>
+# • debug   logged
+```
+
+Or elevating level to error with a constant `ERROR_LEVEL`:
+
+```ruby
+logger.log_at TTY::Logger::ERROR_LEVEL do
+  logger.debug("not logged")
+  logger.error("logged")
+end
+# =>
+# ⨯ error   logged
+```
 
 ### 2.3 Structured data
 
@@ -236,16 +324,26 @@ logger.wait "Ready to deploy", app: "myapp", env: "prod"
 # … waiting Ready to deploy           app=myapp env=prod
 ```
 
+You can delay data evaluation until it's evaluated by passing it inside a block:
+
+```ruby
+logger.wait { ["Ready to deploy", {app: "myapp", env: "prod"}] }
+# =>
+# … waiting Ready to deploy           app=myapp env=prod
+```
+
 ### 2.4 Configuration
 
 All the configuration options can be changed globally via `configure` or per logger instance via object initialization.
 
-* `:formatter` - the formatter used to display structured data. Defaults to `:text`. see [Formatters](#26-formatters) for more details.
-* `:handlers` - the handlers used to log messages. Defaults to `[:console]`. See [Handlers](#25-handlers) for more details.
+* `:filters` - the storage of placeholders to filter sensitive data out from the logs. Defaults to `{}`.
+* `:formatter` - the formatter used to display structured data. Defaults to `:text`. See [Formatters](#27-formatters) for more details.
+* `:handlers` - the handlers used to log messages. Defaults to `[:console]`. See [Handlers](#26-handlers) for more details.
 * `:level` - the logging level. Any message logged below this level will be simply ignored. Each handler may have it's own default level. Defaults to `:info`
 * `:max_bytes` - the maximum message size to be logged in bytes. Defaults to `8192` bytes. The truncated message will have `...` at the end.
 * `:max_depth` - the maximum depth for nested structured data. Defaults to `3`.
 * `:metadata` - the meta info to display before the message, can be `:pid`, `:date`, `:time` or `:file`. Defaults to empty array `[]`, no metadata. Setting this to `:all` will print all the metadata.
+* `:types` - the new custom log types. Defaults to `{}`.
 
 For example, to configure `:max_bytes`, `:level` and `:metadata` for all logger instances do:
 
@@ -275,7 +373,69 @@ The `:metdata` configuration option can include the following symbols:
 * `:time` - the log event time
 * `:file` - the file with a line number the log event is triggered from
 
-### 2.5 Handlers
+### 2.4.2 Filters
+
+You can filter sensitive data out of log output with `filters` configuration option. As a value provide a list of sensitive data items:
+
+```ruby
+logger = TTY::Logger.new(output: output) do |config|
+  config.filters = ["secret", "password"]
+end
+```
+
+Which by default will replace each data item with `[FILTERED]` placeholder:
+
+```ruby
+logger.info("Super secret info with password")
+# =>
+# ℹ info    Super [FILTERED] info with [FILTERED]
+```
+
+You can also replace each data item with a custom placeholder. To do so use a hash with pairs of matched text and replacement placeholder.
+
+For example, to replace "secret" content with placeholder "<SECRET>" do:
+
+```ruby
+logger = TTY::Logger.new do |config|
+  config.filters = { "secret" => "<SECRET>" }
+end
+```
+
+When logged, it will produce:
+
+```ruby
+logger.info("Super secret info")
+# =>
+# ℹ info    Super <SECRET> info
+```
+
+### 2.5 Cloning
+
+You can create a copy of a logger with the current configuration using the `copy` method.
+
+For example, given the following logger with `:app` and `:env` data:
+
+```ruby
+logger = TTY::Logger.new(fields: {app: "parent", env: "prod"})
+```
+
+We can create a copy with a custom configuration that changes filtered message content and `:app` data:
+
+```ruby
+child_logger = logger.copy(app: "child") do |config|
+  config.filters = ["logging"]
+end
+```
+
+```ruby
+logger.info("Parent logging")
+child_logger.warn("Child logging")
+# =>
+# ℹ info    Parent logging            app=parent env=prod
+# ⚠ warning Child [FILTERED]          app=child env=prod
+```
+
+### 2.6 Handlers
 
 `TTY::Logger` supports many ways to handle log messages.
 
@@ -285,7 +445,7 @@ The available handlers by default are:
 * `:null` - discards any log messages
 * `:stream` - log messages to an `IO` stream, a file, a socket or a console.
 
-You can also implement your own [custom handler](#253-custom-handler).
+You can also implement your own [custom handler](#263-custom-handler).
 
 The handlers can be configured via global or instance configuration with `handlers`. The handler can be a name or a class name:
 
@@ -311,7 +471,7 @@ logger.add_handler(:console)
 logger.remove_handler(:console)
 ```
 
-#### 2.5.1 Console handler
+#### 2.6.1 Console Handler
 
 The console handler prints log messages to the console. It supports the following options:
 
@@ -326,9 +486,9 @@ The supported options in the `:styles` are:
 * `:color` - the color for the log message.
 * `:levelpad` - the extra amount of padding used to display log label.
 
-See the [TTY::Logger::Handlers::Console]() for full list of styles.
+See the [TTY::Logger::Handlers::Console](https://github.com/piotrmurach/tty-logger/blob/master/lib/tty/logger/handlers/console.rb) for full list of styles.
 
-Console handler has many defaults styles such as `success` and `error`:
+Console handler has many default styles such as `success` and `error`:
 
 ```ruby
 logger = TTY::Logger.new
@@ -339,7 +499,7 @@ logger.error("Default error")
 # ⨯ error   Default error
 ```
 
-You can change console handler default style with a tuple of handler name and options hash.
+You can change the default styling with a tuple of handler name and options hash.
 
 In our example, we want to change the styling of `success` and `error`:
 
@@ -353,7 +513,7 @@ new_styles = {
     error: {
       symbol: "!",
       label: "Dooh",
-      levelpad: 3
+      levelpad: 3 # the amount of extra padding to align level names in a column
     }
   }
 }
@@ -362,18 +522,18 @@ new_styles = {
 And then use the `new_styles` when providing `handlers` configuration:
 
 ```ruby
-new_style = TTY::Logger.new do |config|
-  config.handlers = [:console, new_styles]
+styled_logger = TTY::Logger.new do |config|
+  config.handlers = [[:console, new_styles]]
 end
 
-new_style.success("Custom success")
-new_style.error("Custom error")
+styled_logger.success("Custom success")
+styled_logger.error("Custom error")
 # =>
-+ Ohh yes Custom success
-! Dooh    Custom error
+# + Ohh yes Custom success
+# ! Dooh    Custom error
 ```
 
-#### 2.5.2 Stream handler
+#### 2.6.2 Stream handler
 
 To send log event data outside of console to another service or `IO` stream, you can use `:stream` handler.
 
@@ -387,7 +547,7 @@ end
 By default, the output will be a plain text streamed to console. The text contains key and value pairs of all the metadata and the message of the log event.
 
 ```ruby
-loggger.info("Info about the deploy", app="myap", env="prod")
+loggger.info("Info about the deploy", app:"myap", env:"prod")
 # =>
 # pid=18315 date="2019-07-21" time="15:42:12.463" path="examples/stream.rb:17:in`<main>`"
 # level=info message="Info about the deploy" app=myapp env=prod
@@ -411,7 +571,7 @@ loggger.info("Info about the deploy", app="myap", env="prod")
 # "level":"info","message":"Info about the deploy","app":"myapp","env":"prod"}
 ```
 
-#### 2.5.3 Custom Handler
+#### 2.6.3 Custom Handler
 
 You can create your own log event handler if the default ones don't match your needs.
 
@@ -471,7 +631,7 @@ logger = TTY::Logger.new
 logger.add_handler [MyHandler, label: "myhandler"]
 ```
 
-#### 2.5.4 Multiple Handlers
+#### 2.6.4 Multiple Handlers
 
 You can define as many handlers as you need. For example, you may log messages both to console and stream:
 
@@ -492,7 +652,7 @@ logger = TTY::Logger.new do |config|
 end
 ```
 
-### 2.6 Formatters
+### 2.7 Formatters
 
 The available formatters are:
 
@@ -514,7 +674,7 @@ TTY::Logger.new do |config|
   config.handlers = [:console, [:console, formatter: :json]]
 end
 ```
-### 2.7 Output Streams
+### 2.8 Output Streams
 
 By default all log events are output to `stderr`. You can change this using configuration `output` option. Any `IO`-like stream such as file, socket or console can be used. For example, to log all messages to a file do: