beaver 1.3.1 → 1.4.0

data/README.rdoc

@@ -8,7 +8,6 @@ Beaver is a light DSL and command line utility for parsing HTTP and Rails produc
 * Did anyone submit a form with the words "kill them all"? Yikes.
 * Rails 3.2 tagged logging is cool, but what's a good way to review them?
 
-Read the full documentation at {jordanhollinger.com/docs/beaver/}[http://jordanhollinger.com/docs/beaver/].
 For a full list of matchers available to "hit", see the Beaver::Dam class.
 For a full list of methods available inside a "hit" block, or to members of the "hits" array in a "dam" block, see the Beaver::Request, Beaver::Parsers::Rails, and Beaver::Parsers::HTTP classes.
 
@@ -55,6 +54,15 @@ Run ''beaver'' from the command line, passing in your beaver file and some logs:
   require 'rubygems'
   require 'beaver'
 
+  Beaver.stream '/path/to/httpd/access_logs*' do
+    hit :failed_logins, :method => :post, :path => '/login', :status => 401
+    dam :failed_logins do
+      puts "#{hits.size} failed logins!"
+    end
+  end
+
+Or with even less DSL...
+
   beaver = Beaver.new('/path/to/httpd/access_logs*')
   beaver.hit :failed_logins, :method => :post, :path => '/login', :status => 401
   beaver.dam :failed_logins do
@@ -62,6 +70,14 @@ Run ''beaver'' from the command line, passing in your beaver file and some logs:
   end
   beaver.stream
 
+Or just to parse and return the matching requests...
+
+  requests = Beaver.dam('/path/to/rails/production.log*', :method => :put)
+
+Or as just a parser (no filtering)...
+
+  requests = Beaver.parse('/path/to/rails/production.log*')
+
 == Use beaver as part of the *nix toolchain
 
 It's difficult to grep through a multi-line log format like Rails' and output each matching multi-line event (though I hear Google is working on a 'Context-Free Grep', which may help solve that). Until then, for Rails anyway, beaver is happy to step in.

data/lib/beaver/beaver.rb

@@ -1,7 +1,17 @@
-# Not specifically a performance analyzer (like https://github.com/wvanbergen/request-log-analyzer/wiki)
-# Rather, a DSL for finding out how people are using your Rails app (which could include performance).
+# A DSL and library for finding out how people are using your Rails app.
 # Can also be used to parse/analyze HTTP access logs (Apache, Nginx, etc.)
+#
+#  # Parse and return the requests
+#  requests = Beaver.parse('/path/to/log/files')
+#
+#  # Parse, filters, and returns the requests (all requests are always returned)
+#  requests = Beaver.filter('/path/to/log/files') do
+#    hit :error, :status => (400..505) do
+#      puts "#{status} on #{path} at #{time} from #{ip} with #{params_str}"
+#    end
+#  end
 # 
+#  # Parse and filters the requests, returns nil
 #  Beaver.stream('/path/to/log/files') do
 #    hit :error, :status => (400..505) do
 #      puts "#{status} on #{path} at #{time} from #{ip} with #{params_str}"
@@ -9,18 +19,33 @@
 #  end
 # 
 module Beaver
-  # Creates a new Beaver and immediately filters the log files. This should scale well
-  # for even very large logs, at least when compared to Beaver#parse.
+  # Parses the logs and returns the requests.
+  def self.parse(*args)
+    Beaver.new(*args).parse.requests
+  end
+
+  # Parses the logs and filters them through the given block. *All* parsed requests 
+  # are returned, not just the ones that matched. This is useful for when you take your action(s) on the matching reqeusts *inside* the block, but you still want access to all the requsts afterwords.
+  def self.filter(*args, &blk)
+    Beaver.new(*args, &blk).parse.filter.requests
+  end
+
+  # Parses the logs and filters them through the (optional) block. Parsed requests are
+  # not retained, hence are not returned. Returns nil.
+  # 
+  # In theory, this should be more memory efficient than Beaver#filter.
   def self.stream(*args, &blk)
-    raise ArgumentError, 'You must pass a block to Beaver#stream' unless block_given?
     Beaver.new(*args, &blk).stream
+    nil
   end
 
-  # Identical to Beaver#stream, except that the requests are retained, so you may
-  # examine them afterwards. For large logs, this may be noticibly inefficient.
-  def self.parse(*args, &blk)
-    raise ArgumentError, 'You must pass a block to Beaver#parse' unless block_given?
-    Beaver.new(*args, &blk).parse.filter
+  # Parses the logs and filters them through the provided matcher options. Returns *only* the matching requests.
+  def self.dam(*args)
+    beaver = Beaver.new(*args)
+    dam = beaver.hit :hits
+    beaver.parse
+    beaver.filter
+    dam.hits
   end
 
   # Alias to Beaver::Beaver.new
@@ -84,7 +109,7 @@ module Beaver
     end
 
     # Parses the logs and immediately filters them through the dams. Requests are not retained,
-    # so this should scale well to very large sets of logs.
+    # so this should scale better to very large sets of logs.
     def stream
       # Match the request against each dam, and run the dam's callback
       _parse do |request|

data/lib/beaver/version.rb

@@ -1,4 +1,4 @@
 module Beaver
-  MAJOR_VERSION, MINOR_VERSION, TINY_VERSION, PRE_VERSION = 1, 3, 1, nil # :nodoc:
+  MAJOR_VERSION, MINOR_VERSION, TINY_VERSION, PRE_VERSION = 1, 4, 0, nil # :nodoc:
   VERSION = [MAJOR_VERSION, MINOR_VERSION, TINY_VERSION, PRE_VERSION].compact.join '.' # :nodoc:
 end

metadata

@@ -1,32 +1,24 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: beaver
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 1
-  - 3
-  - 1
-  version: 1.3.1
+version: !ruby/object:Gem::Version
+  version: 1.4.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-06-30 00:00:00 -04:00
-default_executable: 
+date: 2012-11-12 00:00:00.000000000 Z
 dependencies: []
-
-description: A simple DSL and command-line tool for discovering what people are up to in your Rails app
+description: A simple DSL and command-line tool for discovering what people are up
+  to in your Rails app
 email: jordan@jordanhollinger.com
-executables: 
+executables:
 - beaver
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - lib/beaver.rb
 - lib/beaver/dam.rb
 - lib/beaver/beaver.rb
@@ -38,37 +30,28 @@ files:
 - README.rdoc
 - LICENSE
 - bin/beaver
-has_rdoc: true
 homepage: http://github.com/jhollinger/beaver
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Rails log parser
 test_files: []
-