RubyDoc.info: File: README – Documentation for binnacle (0.4.9)

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)

Status

CI Status

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:

RailsApplication::Application.configure do
  config.logger = Binnacle::Logging.build(API_KEY, API_SECRET, BINNACLE_URL, BINNACLE_APP_LOG_CHANNEL)
end

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:

def create
  logger.info "PostsController#create"
  @post = Post.new(post_params)
  if @post.save
    client = Binnacle::Client.new(publisher.api_key, publisher.api_secret)
    client.signal_asynch('channel', 'event_name', 'new_post', 'rails-app', session.id, 'INFO', [], @post.to_json)
  end
end

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):

require 'binnacle'

client = Binnacle::Client.new(api_key, api_secret, endpoint)
client.signal('5ujzd7gwk8ikmvnqv1w7', 'event_from_client', 'binnacle-ruby', '001', 'INFO')

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):

require 'binnacle'

logger = Binnacle::Logging.build(API_KEY, API_SECRET, '5ujzd7gwk8ikmvnqv1w7', 'localhost')

logger.info("This is an info message")
logger.debug("This is an debug message")

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