Class: Timber::CurrentContext

Inherits:
Object
  • Object
show all
Defined in:
lib/timber/current_context.rb

Overview

Note:

Because context is appended to every log line, it is recommended that you limit this to only neccessary data needed to relate your log lines.

Holds the current context in a thread safe memory storage. This context is appended to every log line. Think of context as join data between your log lines, allowing you to relate them and filter them appropriately.

Constant Summary collapse

THREAD_NAMESPACE = 
:_timber_current_context.freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.add(*args) ⇒ Object

Convenience method for #add. See #add for more info.



23
24
25
 
# File 'lib/timber/current_context.rb', line 23

def add(*args)
  instance.add(*args)
end

.fetch(*args) ⇒ Object

Convenience method for #fetch. See #fetch for more info.



28
29
30
 
# File 'lib/timber/current_context.rb', line 28

def fetch(*args)
  instance.fetch(*args)
end

.instance ⇒ Object

Impelements the Singleton pattern in a thread specific way. Each thread receives its own context.



18
19
20
 
# File 'lib/timber/current_context.rb', line 18

def instance
  Thread.current[THREAD_NAMESPACE] ||= new
end

.remove(*args) ⇒ Object

Convenience method for #remove. See #remove for more info.



33
34
35
 
# File 'lib/timber/current_context.rb', line 33

def remove(*args)
  instance.remove(*args)
end

.reset(*args) ⇒ Object

Convenience method for #reset. See #reset for more info.



38
39
40
 
# File 'lib/timber/current_context.rb', line 38

def reset(*args)
  instance.reset(*args)
end

.with(*args, &block) ⇒ Object

Convenience method for #with. See #with for more info.



43
44
45
 
# File 'lib/timber/current_context.rb', line 43

def with(*args, &block)
  instance.with(*args, &block)
end

Instance Method Details

#add(*objects) ⇒ Object

Note:

Because context is included with every log line, it is recommended that you limit this to only neccessary data.

Adds contexts but does not remove them. See #with for automatic maintenance and #remove to remove them yourself.



53
54
55
56
57
58
59
 
# File 'lib/timber/current_context.rb', line 53

def add(*objects)
  objects.each do |object|
    hash.merge!(object.to_hash)
  end
  expire_cache!
  self
end

#fetch(*args) ⇒ Object

Fetch a specific context by key.



62
63
64
 
# File 'lib/timber/current_context.rb', line 62

def fetch(*args)
  hash.fetch(*args)
end

#remove(*keys) ⇒ Object

Removes a context. If you wish to remove by key, or some other way, use #hash and modify the hash accordingly.



68
69
70
71
72
73
74
 
# File 'lib/timber/current_context.rb', line 68

def remove(*keys)
  keys.each do |keys|
    hash.delete(keys)
  end
  expire_cache!
  self
end

#replace(hash) ⇒ Object 



76
77
78
79
80
 
# File 'lib/timber/current_context.rb', line 76

def replace(hash)
  @hash = hash
  expire_cache!
  self
end

#reset ⇒ Object

Resets the context to be blank. Use this carefully! This will remove any context, include context that is automatically included with Timber.



84
85
86
87
88
 
# File 'lib/timber/current_context.rb', line 84

def reset
  hash.clear
  expire_cache!
  self
end

#snapshot ⇒ Object

Snapshots the current context so that you get a moment in time representation of the context, since the context can change as execution proceeds. Note that individual contexts should be immutable, and we implement snapshot caching as a result of this assumption.



93
94
95
 
# File 'lib/timber/current_context.rb', line 93

def snapshot
  @snapshot ||= hash.clone
end

#with(*objects) ⇒ Object

Note:

Because context is included with every log line, it is recommended that you limit this to only neccessary data.

Note:

Any custom context needs to have a single root key to be valid. i.e. instead of: Timber::CurrentContext.with(job_id: “123”, job_name: “Refresh User Account”)

Adds a context and then removes it when the block is finished executing.

do

Timber::CurrentContext.with(job: {job_id: "123", job_name: "Refresh User Account"})

Examples:

Adding a custom context

Timber::CurrentContext.with({build: {version: "1.0.0"}}) do
  # ... anything logged here will include the context ...
end

Adding multiple contexts

Timber::CurrentContext.with(context1, context2) { ... }


116
117
118
119
120
121
122
123
124
 
# File 'lib/timber/current_context.rb', line 116

def with(*objects)
  old_hash = hash.clone
  begin
    add(*objects)
    yield
  ensure
    replace(old_hash)
  end
end