= Samuel

Samuel is a gem for automatic logging of your HTTP requests. It's named for
the serial diarist Mr. Pepys, who was known to reliably record events both
quotidian and remarkable.

Should a Great Plague, Fire, or Whale befall an important external web service
you use, you'll be sure to have a tidy record of it.

It supports both Net::HTTP and HTTPClient (formerly HTTPAccess2),
automatically loading the correct logger for the HTTP client you're using.

== Usage

If you're using Bundler, just add this to your Gemfile:

  gem "samuel", "~> 0.3"

When Rails is loaded, Samuel configures itself to use Rails's logger and an
ActiveRecord-like format automatically, so you don't need to do anything else.

For non-Rails projects, you'll have to manually configure logging, like this:

  require 'samuel'
  Samuel.logger = Logger.new('http_requests.log')

If you don't assign a logger, Samuel will configure a default logger on +STDOUT+.

== HTTP Clients

When you load Samuel, it automatically detects which HTTP clients you've
loaded, then patches them to add logging. If no HTTP drivers are loaded when
you load Samuel, it will automatically load Net::HTTP for you. (So, if you're
using HTTPClient or a library based on it, make sure to require it before you
require Samuel.)

== Configuration

There are two ways to specify configuration options for Samuel: global and
inline. Global configs look like this:

  Samuel.config[:labels]          = {"example.com" => "Example API"}
  Samuel.config[:filtered_params] = :password

You should put global configuration somewhere early-on in your program. If
you're using Rails, <tt>config/initializers/samuel.rb</tt> will do the trick.

Alternatively, an inline configuration block temporarily overrides any global
configuration for a set of HTTP requests:

  Samuel.with_config :label => "Twitter API" do
    Net::HTTP.start("twitter.com") { |http| http.get("/help/test") }
  end

Right now, there are three configuration changes you can make in either style:

* <tt>:labels</tt> -- This is a hash with domain substrings as keys and log
  labels as values. If a request domain includes one of the domain substrings,
  the corresponding label will be used for the first part of that log entry.
  By default this is empty, so that all requests are labeled with a default of
  <tt>"HTTP Request"</tt>.

* <tt>:label</tt> -- As an alternative to the <tt>:labels</tt> hash, this is
  simply a string. If set, it takes precedence over any <tt>:labels</tt> (by
  default, it's not set). It gets <tt>"Request"</tt> appended to it as well --
  so if you want your log to always say <tt>Twitter API Request</tt> instead
  of the default <tt>HTTP Request</tt>, you can set this to <tt>"Twitter
  API"</tt>. I'd recommend using this setting globally if you're only making
  requests to one service, or inline if you just need to temporarily override
  the global <tt>:labels</tt>.

* <tt>:filtered_params</tt> -- This works just like Rails's
  +filter_parameter_logging+ method. Set it to a symbol, string, or array of
  them, and Samuel will filter the value of query parameters that have any of
  these patterns as a substring by replacing the value with
  <tt>[FILTERED]</tt> in your logs. By default, no filtering is enabled.

Samuel logs successful HTTP requests at the +INFO+ level; Failed requests log
at the +WARN+ level. This isn't currently configurable, but it's on the list.

== License

Copyright 2009–2011 Chris Kampmeier. See +LICENSE+ for details.
