GitHub - unepwcmc/bystander: Log your application flow without any ugly loggers

3 min read Original article ↗

Bystander

A Ruby Gem that makes it easy to log your application's Critical Paths™ without having to touch the behaviour of your code.

Bystander in action, in a Slack channel

Getting started

How does it work?

With some basic configuration, Bystander hooks in to your Ruby classes and creates a log entry every time one of the methods you specify is called, and when the method returns.

Where does it log to?

Anywhere! Well, if you want it to. Currently it defaults to logging to a Slack channel, but is designed to work with any transport method (warning: you're gonna have to write some code).

Usage

Automatic Logging

Bystander consists of a DSL that allows you to define what method calls you want to listen to. The concept is simple:

  • You have one or more Scenes, which match to a process (such as importing a file)
  • Each Scene consists of one or more Actors, which define the classes that will be taking part in the process.
  • Each Scene consists of one or more Acts, which define what methods to listen to.
Bystander.scene('import') do
  actors do
    add Download
  end

  acts do
    add :download, :make_current, notify: :wrap
  end
end

An act has two types of notifiers: wrap and before. wrap notifies your transport before and after the method is called, whereas before only notifies as the method is called.

Whenever the methods are called, Bystander will log the call and the return:

Calling: Download#make_current
Finished: Download#make_current

Manual Logging

Bystander has a basic capability to log custom messages, inline in your code, like a normal logger.

Bystander.log("I've made a huge mistake")

Configuration

Slack

Before you use Bystander, ensure you run the following configuration block (e.g., in a Rails initializer):

Bystander::Transports::Slack.configure do |slack|
  slack.username     'Bystander'
  slack.webhook_url  ENV['SLACK_WEBHOOK_URL']
  slack.channel      '#bystander'

  # Prepend all messages with this string. Useful for env info, etc.
  slack.prepend     "#{ENV['RAILS_ENV']} - (##{Process.pid}):"
end

Using Bystander in Tests

Most of the time you won't want Bystander running during tests. To disable Bystander, preface your test code (for example, in your test_helper.rb) with:

Bystander.enable_testing!

Upgrading to 2.0

You might be here to check what the heck is changing in version 2.0. Luckily enough, almost nothing: we are upgrading the slack-notifier dependency, and this needs us to change the Slack configuration a little bit.

So, if you have this:

Bystander::Transports::Slack.configure do |slack|
  slack.domain       'unepwcmc'
  slack.auth_token   ENV['SLACK_AUTH_TOKEN']
  slack.channel      '#bystander'
end

turn it into this:

Bystander::Transports::Slack.configure do |slack|
  slack.username     'Bystander'
  slack.webhook_url  ENV['SLACK_WEBHOOK_URL']
  slack.channel      '#bystander'
end

You can get a Slack webhook URL by creating an "Incoming Webhook" integration in your team's slack interface. Piece of cake!