timber 2.2.0 → 2.2.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +9 -1
- data/README.md +35 -83
- data/lib/timber/integrations/rack/user_context.rb +4 -17
- data/lib/timber/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 66720d601b2548f7390c9c5f37b98dfc9b3374c4
|
|
4
|
+
data.tar.gz: 6dd041106e908bd9d240e4633e0db7026ca0640b
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: ee4f83cffdffb37160e5e4bc385a9148e11a6cfb9106d928ce18e21399074f6b3087d3c45110de98bd876430bee54719656b66a8f62cf715e72e4565d5326bd6
|
|
7
|
+
data.tar.gz: 2c823beb4dabc9b0da1f543d5e836087989640002799f1422092bed6b555083d15e4b7aa4260cc8cdc2a86d32ebf3ebbbe9007d858f20f0cbaeb5b62c1088ceb
|
data/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [2.2.1] - 2017-09-13
|
|
11
|
+
### Changed
|
|
12
|
+
|
|
13
|
+
- Omniauth integration was removed since it only captures user context during the Authentication
|
|
14
|
+
phase. Omniauth does not persist sessions. As such, the integration is extremely low value
|
|
15
|
+
and could cause unintended issues.
|
|
16
|
+
|
|
10
17
|
## [2.2.0] - 2017-09-13
|
|
11
18
|
### Changed
|
|
12
19
|
|
|
@@ -16,5 +23,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
|
|
|
16
23
|
instead of applying back pressure.
|
|
17
24
|
|
|
18
25
|
|
|
19
|
-
[Unreleased]: https://github.com/timberio/timber-ruby/compare/v2.2.
|
|
26
|
+
[Unreleased]: https://github.com/timberio/timber-ruby/compare/v2.2.1...HEAD
|
|
27
|
+
[2.2.1]: https://github.com/timberio/timber-ruby/compare/v2.2.0...v2.2.1
|
|
20
28
|
[2.2.0]: https://github.com/timberio/timber-ruby/compare/v2.1.10...v2.2.0
|
data/README.md
CHANGED
|
@@ -5,14 +5,17 @@
|
|
|
5
5
|
[](https://travis-ci.org/timberio/timber-ruby)
|
|
6
6
|
[](https://codeclimate.com/github/timberio/timber-ruby)
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
8
|
+
Timber for Ruby is a drop in replacement for your Ruby logger that
|
|
9
|
+
[unobtrusively augments](https://timber.io/docs/concepts/structuring-through-augmentation) your
|
|
10
|
+
logs with [rich metadata and context](https://timber.io/docs/concepts/metadata-context-and-events)
|
|
11
|
+
making them [easier to search, use, and read](#get-things-done-with-your-logs). It pairs with the
|
|
12
|
+
[Timber console](#the-timber-console) to deliver a tailored Ruby logging experience designed to make
|
|
13
|
+
you more productive.
|
|
11
14
|
|
|
12
15
|
1. [**Installation** - One command: `bundle exec timber install`](#installation)
|
|
13
|
-
2. [**Usage** - Simple
|
|
16
|
+
2. [**Usage** - Simple & powerful API](#usage)
|
|
14
17
|
3. [**Integrations** - Automatic context and metadata for your existing logs](#integrations)
|
|
15
|
-
4. [**The Timber Console** - Designed for
|
|
18
|
+
4. [**The Timber Console** - Designed for applications & developers](#the-timber-console)
|
|
16
19
|
5. [**Get things done with your logs 💪**](#get-things-done-with-your-logs)
|
|
17
20
|
|
|
18
21
|
|
|
@@ -24,9 +27,11 @@ readable logs that are easier to search and use:
|
|
|
24
27
|
gem 'timber', '~> 2.1'
|
|
25
28
|
```
|
|
26
29
|
|
|
27
|
-
2. In your `shell`, run
|
|
30
|
+
2. In your `shell`, run:
|
|
28
31
|
|
|
29
|
-
|
|
32
|
+
```
|
|
33
|
+
bundle install && bundle exec timber install
|
|
34
|
+
```
|
|
30
35
|
|
|
31
36
|
|
|
32
37
|
## Usage
|
|
@@ -43,9 +48,11 @@ logger.error("Error message")
|
|
|
43
48
|
logger.fatal("Fatal message")
|
|
44
49
|
```
|
|
45
50
|
|
|
46
|
-
|
|
47
|
-
[
|
|
48
|
-
|
|
51
|
+
1. [Search it](https://timber.io/docs/app/console/searching) with queries like: `error message`
|
|
52
|
+
2. [Alert on it](https://timber.io/docs/app/console/alerts) with threshold based alerts
|
|
53
|
+
3. [View this event's metadata and context](https://timber.io/docs/app/console/view-metdata-and-context)
|
|
54
|
+
|
|
55
|
+
[...read more in our docs](https://timber.io/docs/languages/ruby/usage/basic-logging)
|
|
49
56
|
|
|
50
57
|
---
|
|
51
58
|
|
|
@@ -53,13 +60,7 @@ metadata, you don't have to worry about making every log structured!
|
|
|
53
60
|
|
|
54
61
|
<details><summary><strong>Logging events (structured data)</strong></summary><p>
|
|
55
62
|
|
|
56
|
-
|
|
57
|
-
structured data name or type conflicts. Keep in mind, Timber defines common events in the
|
|
58
|
-
[`Timber::Events`](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Events) namespace,
|
|
59
|
-
which are automatically logged for you through our [integrations](#integrations). You should not
|
|
60
|
-
have to maually log events defined there except in special circumstances.
|
|
61
|
-
|
|
62
|
-
### How to use it
|
|
63
|
+
Log structured data without sacrificing readability:
|
|
63
64
|
|
|
64
65
|
```ruby
|
|
65
66
|
logger.warn "Payment rejected", payment_rejected: {customer_id: "abcd1234", amount: 100, reason: "Card expired"}
|
|
@@ -67,9 +68,9 @@ logger.warn "Payment rejected", payment_rejected: {customer_id: "abcd1234", amou
|
|
|
67
68
|
|
|
68
69
|
1. [Search it](https://timber.io/docs/app/console/searching) with queries like: `type:payment_rejected` or `payment_rejected.amount:>100`
|
|
69
70
|
2. [Alert on it](https://timber.io/docs/app/console/alerts) with threshold based alerts
|
|
70
|
-
3. [Graph & visualize it](https://timber.io/docs/app/console/graphing)
|
|
71
71
|
4. [View this event's data and context](https://timber.io/docs/app/console/view-metdata-and-context)
|
|
72
|
-
|
|
72
|
+
|
|
73
|
+
...[read more in our docs](https://timber.io/docs/languages/ruby/usage/custom-events)
|
|
73
74
|
|
|
74
75
|
---
|
|
75
76
|
|
|
@@ -77,17 +78,7 @@ logger.warn "Payment rejected", payment_rejected: {customer_id: "abcd1234", amou
|
|
|
77
78
|
|
|
78
79
|
<details><summary><strong>Setting context</strong></summary><p>
|
|
79
80
|
|
|
80
|
-
|
|
81
|
-
environment when the log was written, allowing you to relate logs so you can easily segment them.
|
|
82
|
-
It's how Timber is able to accomplish features like
|
|
83
|
-
[tailing users](https://timber.io/docs/app/console/tail-a-user) and
|
|
84
|
-
[tracing HTTP requests](https://timber.io/docs/app/console/trace-http-requests).
|
|
85
|
-
Keep in mind, Timber defines common contexts in the
|
|
86
|
-
[`Timber::Contexts`](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Contexts) namespace,
|
|
87
|
-
which are automatically set for you through our [integrations](#integrations). You should not
|
|
88
|
-
have to maually set these contexts except in special circumstances.
|
|
89
|
-
|
|
90
|
-
### How to use it
|
|
81
|
+
Add shared structured data across your logs:
|
|
91
82
|
|
|
92
83
|
```ruby
|
|
93
84
|
Timber.with_context(job: {id: 123}) do
|
|
@@ -99,24 +90,16 @@ end
|
|
|
99
90
|
|
|
100
91
|
1. [Search it](https://timber.io/docs/app/console/searching) with queries like: `job.id:123`
|
|
101
92
|
2. [View this context when viewing a log's metadata](https://timber.io/docs/app/console/view-metdata-and-context)
|
|
102
|
-
|
|
93
|
+
|
|
94
|
+
...[read more in our docs](https://timber.io/docs/languages/ruby/usage/custom-context)
|
|
103
95
|
|
|
104
96
|
---
|
|
105
97
|
|
|
106
98
|
</p></details>
|
|
107
99
|
|
|
108
|
-
<details><summary><strong>Metrics &
|
|
100
|
+
<details><summary><strong>Metrics, Timings, & Tracing</strong></summary><p>
|
|
109
101
|
|
|
110
|
-
|
|
111
|
-
[logging an event](https://timber.io/docs/languages/ruby/usage/custom-events). Timber is based on
|
|
112
|
-
modern big-data principles and can aggregate inordinately large data sets in seconds. Logging
|
|
113
|
-
events (raw data as it exists), gives you the flexibility in the future to segment and aggregate
|
|
114
|
-
your data any way you see fit. This is superior to choosing specific paradigms before hand, when
|
|
115
|
-
you are unsure how you'll need to use your data in the future.
|
|
116
|
-
|
|
117
|
-
### How to use it
|
|
118
|
-
|
|
119
|
-
Below is a contrived example of timing a background job:
|
|
102
|
+
Time code blocks:
|
|
120
103
|
|
|
121
104
|
```ruby
|
|
122
105
|
timer = Timber.start_timer
|
|
@@ -124,13 +107,7 @@ timer = Timber.start_timer
|
|
|
124
107
|
logger.info("Processed background job", background_job: {time_ms: timer})
|
|
125
108
|
```
|
|
126
109
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
```ruby
|
|
130
|
-
logger.info("Processed background job", background_job: {time_ms: 45.6})
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
Lastly, metrics aren't limited to timings. You can capture any metric you want:
|
|
110
|
+
Log generic metrics:
|
|
134
111
|
|
|
135
112
|
```ruby
|
|
136
113
|
logger.info("Credit card charged", credit_card_charge: {amount: 123.23})
|
|
@@ -139,8 +116,8 @@ logger.info("Credit card charged", credit_card_charge: {amount: 123.23})
|
|
|
139
116
|
1. [Search it](https://timber.io/docs/app/console/searching) with queries like: `background_job.time_ms:>500`
|
|
140
117
|
2. [Alert on it](https://timber.io/docs/app/console/alerts) with threshold based alerts
|
|
141
118
|
3. [View this log's metadata in the console](https://timber.io/docs/app/console/view-metdata-and-context)
|
|
142
|
-
4. ...read more in our [docs](https://timber.io/docs/languages/ruby/usage/metrics-and-timings)
|
|
143
119
|
|
|
120
|
+
...[read more in our docs](https://timber.io/docs/languages/ruby/usage/metrics-and-timings)
|
|
144
121
|
|
|
145
122
|
</p></details>
|
|
146
123
|
|
|
@@ -152,20 +129,14 @@ Below are a few popular configuration options, for a comprehensive list, see
|
|
|
152
129
|
|
|
153
130
|
<details><summary><strong>Logrageify. Silence noisy logs.</strong></summary><p>
|
|
154
131
|
|
|
155
|
-
|
|
156
|
-
[lograge](https://github.com/roidrage/lograge)
|
|
157
|
-
option for anyone transitioning from lograge.
|
|
158
|
-
|
|
159
|
-
### How to use it
|
|
132
|
+
Silence noisy logs that aren't of value to you, just like
|
|
133
|
+
[lograge](https://github.com/roidrage/lograge):
|
|
160
134
|
|
|
161
135
|
```ruby
|
|
162
136
|
# config/initializers/timber.rb
|
|
163
|
-
|
|
164
137
|
Timber.config.logrageify!()
|
|
165
138
|
```
|
|
166
139
|
|
|
167
|
-
### How it works
|
|
168
|
-
|
|
169
140
|
It turns this:
|
|
170
141
|
|
|
171
142
|
```
|
|
@@ -182,18 +153,7 @@ Completed 200 OK in 79ms (Views: 78.8ms | ActiveRecord: 0.0ms)
|
|
|
182
153
|
Into this:
|
|
183
154
|
|
|
184
155
|
```
|
|
185
|
-
Get "/" sent 200 OK in 79ms
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
Internally this is equivalent to:
|
|
189
|
-
|
|
190
|
-
```ruby
|
|
191
|
-
# config/initializers/timber.rb
|
|
192
|
-
|
|
193
|
-
Timber.config.integrations.action_controller.silence = true
|
|
194
|
-
Timber.config.integrations.action_view.silence = true
|
|
195
|
-
Timber.config.integrations.active_record.silence = true
|
|
196
|
-
Timber.config.integrations.rack.http_events.collapse_into_single_event = true
|
|
156
|
+
Get "/" sent 200 OK in 79ms
|
|
197
157
|
```
|
|
198
158
|
|
|
199
159
|
### Pro-tip: Keep controller call logs (recommended)
|
|
@@ -222,11 +182,8 @@ For a full list of integration settings, see
|
|
|
222
182
|
<details><summary><strong>Silence specific requests (LB health checks, etc)</strong></summary><p>
|
|
223
183
|
|
|
224
184
|
Silencing noisy requests can be helpful for silencing load balance health checks, bot scanning,
|
|
225
|
-
or activity that generally is not meaningful to you.
|
|
226
|
-
|
|
227
|
-
### How to use it
|
|
228
|
-
|
|
229
|
-
The following will silence all `[GET] /_health` requests:
|
|
185
|
+
or activity that generally is not meaningful to you. The following will silence all
|
|
186
|
+
`[GET] /_health` requests:
|
|
230
187
|
|
|
231
188
|
```ruby
|
|
232
189
|
# config/initializers/timber.rb
|
|
@@ -247,12 +204,10 @@ The first parameter being the traditional Rack env hash, the second being a
|
|
|
247
204
|
<details><summary><strong>Capture custom user context</strong></summary><p>
|
|
248
205
|
|
|
249
206
|
By default Timber automatically captures user context for most of the popular authentication
|
|
250
|
-
libraries (Devise,
|
|
207
|
+
libraries (Devise, and Clearance). See
|
|
251
208
|
[Timber::Integrations::Rack::UserContext](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Integrations/Rack/UserContext)
|
|
252
209
|
for a complete list.
|
|
253
210
|
|
|
254
|
-
### How to use it
|
|
255
|
-
|
|
256
211
|
In cases where you Timber doesn't support your strategy, or you want to customize it further,
|
|
257
212
|
you can do so like:
|
|
258
213
|
|
|
@@ -284,8 +239,6 @@ end
|
|
|
284
239
|
[Timber::Contexts::Release](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Contexts/Release)
|
|
285
240
|
tracks the current application release and version.
|
|
286
241
|
|
|
287
|
-
### How to use it
|
|
288
|
-
|
|
289
242
|
If you're on Heroku, simply enable the
|
|
290
243
|
[dyno metadata](https://devcenter.heroku.com/articles/dyno-metadata) feature. If you are not,
|
|
291
244
|
set the following environment variables and this context will be added automatically:
|
|
@@ -304,7 +257,7 @@ All variables are optional, but at least one must be present.
|
|
|
304
257
|
## Integrations
|
|
305
258
|
|
|
306
259
|
Timber integrates with popular frameworks and libraries to capture context and metadata you
|
|
307
|
-
couldn't otherwise. This automatically
|
|
260
|
+
couldn't otherwise. This automatically augments logs produced by these libraries, making them
|
|
308
261
|
[easier to search and use](#do-amazing-things-with-your-logs). Below is a list of libraries we
|
|
309
262
|
support:
|
|
310
263
|
|
|
@@ -313,7 +266,6 @@ support:
|
|
|
313
266
|
* [**Rack**](https://timber.io/docs/languages/ruby/integrations/rack)
|
|
314
267
|
* [**Devise**](https://timber.io/docs/languages/ruby/integrations/devise)
|
|
315
268
|
* [**Clearance**](https://timber.io/docs/languages/ruby/integrations/clearnace)
|
|
316
|
-
* [**Omniauth**](https://timber.io/docs/languages/ruby/integrations/omniauth)
|
|
317
269
|
* [**Warden**](https://timber.io/docs/languages/ruby/integrations/devise)
|
|
318
270
|
* Platforms
|
|
319
271
|
* [**Heroku**](https://timber.io/docs/languages/ruby/integrations/heroku)
|
|
@@ -324,7 +276,7 @@ support:
|
|
|
324
276
|
|
|
325
277
|
## Get things done with your logs
|
|
326
278
|
|
|
327
|
-
Logging features
|
|
279
|
+
Logging features designed to help developers get more done:
|
|
328
280
|
|
|
329
281
|
1. [**Powerful searching.** - Find what you need faster.](https://timber.io/docs/app/console/searching)
|
|
330
282
|
2. [**Live tail users.** - Easily solve customer issues.](https://timber.io/docs/app/console/tail-a-user)
|
|
@@ -8,6 +8,8 @@ module Timber
|
|
|
8
8
|
# This is a Rack middleware responsible for setting the user context.
|
|
9
9
|
# See {Timber::Contexts::User} for more information on the user context.
|
|
10
10
|
#
|
|
11
|
+
# ## Why a Rack middleware?
|
|
12
|
+
#
|
|
11
13
|
# We use a Rack middleware because we want to set the user context as early as
|
|
12
14
|
# possible, and before the initial incoming request log line:
|
|
13
15
|
#
|
|
@@ -29,7 +31,6 @@ module Timber
|
|
|
29
31
|
# automatically set the user context for you.
|
|
30
32
|
#
|
|
31
33
|
# * Devise, or any Warden based authentication strategy
|
|
32
|
-
# * Omniauth
|
|
33
34
|
# * Clearance
|
|
34
35
|
#
|
|
35
36
|
# Or, you can use your own custom authentication, see the {.custom_user_context}
|
|
@@ -47,7 +48,7 @@ module Timber
|
|
|
47
48
|
#
|
|
48
49
|
# @example Setting your own custom user context
|
|
49
50
|
# Timber::Integrations::Rack::UserContext.custom_user_hash = lambda do |rack_env|
|
|
50
|
-
#
|
|
51
|
+
# rack_env['my_custom_key'].user
|
|
51
52
|
# end
|
|
52
53
|
def custom_user_hash=(proc)
|
|
53
54
|
if proc && !proc.is_a?(Proc)
|
|
@@ -78,14 +79,10 @@ module Timber
|
|
|
78
79
|
private
|
|
79
80
|
def get_user_hash(env)
|
|
80
81
|
# The order is relevant here. The 'warden' key can be set, but
|
|
81
|
-
# not return a user, in which case the user data might be in
|
|
82
|
-
# data.
|
|
82
|
+
# not return a user, in which case the user data might be in another key.
|
|
83
83
|
if self.class.custom_user_hash.is_a?(Proc)
|
|
84
84
|
Timber::Config.instance.debug { "Obtaining user context from the custom user hash" }
|
|
85
85
|
self.class.custom_user_hash.call(env)
|
|
86
|
-
elsif (auth_hash = env['omniauth.auth'])
|
|
87
|
-
Timber::Config.instance.debug { "Obtaining user context from the omniauth auth hash" }
|
|
88
|
-
get_omniauth_user_hash(auth_hash)
|
|
89
86
|
elsif env[:clearance] && env[:clearance].signed_in?
|
|
90
87
|
Timber::Config.instance.debug { "Obtaining user context from the clearance user" }
|
|
91
88
|
user = env[:clearance].current_user
|
|
@@ -99,16 +96,6 @@ module Timber
|
|
|
99
96
|
end
|
|
100
97
|
end
|
|
101
98
|
|
|
102
|
-
def get_omniauth_user_hash(auth_hash)
|
|
103
|
-
info = auth_hash['info']
|
|
104
|
-
|
|
105
|
-
{
|
|
106
|
-
id: auth_hash['uid'],
|
|
107
|
-
name: info['name'],
|
|
108
|
-
email: info['email']
|
|
109
|
-
}
|
|
110
|
-
end
|
|
111
|
-
|
|
112
99
|
def get_user_object_hash(user)
|
|
113
100
|
id = try_user_id(user)
|
|
114
101
|
name = try_user_name(user)
|
data/lib/timber/version.rb
CHANGED