1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
= 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.
|
