A Ruby Gem that makes it easy to log your application's Critical Paths™ without having to touch the behaviour of your code.
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.
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).
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
Scene
s, which match to a process (such as importing a file) - Each
Scene
consists of one or moreActor
s, which define the classes that will be taking part in the process. - Each
Scene
consists of one or moreAct
s, 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
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")
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
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!
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!