Cogger

When creating a new logger, you can configure behavior via the following attributes:

• id: The program/process ID which shows up in the logs as your id. Default: $PROGRAM_NAME. For example, if run within a demo.rb script, the id would be "demo",

• io: The input/output stream. This can be STDOUT/$stdout, a file/path, or nil. Default: $stdout.

• level: The log level you want to log at. Can be :debug, :info, :warn, :error, :fatal, or :unknown. Default: :info.

• formatter: The formatter to use for formatting your log output. Default: Cogger::Formatter::Emoji. See the Formatters section for more info.

• tags: The global tags used for all log entries. Must be an array of objects you wish to use for tagging purposes. Default: [].

• datetime_format: The global date/time format used for all Time, Date, and/or DateTime values in your log entries. Default: %Y-%m-%dT%H:%M:%S.%L%:z.

• header: Determines if your log files should start with a date/time header comment. Can be true or false and is identical to the skip_header functionality found in the Logger class. Default: true. This is automatically disabled — and can’t be overwritten — when using the JSON formatter since the JSON format doesn’t support code comments.

• mode: The binary mode which determines if your logs should be written in binary mode or not. Can be true or false and is identical to the binmode functionality found in the Logger class. Default: false.

• age: The rotation age of your log. This only applies when logging to a file. This is equivalent to the shift_age as found with the Logger class. Default: 0.

• size: The rotation size of your log. This only applies when logging to a file. This is equivalent to the shift_size as found with the Logger class. Default: 1,048,576 (i.e. 1 MB).

• suffix: The rotation suffix. This only applies when logging to a file. This is equivalent to the shift_period_suffix as found with the Logger class and is used when creating new rotation files. Default: %Y-%m-%d.

Given the above description, here’s how’d you create a new logger instance with all attributes:

Supported levels can be obtained via Cogger::LEVELS. Example:

The default date/time format used for all log values can be viewed via the following:

The above adheres to RFC 3339 and can be customized — as mentioned earlier — when creating a new logger instance. Example:

You can use your environment to define the desired default log level. The default log level is: "info". Although, you can set the log level to any of the following:

While downcase is preferred for each log level value, you can use upcased values as well. If the LOG_LEVEL environment variable is not set, Cogger will fall back to "info" unless overwritten during initialization. Example: Cogger.new level: :debug. Otherwise, an invalid log level will result in an ArgumentError.

Each instance can be mutated using the following messages:

Please see the Logger documentation for more information.

Emojis can be used to decorate and add visual emphasis to your logs. Here are the defaults:

The :emoji formatter is the default formatter which provides dynamic rendering of emojis based on log level. Example:

To add multiple custom emojis, you can chain messages together when registering them:

If you always want to use the same emoji, you could use the emoji formatter with a specific template:

As you can see, using a specific emoji will always display regardless of the current log level.

💡 Emojis are used by the color and emoji formatters so check out the Templates and Formatters sections below to learn more.

Aliases are specific to the Tone gem which allows you alias specific colors/styles via a new name. Here’s how you can use them:

The above would add a :haze alias which consists of bold white text on a purple background. Once added, you’d then be able to view a list of all default and custom aliases. You can also override an existing alias if you’d like something else.

Aliases are a powerful way to customize colors via concise syntax in your templates. Building upon the aliases, added above, you’d be able to use them in your templates as follows:

💡 Aliases are used by the color and emoji formatters so check out the Tone documentation and/or Templates and Formatters sections below to learn more.

All messages use UTF-8 encoding. Any unknown character will show up as a question mark. Example:

The underlying implementation uses the following to produce the logs shown above:

Templates are used by all formatters and adhere to an enhanced version of the String Format Specification as used by Kernel#format. Here’s what is provided by default:

All String Format Specification specifiers, flags, width, and precision are supported except for the following restrictions:

• Use of reference by name is required which means %<demo>s is allowed but %{demo} is not. This is because reference by name is required for regular expressions and/or pattern matching.

• Use of the n$ flag is prohibited because it’s not compatible with the above.

In addition to the above, the String Format Specification is further enhanced with the use of keys, emojis, and/or elements. Each is explained in detail below.

Multiple formatters are provided for you which can be further customized as needed. Here’s what is provided by default:

You can add a formatter by providing a key, class, and optional template. If a template isn’t supplied, then the formatter’s default template will be used instead (more on this shortly). Example:

Symbols or strings can be used interchangeably when adding/getting formatters. As mentioned above, a template doesn’t have to be supplied if you want to use the formatter’s default template which can be inspected via Cogger.templates as mentioned earlier.

💡 When you find yourself customizing any of the default formatters, you can reduce typing by adding your custom configuration to the registry and then referring to it via it’s associated key when initializing a new logger.

Tags allow you to tag your messages at both a global and local (i.e. per message) level. Please note that tags are mostly universal in behavior but can differ based on formatter used. For example, here’s a single global tag:

You can use multiple tags as well:

You are not limited to string-based tags. Any object will work:

With the above, we have string, symbol, integer, hash, and proc tags. With hashes, you’ll always get a the key/value pair formatted as: key=value. Procs/lambdas allow you to lazy evaluate your tag at time of logging which provides a powerful way to acquire the current process ID, thread ID, and so forth.

In addition to global tags, you can use local tags per log message. Example:

You can also combine global and local tags:

As you can see, tags are highly versatile. That said, the following guidelines are worth consideration when using them:

• Prefer uppercase tag names to make them visually stand out.

• Prefer short names, ideally 1-4 characters since long tags defeat the purpose of brevity.

• Prefer consistent tag names by using tags that are not synonymous or ambiguous.

• Prefer using tags by feature rather than things like environments. Examples: API, DB, MAILER.

• Prefer the JSON formatter for structured metadata instead of tags. Logging JSON formatted messages with tags will work but sticking with a traditional hash, instead of tags, will probably serve you better.

Filters allow you to mask sensitive information you don’t want showing up in your logs. The default is an empty set:

To add filters, use:

Symbols and strings can be used interchangeably but are stored as symbols since symbols are used when filtering log entries. Once your filters are in place, you can immediately see their effects:

You can add multiple log streams (outputs) by using:

The above would log the "Demo." message to $stdout — the default stream — to the tmp/demo.log file, and to /dev/null. All attributes used to construct your default logger apply to all additional streams unless customized further. This means any custom template/formatter can be applied to your streams. Example:

In this situation, you’d get colorized output to $stdout and JSON output to the tmp/demo.log file.

There is a lot you can do with streams. For example, if you wanted to experiment with the same message formatted by multiple formatters, you could add a stream per format. Example:

Aborting a program is mostly syntax sugar for Command Line Interfaces (CLIs) which aids in situations where you need to log an error message and exit the program at the same time with an exit code of 1 (similar to how Kernel#abort behaves). This allows your CLI to log an error and ensure the exit status is correct when displaying status, piping commands together, etc. All of the arguments, when messaging #error directly, are the same. Here’s how it works:

You can use #abort without a message which will not log anything and immediately exit:

This is not recommended since using Kernel#exit directly is more performant.

Rack is implicitly supported which means your middleware must be Rack-based and must require the Rack gem since Cogger::Rack::Logger doesn’t explicitly require Rack by default. If these requirements are met then, to add HTTP request logging, you only need to use it. Example:

Like any other Rack middleware, Rails::Rack::Logger is initialized with your current application along with any custom options. Example:

The following defaults are supported:

The defaults can be customized. Example:

In the above example, we see Cogger.new overrides the default Cogger.new(formatter: :json). In practice, you’ll want to customize the logger and key map. Here’s how each default is configured to be used:

• logger: Defaults to JSON formatted logging but you’ll want to pass in the same logger as globally configured for your application in order to reduce duplication and save on memory.

• timer: The timer calculates the total duration of the request and defaults to nanosecond precision but you can swap this out with your own timer if desired. When providing your own timer, the only requirement is that the timer respond to the #call message with a block.

• key_map: The key map is used to map the HTTP Headers to keys (i.e. tags) used in the log output. You can use the existing key map, provide your own, or use a hybrid.

Once this middleware is configured and used within your application, you’ll start seeing the following kinds of log entries (depending on your specific settings and tags used):

Rails

To build upon the above — and if using the Rails framework — you could configure your application as follows:

The above defines Cogger as the default logger for the entire application, ensures Cogger::Rack::Logger is configured to use it and swaps itself with the default Rails::Rack::Logger so you don’t have two pieces of middleware logging the same HTTP requests.

Alternatively, you could use a more advanced configuration with even more detailed logging:

The above does the following:

• Fetches the project version from the environment and then logs the version as a tag.

• PID and thread information are dynamically calculated at runtime, via the proc, as tags too.

• Team information is also captured as a tag.

• The middleware is only configured for use in any environment other than the test environment.

You could also add the following to your Development and Test environments so you capture all logs in a log file:

Should you ever need quick access to the defaults, you can use:

This is primarily meant for display/inspection purposes, though.

Each instance can be inspected via the #inspect message:

You can also look at individual attributes:

When testing, you might find it convenient to rewind and read from the stream you are writing too (i.e. IO, StringIO, File). For instance, here is an example where I inject the default logger into my Demo class and then, for testing purposes, create a new logger to be injected which only logs to StringIO so I can buffer and read for test verification:

The ability to #reread is only available for the default (first) stream and doesn’t work with any additional streams that you add to your logger. That said, this does make it easy to test the Demo implementation while also keeping your test suite output clean at the same time. 🎉