A readable, structured and beautiful logging for the terminal

TTY::Logger provides independent logging component for TTY toolkit.

• Intuitive console output for an increased readability
• Ability to stream data to any IO object
• Supports structured data logging
• Formats and truncates messages to avoid clogging logging output
• Customizable styling of labels and symbols for console output
• Includes metadata information: time, location, scope
• Handles multiple logging outputs

Add this line to your application's Gemfile:

gem 'tty-logger'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty-logger

• 1. Usage
• 2. Synopsis
  • 2.1 Logging
    • 2.1.1 Exceptions
  • 2.2 Levels
  • 2.3 Structured Data
  • 2.4 Configuration
    • 2.4.1 Metadata
  • 2.5 Handlers
    • 2.5.1 Console Handler
    • 2.5.2 Stream Handler
    • 2.5.3 Custom Handler
    • 2.5.4 Multiple Handlers
  • 2.6 Formatters
  • 2.7 Output streams

Create logger:

logger = TTY::Logger.new

And log information using any of the logger types:

logger.info "Deployed successfully"
logger.info "Deployed", "successfully"
logger.info { "Dynamically generated info" }

Include structured data:

logger.info "Deployed successfully", myapp: "myapp", env: "prod"
# =>
# ✔ success Deployed successfully     app=myapp env=prod

Add metadata information:

logger = TTY::Logger.new do |config|
  config.metadata = [:date, :time]
end
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 display to JSON:

logger = TTY::Logger.new do |config|
  config.formatter = :json
end
logger.info "Deployed successfully"
# =>
# [2019-07-17] [23:21:55.287] › ℹ info    Info about the deploy     {"app":"myapp","env":"prod"}

There are many logger types to choose from:

• debug - logs message at :debug level
• info - logs message at :info level
• success - logs message at :info level
• wait - logs message at :info level
• warn - logs message at :warn level
• error - logs message at :error level
• fatal - logs message at :fatal level

To log a message, simply choose one of the above types and pass in the actual message. For example, to log successfully deployment at info level do:

logger.success "Deployed successfully"
# =>
# ✔ success Deployed successfully

Or pass in multiple messages:

logger.success "Deployed", "successfully"
# =>
# ✔ success Deployed successfully

You can delay message evaluation by passing it inside a block:

logger.info { "Dynamically generated info" }
# =>
# ✔ success Deployed successfully

You can also report on exceptions.

For example, let's say you caught an exception about incorrect data format and use fatal level to log it:

begin
  raise ArgumentError, "Wrong data"
rescue => ex
  logger.fatal("Error:", error)
end

This will result in a message followed by a full backtrace:

# =>
# ! fatal   Error: Wrong data
#    tty-logger/spec/unit/exception_spec.rb:12:in `block (2 levels) in <top (required)>'
#    rspec-core-3.8.2/lib/rspec/core/example.rb:257:in `instance_exec'
#    rspec-core-3.8.2/lib/rspec/core/example.rb:257:in `block in run'

The supported levels, ordered by precedence, are:

• :debug - for debug-related messages
• :info - for information of any kind
• :warn - for warnings
• :error - for errors
• :fatal - for fatal conditions

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.

TTY::Logger.new do |config|
  config.level = :info # or "INFO" / 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:

logger = TTY::Logger.new do |config|
  config.handlers = [
    [:console, level: :error],
    [:stream, level: :info]
  ]
end

You can also change the output streams for each handler.

To add global data available for all logger calls:

logger = TTY::Logger.new(fields: {app: "myapp", env: "prod"})

logger.info("Deploying...")
# =>
# ℹ info    Deploying...              app=myapp env=prod

To only add data for a single log event:

logger = TTY::Logger.new
logger.wait "Ready to deploy", app: "myapp", env: "prod"
# =>
# … waiting Ready to deploy           app=myapp env=prod

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 for more details.
• :handlers - the handlers used to log messages. Defaults to [:console]. See 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.

For example, to configure :max_bytes, :level and :metadata for all logger instances do:

TTY::Logger.configure do |config|
  config.max_bytes = 2**10
  config.level = :error
  config.metadata = [:time, :date]
end

Or if you wish to setup configuration per logger instance use block:

logger = TTY::Logger.new do |config|
  config.max_bytes = 2**20
  config.metadata = [:all]
end

The :metdata configuration option can include the following symbols:

• :pid - the log event process identifier
• :date - the log event date
• :time - the log event time
• :file - the file with a line number the log event is triggered from

TTY::Logger supports many ways to handle log messages.

The available handlers by default are:

• :console - log messages to the console, enabled by default
• :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.

The handlers can be configured via global or instance configuration with handlers. The handler can be a name or a class name:

TTY::Logger.new do |config|
  config.handlers = [:console]
end

Or using class name:

TTY::Logger.new do |config|
  config.handlers = [TTY::Logger::Handlers::Console]
end

Handlers can also be added/removed dynamically through add_handler or remove_handler.

logger = TTY::Logger.new
logger.add_handler(:console)
logger.remove_handler(:console)

The console handler prints log messages to the console. It supports the following options:

• :styles - a hash of styling options.
• :formatter - the formatter for log messages. Defaults to :text
• :output - the device to log error messages to. Defaults to $stderr

The supported options in the :styles are:

• :label - the name for the log message.
• :symbol - the graphics to display before the log message label.
• :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.

Console handler has many defaults styles such as success and error:

logger = TTY::Logger.new
logger.success("Default success")
logger.error("Default error")
# =>
# ✔ success Default success
# ⨯ error   Default error

You can change console handler default style with a tuple of handler name and options hash.

In our example, we want to change the styling of success and error:

new_styles = {
  styles: {
    success: {
      symbol: "+",
      label: "Ohh yes"
    },
    error: {
      symbol: "!",
      label: "Dooh",
      levelpad: 3
    }
  }
}

And then use the new_styles when providing handlers configuration:

new_style = TTY::Logger.new do |config|
  config.handlers = [:console, new_styles]
end

new_style.success("Custom success")
new_style.error("Custom error")
# =>
+ Ohh yes Custom success
! Dooh    Custom error

To send log event data outside of console to another service or IO stream, you can use :stream handler.

logger = TTY::Logger.new(output: output) do |config|
  config.handlers = [:stream]
  config.metadata = [:all]
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.

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

You can change stream formatter for ease of working with external services such as Logstash. For example, to use :stream handler with :json format do:

logger = TTY::Logger.new(output: output) do |config|
  config.handlers = [[:stream, formatter: :json]]
  config.metadata = [:all]
end

This will output JSON formatted text streamed to console.

loggger.info("Info about the deploy", app="myap", env="prod")
# =>
# {"pid":18513,"date":"2019-07-21","time":"15:54:09.924","path":"examples/stream.rb:17:in`<main>`",
# "level":"info","message":"Info about the deploy","app":"myapp","env":"prod"}

You can create your own log event handler if the default ones don't match your needs.

The design of your handler should include two calls:

• initialize - where all dependencies get injected
• call - where the log event is handled

We start with the implementation of the initialize method. This method by default is injected with :config key that includes all global configuration options. The :output key for displaying log message in the console and :formatter.

In our case we also add custom :label:

class MyHandler
  def initialize(output: nil, config: nil, formatter: nil, label: nil)
    @label = label
    @output = output
  end
end

Next is the call method that accepts the log event.

The event has the following attributes:

• message - the array of message parts to be printed
• fields - the structured data supplied with the event
• metadata - the additional info about the event. See metadata section for details.

We add implementation of call:

class MyHandler
  def initialize(output: nil, config: nil, label: nil)
    @label = label
    @output = output
  end

  def call(event)
    @output.puts "(#{@label}) #{event.message.join}"
  end
end

Once you have your custom handler, you need to register it with the logger. You can do so using the handlers configuration option:

logger = TTY::Logger.new do |config|
  config.handlers = [[MyHandler, label: "myhandler"]]
end

Or add your handler dynamically after logger initialization:

logger = TTY::Logger.new
logger.add_handler [MyHandler, label: "myhandler"]

You can define as many handlers as you need. For example, you may log messages both to console and stream:

logger = TTY::Logger.new do |config|
  config.handlers = [:console, :stream]
end

Each handler can have its own configuration. For example, you can register :console handler to log messages above error level and :stream that logs any message with info or higher level:

logger = TTY::Logger.new do |config|
  config.handlers = [
    [:console, level: :error],
    [:stream, level: :info]
  ]
end

The available formatters are:

• :json
• :text

You can configure format for all the handlers:

TTY::Logger.new do |config|
  config.formatter = :json
end

Or specify a different formatter for each handler. For example, let's say you want to log to console twice, once with default formatter and once with :json formatter:

TTY::Logger.new do |config|
  config.handlers = [:console, [:console, formatter: :json]]
end

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:

logger = TTY::Logger.new do |config|
  config.output = File.open("errors.log", "a")
end

You can also specify multiple streams that all log messages will be sent to:

logger = TTY::Logger.new do |config|
  config.output = [$stderr, File.open("errors.log", "a")]
end

Conversely, you can specify different output for each of the handlers used. For example, you can output all messages above info level to a file with a stream handler and only show error messages in the console with a nicely formatted output.

logger = TTY::Logger.new do |config|
  config.handlers = [
    [:console, output: $stderr, level: :error],
    [:stream, output: File.open("errors.log", "a"), level: :info)]
  ]
end

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-logger. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the TTY::Logger project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Copyright (c) 2019 Piotr Murach. See LICENSE for further details.