Binnacle Ruby Client
Ruby Client for the RESTful Multi-channel Push Service Binnacle (see binnacle.io)
__/\\\______________________________________________________________________________/\\\\\\____________________
_\/\\\_____________________________________________________________________________\////\\\____________________
_\/\\\__________/\\\__________________________________________________________________\/\\\____________________
_\/\\\_________\///____/\\/\\\\\\_____/\\/\\\\\\_____/\\\\\\\\\_________/\\\\\\\\_____\/\\\_________/\\\\\\\\__
_\/\\\\\\\\\____/\\\__\/\\\////\\\___\/\\\////\\\___\////////\\\______/\\\//////______\/\\\_______/\\\/////\\\_
_\/\\\////\\\__\/\\\__\/\\\__\//\\\__\/\\\__\//\\\____/\\\\\\\\\\____/\\\_____________\/\\\______/\\\\\\\\\\\__
_\/\\\__\/\\\__\/\\\__\/\\\___\/\\\__\/\\\___\/\\\___/\\\/////\\\___\//\\\____________\/\\\_____\//\\///////___
_\/\\\\\\\\\___\/\\\__\/\\\___\/\\\__\/\\\___\/\\\__\//\\\\\\\\/\\___\///\\\\\\\\___/\\\\\\\\\___\//\\\\\\\\\\_
_\/////////____\///___\///____\///___\///____\///____\////////\//______\////////___\/////////_____\//////////__
Overview
Send events and log messages to Binnacle
Drop in replacement for Ruby’s Logger (See http://www.ruby-doc.org/stdlib-2.2.0/libdoc/logger/rdoc/Logger.html)
Building
-
Pull the JS assets (after bundling) from Rails Assets (https://rails-assets.org/#/?query=binnacle)
-
rake binnacle:install_binnacle_js
-
Build the Gem:
gem build binnacle.gemspec
-
Install the Gem Locally:
gem install ./binnacle-M.m.P.gem
Installation
Rails 3.x/4.x/5.x
Add the binnacle gem to your Gemfile. In Gemfile:
gem 'binnacle'
Then from your project’s RAILS_ROOT, and in your development environment, run:
bundle install
rails generate binnacle
The generator creates a file under config/initializers/binnacle.rb
. Although you
can configure all aspects of the binnacle client via this initializer we recommend
that you configure any credentials and account/app/channel ids via Environment
variables (using something like the dotenv gem in development and ENV values in
production/staging)
Configuration
Rails 3.x
In config/environments/production.rb:
In Rails 4.x - 5.x
The Binnacle Ruby client integrate seamlessly with the Ruby on Rails to:
-
Provide a Pub-Sub client to interact with Binnacle’s Push Service
-
Intercepts Rails Logger to log to a Binnacle Channel
-
Intercepts Errors and Exceptions and logs them to a Binnacle Channel
# ==============================================================================
# Binnacle Configuration
# ==============================================================================
# Available parameters (some are also configurable via ENV variables, see parens):
# ==============================================================================
# - url: The Binnacle Endpoint URL (BINNACLE_URL)
# - logging_channel: The application logger Binnacle Channel (BINNACLE_APP_LOG_CHANNEL)
# - error_channel: The application error Binnacle Channel (BINNACLE_APP_ERR_CHANNEL)
# - api_key: An approved publisher API key for the App (BINNACLE_API_KEY)
# - api_secret: The API secret for the given API key (BINNACLE_API_SECRET)
# - intercept_rails_logging: Redirect rails logging to logging_channel in Binnacle (BINNACLE_RAILS_LOG)
# - report_exceptions: Trap exceptions are log them to error_channel (BINNACLE_REPORT_EXCEPTIONS)
# - ignored_exceptions: List of Exceptions that do not get reported to Binnacle (BINNACLE_IGNORED_EXCEPTIONS)
# - ignore_cascade_pass: Whether to skip reporting exceptions where the headers['X-Cascade'] is set to 'pass'.
# In Rails typically it means route was not found (404 error).
# ==============================================================================
Binnacle.configure do |config|
config.intercept_rails_logging = true
config.report_exceptions = true
end
Usage
Rails
Once configured the Binnacle client is available to send signals. In the example below from a Rails controller:
Available methods are: signal, signal_asynch, recents, report_exception
Direct Via Ruby Client
Build an instance of Logging Adapter passing the following Binnacle configuration values (get them from you App page on the Binnacle Website):
Parameters to Client.new:
-
api_key: An approved publisher API key for the App (
BINNACLE_API_KEY
) -
api_secret: The API secret for the given API key (
BINNACLE_API_SECRET
) -
endpoint: The Binnacle Endpoint (host) (
BINNACLE_ENDPOINT
)
All these values can be configured as ENV variables (variable name in parenthesis)
Parameters to signal:
-
channel_id: Your default Binnacle Channel ID
-
event_name: The name of the event
-
client_id: Use for system/subsystem/component id/name
-
session_id: Use to track a user session across requests/processes
-
log_level: UNKNOWN, FATAL, ERROR, WARN, INFO, DEBUG
-
tags (optional): An Array of tags, e.g.
['accounts', 'refunds', 'dispute']
-
json (optional): A Ruby Hash, e.g.
{ message: "there you are!" }
Via Ruby/Rails Logging
Build an instance of Logging Adapter (which wraps the Binnacle Client):
Parameters to Logging.new:
-
api_key: An approved publisher API key for the App (
BINNACLE_API_KEY
) -
api_secret: The API secret for the given API key (
BINNACLE_API_SECRET
) -
logging_channel_id: A Binnacle Channel ID
-
endpoint: The Binnacle Endpoint (host) (
BINNACLE_ENDPOINT
)
The following log statement:
logger.info("hey")
results in the following message being sent to Binnacle:
{
"channelId": "5ujzd7gwk8ikmvnqv1w7",
"sessionId": "",
"clientEventTime": "2015-01-31T08:55:19-0700",
"eventName": "log",
"clientId": "",
"logLevel": "INFO",
"tags": [],
"json": {"message":"hey"}
}
Switching channel and passing other parameters
We override Ruby’s logger 'progname' parameter to pass a Hash where you can specify Binnacle’s signal remaining parameters (session_id, event_name, client_id, tags)
For example, the following log statement:
logger.info(channel_id: 'xxx', session_id: '8675309', event_name: 'failed_transfer') { 'transfer failed, bad RTN' }
Will post to Binnacle under the event name failed_transfer
, to the channel with id xxx
and with session_id
equal to 8675309
.
In the hash you can pass channel_id
, session_id
, event_name
, client_id
, tags
, json
If instead of a Hash you pass a String the event_name
will be assigned its value.
Binnacle Executable
Installing the client gem provides the binnacle
executable which provides the following features:
Live Tail
Use tail -f
(follow) subcommand to live tail a binnacle channel or app.
binnacle tail -f --host=localhost --channel=ylhcn28x7skv6av8q93m --api-key=jzr5d5kgj4j3l8fm90tr --api-secret=bz3e3w44o3323dypp8d7 --encrypted=false
The tail subcommand has the following options:
SUBCOMMAND
tail -- listen to a Binnacle channel or app
Usage:
binnacle tail
where [options] are:
-h, --host=<s> Binnacle Host (default: localhost)
-c, --channel=<s> Binnacle Channel
-a, --app=<s> Binnacle App
-u, --api-key=<s> Binnacle API Key
-p, --api-secret=<s> Binnacle API Secret
-f, --follow Monitors a Binnacle Channel or App
-n, --lines=<i> Get the last n events on the Channel
-s, --since=<i> Number of minutes in the past to search for events
-e, --encrypted, --no-encrypted Use SSL/HTTPS (default: true)
-l, --help Show this message
Recent Events
Use tail -n
subcommand to get the last N events in the last M minutes'
lines
: maximum number of events to retrieve
since
: number of minutes in the past (defaults to 5 minutes)
binnacle tail -n 2 -s 60 --host=localhost --channel=ylhcn28x7skv6av8q93m --api-key=jzr5d5kgj4j3l8fm90tr --api-secret=bz3e3w44o3323dypp8d7 --no-encrypted
Testing
We use RSpec. When developing outgoing HTTP logging adaptors you can pass SERVE_TEST_ASSETS=true to rspec to run an embedded thin server to server test files:
SERVE_TEST_ASSETS=true rspec