Blinkist TransactionLogger

Codeship Status for blinkist/transaction_logger Gem Version Code Climate Dependency Status

Business Transactions Logger for Ruby that compiles contextual logging information and can send it to a configured logging service such as Logger or Loggly in a nested hash.

Table of Contents

  1. Installation
  2. Output
  3. Configuration
  4. Usage
  5. Version History
  6. Contributing


Add this line to your application's Gemfile:

gem "transaction_logger"

And then execute:

$ bundle

Or install it yourself as:

$ gem install transaction_logger


By registering a method with TransactionLogger, the TransactionLogger is expected to print out every log that occurred under this method, and each nested method's local information as well.

When a transaction raises an error, it will log the error message, error class, and 10 lines of the backtrace by default. This will be logged at the level of the transaction that raised the error.

Additionally, if no errors are raised, but an error or fatal log is made, then the TransactionLogger will send it's log hash to the configured logger.


Configure the logger by calling TransactionLogger.logger, such as with Ruby's Logger:

logger = STDOUT # Ruby default logger setup
TransactionLogger::Configure.logger = logger

Calling Transaction_Logger.logger with no parameter sets the logger to a new instance of Logger as shown above.

Configuring the Prefix

You can add a prefix to every hash key in the log by using the class method log_prefix:

TransactionLogger::Configure.log_prefix = "transaction_logger_"
# output hash:
# {
#   "transaction_logger_name" => "some name"
#   "transaction_logger_context" => { "user_id" => 1 }
#   ...
# }

Configuring the Log Level Threshold

You may also choose at which log level the TransactionLogger sends it's log hash. By default, error is the threshold, so that if an error or fatal log is made, then the TransactionLogger will send a JSON hash to it's configured logger. If you wish to set the threshold to warn, you can configure the TransactionLogger to do so:

TransactionLogger::Configure.level_threshold = :warn


To register a method as a transaction, include the TransactionLogger and use add_transaction_log after the method definition:

class YourClass
  include TransactionLogger

  def some_method "logged message"
    # method code

  add_transaction_log :some_method

By default, the transaction will be named YourClass:some_method. You can easily change this by adding the name to the options params:

add_transaction_log :some_method, {name: "Custom Name" }

You can set a context to the options that is pushed to the logger. It can either anything supporting .to_hash or a Proc. The proc will be evaluated in the scope of the traced method.

add_transaction_log :some_method, {context: "Custom Context" }
add_transaction_log :some_method, {context: { key: "value context" } }
add_transaction_log :some_method, {context: -> { request.params } }


Assuming there is already an instance of Ruby's Logger class, here is a transaction that raises an error:

class ExampleClass
  def some_method(result)
    include TransactionLogger "Trying something complex"
    raise RuntimeError, "Error"

    result "Success"

  add_transaction_log :some_method, { context: { some_id: 12 } }

The expected output is:

  "name": "ExampleClass:some_method",
  "context": {
    "some_id": 12
  "duration": 0.112,
  "history": [{
    "info": "Trying something complex"
    }, {
      "error_message": "Error",
      "error_class": "RuntimeError",
      "error_backtrace": [
        "example_class.rb:6:in `some_method'",
        ".../transaction_logger.rb:86:in `call'",
        ".../transaction_logger.rb:86:in `block (2 levels) in add_transaction_log'",
        ".../transaction_logger/transaction.rb:37:in `call'",
        ".../transaction_logger/transaction.rb:37:in `run'",
        ".../transaction_logger/transaction_manager.rb:41:in `start'",
        ".../transaction_logger.rb:78:in `block in add_transaction_log'",
        "test.rb:4:in `<main>'"


Version History


  • Fixed issues #32 for missing context
  • Added support for Proc as context #34


  • Fixed issues with undefined trap_logger method
  • Hid module methods other than add_transaction_log
  • TransactionLogger configuration updated


  • AOP approach that provides a much cleaner, easier implementation of the TransactionLogger
  • Added default transaction name
  • Added support for log level threshold


  • Added support for log prefixes


  • initial version


  1. Fork it ( )
  2. Create your feature branch (git checkout -b feature/your_feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin feature/your_feature)
  5. Create a new Pull Request