timber 2.2.0 → 2.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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