dogcatcher 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZjlkMTYzOTMyYWM3MTA5M2Q0NWIxMDQ4M2M5MWQxZjdlNzg2OWFkNw==
+  data.tar.gz: !binary |-
+    MzM5MDM2MDY1YzdiNGYwZGJjOGUyZGFkNTkzNmVhZTQ5MGFlODE3OQ==
+SHA512:
+  metadata.gz: !binary |-
+    ZmQ3OWVhMzM2YWRlZTJkZTA5M2QxY2YzMzk2MGRiNzg1MDFlZDBlYzA5ZmY0
+    NGEwOGNkZWE0ZDBlZGJlNzZkZjZhNjkzMzQwNDg2MTg5YzZmNWY3ZGU1YjFj
+    YTg2OWM5NmM3MzVlY2JjMDQyZmRjYTBhNGQwNGQxMjdiODFmY2Q=
+  data.tar.gz: !binary |-
+    ZmYwYzE2OWI0YWZjZTVkZjUyYmI0YzQyMjA3ZDNlYmE2ZGE1NzBiZTU3YTNl
+    MzQ1MTUwNDk5YjJiNzIwNDUyMjkwMTI3ZmZjNjBhMzExN2UyZjA3NGRlYzk3
+    MGI2NDg4NGQ5MDdjNGJlODM5MjZhOWZhODMxZjkzMzVjMzFjNGU=

data/.editorconfig

@@ -0,0 +1,5 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+- 2.1.6
+before_install: gem install bundler -v 1.10.6
+deploy:
+  provider: rubygems
+  api_key:
+    secure: fXyp78ETH+ot0NlPTqdayyVUN4Wt+VGCKZOk2XvwI2WSE26OmGkMRGhkp8mH9zUq2tvMN0XvNW/+7XVUJ0Qep8KfqafR73VWhCoM4FEC1j1xlIg3oTwug+TxrYaQVisM9sgqTiwJ/suIxKpp7Br77F4mAnKhHs+lUTR9qzW/CK9QAM7rbKuBGTtwBSfv0J+oYG1a24yCl2OqXCfS1JRJ11CQnvoUcOlCHZ1Lx4NTsjPuy/J/R3qhECa11qgi6e6S0szf1OEHhSTQBjJ/rTIEZAiYbWC55g20s5uMwwocc3iy6BaqM8kh8VjWzgoWH7yIzsmyPXDfgCq95/oOx/cuA3Kp7a3rt+wRNAZbbkeHWfbrJ9iEb0s3en6855t6QaKK8kgntTkcO0n2oCrAaU1CijG42koS4J+GqvY0zq9Kqm+BbBBNRIslIIBZvexvHrleSjF/uF5hR71gNeIT5aoSUV+4t+rc+OgeEjCpv0UEf9BJ3uvRPUYC83FY1ygUm8PwMt1hhcSgkWQQLZcP8MLYda7zWM+WJpm60WJoCnNuqiVQ8lc0U9iNU7Dr4a+bPkqZScH29QvdlBrqeTTwLNrki8/dDGdSmb5GH7d7V//Iw0XnNXs9/FQQJ2qMqCREHh3fGs1eJGAXq61MqNpZ7Bg96SF4n56aAKVKBPdd35krWPM=
+  on:
+    tags: true

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in dogcatcher.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Ben Vidulich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,124 @@
+# Dogcatcher
+
+[![Build Status](https://travis-ci.org/zl4bv/dogcatcher.svg)](https://travis-ci.org/zl4bv/dogcatcher)
+[![Gem Version](https://badge.fury.io/rb/dogcatcher.svg)](https://badge.fury.io/rb/dogcatcher)
+
+![screenshot_event](support/screenshot_event.png)
+
+Dogcatcher is a tool to track exceptions in Ruby applications and send them to Datadog
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dogcatcher'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install dogcatcher
+
+## Usage
+
+### Basic example
+
+This is an example that you can use anywhere within your Ruby project. By
+default the exception will be sent to statsd running on the local host.
+
+```ruby
+require 'dogcatcher'
+
+begin
+  fail ArgumentError, 'Example error'
+rescue ArgumentError => exception
+  Dogcatcher.notify(exception)
+end
+```
+
+### Example within Rake
+
+When dogcatcher has been required in a Rakefile, the all exceptions raised in
+any Rake task will automatically be collected.
+
+```ruby
+require 'dogcatcher'
+
+task :example_task do
+  fail ArgumentError, 'Example error'
+end
+```
+
+## Configuration
+
+By default Dogcatcher will send events to statsd running on the local host. By
+specifying a Datadog API key, Dogcatcher will switch to sending events to the
+Datadog API instead.
+
+```ruby
+Dogcatcher.configure do |c|
+  c.api_key = '<datadog API key goes here>'
+end
+```
+
+Since the default approach is to send events to one or the other, options are
+available to explicitly control where the events are sent.
+
+```ruby
+Dogcatcher.configure do |c|
+  c.use_dogapi = true
+  c.use_statsd = true
+end
+```
+
+The host and port that statsd events are sent to can be configured like so.
+
+```ruby
+Dogcatcher.configure do |c|
+  c.statsd_host = '127.0.0.1'
+  c.statsd_port = 8125
+end
+```
+
+An optional program name can be specified to help distinguish between multiple
+applications. This will appear in the event title.
+
+```ruby
+Dogcatcher.configure do |c|
+  c.program = 'Example program'
+end
+```
+
+By default, Dogcatcher will add tags for each gem and its version found in the
+backtrace. This can be disabled if required.
+
+```ruby
+Dogcatcher.configure do |c|
+  c.gem_tags = false
+end
+```
+
+The backtrace can be cleaned by adding filters or silencers. The filters
+shown below were used to generate the screenshot shown above.
+
+```ruby
+Dogcatcher.configure do |c|
+  c.add_filter { |line| line.gsub(Dir.pwd, '.') }
+  c.add_filter { |line| line.gsub(%r{^.*/gem/ruby/[0-9.]+/gems/([A-Za-z0-9\-_]+)-([0-9.]+(\.[a-z]+(\.[0-9]+)?)?)/}, '\1 (\2) ') }
+  c.add_filter { |line| line.gsub(%r{.*/gem/ruby/[0-9.]+(/bin/)}, '<gem path>\1') }
+  c.add_filter { |line| line.gsub(%r{.*(/lib/ruby/[0-9.]+)}, '<interpreter path>\1') }
+  c.add_silencer { |line| false }
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/zl4bv/dogcatcher.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'dogcatcher'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require 'pry'
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/dogcatcher.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'dogcatcher/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'dogcatcher'
+  spec.version       = Dogcatcher::VERSION
+  spec.authors       = ['Ben Vidulich']
+  spec.email         = ['ben@vidulich.co.nz']
+
+  spec.summary       = %q{Dogcatcher is a tool to catch exceptions in Ruby applications and send them to Datadog}
+  spec.description   = %q{Dogcatcher is a tool to catch exceptions in Ruby applications and send them to Datadog}
+  spec.homepage      = 'https://github.com/zl4bv/dogcatcher'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.10'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec'
+
+  spec.add_runtime_dependency 'activesupport', '~> 4'
+  spec.add_runtime_dependency 'dogapi', '~> 1.22'
+  spec.add_runtime_dependency 'dogstatsd-ruby', '~> 1.6'
+end

data/lib/dogcatcher.rb

@@ -0,0 +1,40 @@
+require 'active_support/backtrace_cleaner'
+require 'dogapi'
+require 'statsd'
+
+require 'dogcatcher/ext/rake/task'
+require 'dogcatcher/config'
+require 'dogcatcher/markdown'
+require 'dogcatcher/notice'
+require 'dogcatcher/notifier'
+require 'dogcatcher/version'
+
+module Dogcatcher
+  class << self
+    # Returns a config instance
+    #
+    # @return [Dogcatcher::Config]
+    def config
+      @config ||= Config.new
+    end
+
+    # Used to configure Dogcatcher
+    #
+    # @yieldparam [Dogcatcher::Config]
+    def configure
+      yield config
+    end
+
+    # @param [Exception] exception
+    # @return [Dogcatcher::Notice]
+    def build_notice(exception)
+      Notice.new(config, exception)
+    end
+
+    # @param [Dogcatcher::Notice] notice
+    def notify(notice)
+      @notifier ||= Notifier.new(config)
+      @notifier.notify(notice)
+    end
+  end
+end

data/lib/dogcatcher/config.rb

@@ -0,0 +1,86 @@
+module Dogcatcher
+  # Configuration for Dogcatcher
+  class Config
+    # Optional program name that will be included in the event information.
+    attr_accessor :program
+
+    # Datadog API key.
+    #
+    # This must be configured in order to sent events to the Datadog API.
+    attr_accessor :api_key
+
+    # The host and port where statsd events will be sent.
+    #
+    # By default the host is +127.0.0.1+ and the port is +8125+.
+    attr_accessor :statsd_host
+    attr_accessor :statsd_port
+
+    # When each is set to +true+ then exceptions will be sent via the
+    # corresponding method. Both can be enabled/disabled at the same time.
+    #
+    # By default these are unset; dogapi will be used if an API key is provided
+    # else statsd will be used.
+    attr_accessor :use_dogapi
+    attr_accessor :use_statsd
+
+    # When enabled it will add tags for each +gem_name:version+ found in the
+    # backtrace.
+    #
+    # Enabled by default.
+    attr_accessor :gem_tags
+
+    # Used to clean the backtrace.
+    #
+    # By default it does no cleaning.
+    attr_accessor :backtrace_cleaner
+
+    def initialize
+      @statsd_host = '127.0.0.1'
+      @statsd_port = 8125
+      @gem_tags = true
+      @backtrace_cleaner = ActiveSupport::BacktraceCleaner.new
+    end
+
+    # Adds a backtrace filter. The given line in the backtrace will be replaced
+    # with the line returned by the given block.
+    #
+    # @yieldparam [String] line in the backtrace
+    # @yieldreturn [String] filtered line in the backtrace
+    def add_filter
+      backtrace_cleaner.add_filter { |line| yield line }
+    end
+
+    # Adds a backtrace silencer. Excludes the given line from the backtrace if
+    # the given block returns +true+.
+    #
+    # @yieldparam [String] line in the backtrace
+    # @yieldreturn [Boolean] true if the line should be excluded
+    def add_silencer
+      backtrace_cleaner.add_silencer { |line| yield line }
+    end
+
+    # Whether to send events to the Datadog API.
+    #
+    # If {#use_dogapi} is +nil+ (the default), then this will return +true+ if
+    # a Datadog API key is set.
+    #
+    # @return [Boolean] true if events should be sent to the Datadog API
+    def use_dogapi?
+      return !@api_key.nil? if @use_dogapi.nil?
+
+      @use_dogapi
+    end
+
+    # Whether to send events to a statsd collector.
+    #
+    # If {#use_dogapi} is +nil+ (the default), then this will return +false+ if
+    # a Datadog API key is set.
+    #
+    # @return [Boolean] true if events should be sent to a statsd collector
+    def use_statsd?
+      return @api_key.nil? if @use_statsd.nil?
+
+      @use_statsd
+    end
+  end
+end

data/lib/dogcatcher/ext/rake/task.rb

@@ -0,0 +1,16 @@
+module Rake
+  class Task
+    # We want to use the original execute method later
+    alias original_execute execute
+
+    def execute(args = nil)
+      original_execute(args)
+    rescue Exception => ex
+      notice = Dogcatcher.build_notice(ex)
+      notice.notifier = 'rake'
+      notice.action = name
+      Dogcatcher.notify(notice)
+      raise ex
+    end
+  end
+end

data/lib/dogcatcher/markdown.rb

@@ -0,0 +1,30 @@
+module Dogcatcher
+  # Produces a string formatted as Markdown.
+  class Markdown
+    def initialize
+      @result = []
+    end
+
+    # Adds a bullet point to the result string.
+    #
+    # @param [String] str text to include next to the bullet point
+    def bullet(str)
+      @result << ['* ', str, "\n"]
+    end
+
+    # Adds a code block to the result string.
+    #
+    # @param [String] str text to include in the code block
+    # @param [String] language of the code block
+    def code_block(str, language = nil)
+      @result << ['```', language, "\n", str, "\n```\n"]
+    end
+
+    # Gets the result string formatted in Markdown.
+    #
+    # @return [String]
+    def result
+      ['%%%', "\n", *@result, "\n", '%%%'].join('')
+    end
+  end
+end

data/lib/dogcatcher/notice.rb

@@ -0,0 +1,69 @@
+module Dogcatcher
+  class Notice
+    # Name of the source that caught the exception
+    attr_accessor :notifier
+
+    # Name of the action that caused the exception
+    attr_accessor :action
+
+    # Additional information about the exception
+    attr_accessor :metadata
+
+    # The exception itself
+    attr_reader :exception
+
+    # @param [Dogcatcher::Config] config
+    # @param [Exception] exception
+    def initialize(config, exception)
+      @config = config
+      @exception = exception
+      @metadata = {}
+    end
+
+    # Markdown-formatted message containing the backtrace and metadata.
+    #
+    # @return [String]
+    def message
+      backtrace = @config.backtrace_cleaner.clean(exception.backtrace)
+      markdown = Markdown.new
+      metadata.each { |key, value| markdown.bullet("#{key}: #{value}") }
+      markdown.code_block(backtrace.join("\n"))
+      markdown.result
+    end
+
+    # Tags containing information about the event. If gem version tags are
+    # enabled then they will be included in the output.
+    #
+    # @return [Array<String>]
+    def tags
+      arr = []
+      arr << "notifier:#{notifier}"
+      arr << "action:#{action}"
+      arr << "exception_class:#{exception.class}"
+      arr << gem_tags if @config.gem_tags
+      arr.flatten
+    end
+
+    # Title of the event/notice.
+    #
+    # Includes the program name if a program name is configured.
+    #
+    # @return [String]
+    def title
+      program = "#{@config.program} - " if @config.program
+      "#{program}#{exception.class}:#{exception.message}"
+    end
+
+    private
+
+    # Searches for gem versions in the backtrace and derives tags from them.
+    #
+    # @return [Array<String>]
+    def gem_tags
+      exception.backtrace.map do |line|
+        match = line.scan(%r{gems/([A-Za-z\-_]+)-([0-9.]+(\.[a-z]+(\.[0-9]+)?)?)/})
+        match.empty? ? nil : match.flatten.compact.join(':')
+      end.compact
+    end
+  end
+end

data/lib/dogcatcher/notifier.rb

@@ -0,0 +1,38 @@
+module Dogcatcher
+  # Sends events/notices to the Datadog API and/or a statsd collector.
+  class Notifier
+    # @param [Dogcatcher::Config] config
+    def initialize(config)
+      @config = config
+    end
+
+    # Sends events/notices to the Datadog API and/or a statsd collector.
+    #
+    # @param [Dogcatcher::Notice]
+    def notify(notice)
+      notify_dogapi(notice) if @config.use_dogapi?
+      notify_statsd(notice) if @config.use_statsd?
+    end
+
+    private
+
+    # @param [Dogcatcher::Notice]
+    def notify_dogapi(notice)
+      event = Dogapi::Event.new(notice.message,
+                                msg_title: notice.title,
+                                tags: notice.tags,
+                                alert_type: 'error')
+
+      Dogapi::Client.new(@config.api_key).emit_event(event)
+    end
+
+    # @param [Dogcatcher::Notice]
+    def notify_statsd(notice)
+      client = Statsd.new(@config.statsd_host, @config.statsd_port)
+      client.event(notice.title,
+                   notice.message,
+                   tags: notice.tags,
+                   alert_type: 'error')
+    end
+  end
+end

data/lib/dogcatcher/version.rb

@@ -0,0 +1,3 @@
+module Dogcatcher
+  VERSION = '0.1.0'.freeze
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: dogcatcher
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ben Vidulich
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: dogapi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.22'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.22'
+- !ruby/object:Gem::Dependency
+  name: dogstatsd-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: Dogcatcher is a tool to catch exceptions in Ruby applications and send
+  them to Datadog
+email:
+- ben@vidulich.co.nz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .editorconfig
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- dogcatcher.gemspec
+- lib/dogcatcher.rb
+- lib/dogcatcher/config.rb
+- lib/dogcatcher/ext/rake/task.rb
+- lib/dogcatcher/markdown.rb
+- lib/dogcatcher/notice.rb
+- lib/dogcatcher/notifier.rb
+- lib/dogcatcher/version.rb
+- support/screenshot_event.png
+homepage: https://github.com/zl4bv/dogcatcher
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Dogcatcher is a tool to catch exceptions in Ruby applications and send them
+  to Datadog
+test_files: []