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.



30
31
32
 
# File 'lib/timber/current_context.rb', line 30

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

.fetch(*args) ⇒ Object

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



35
36
37
 
# File 'lib/timber/current_context.rb', line 35

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

.instance ⇒ Object

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



20
21
22
 
# File 'lib/timber/current_context.rb', line 20

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

.remove(*args) ⇒ Object

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



40
41
42
 
# File 'lib/timber/current_context.rb', line 40

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

.reset(*args) ⇒ Object

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



45
46
47
 
# File 'lib/timber/current_context.rb', line 45

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

.with(*args, &block) ⇒ Object

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



25
26
27
 
# File 'lib/timber/current_context.rb', line 25

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.



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

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

#fetch(*args) ⇒ Object

Fetch a specific context by key.



83
84
85
 
# File 'lib/timber/current_context.rb', line 83

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

#remove(*objects) ⇒ Object

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



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/timber/current_context.rb', line 89

def remove(*objects)
  objects.each do |object|
    if object.is_a?(Symbol)
      hash.delete(object)
    else
      context = Contexts.build(object)

      if context.keyspace == :custom
        # Custom contexts are merged and should be removed the same
        hash[context.keyspace].delete(context.type)
        if hash[context.keyspace] == {}
          hash.delete(context.keyspace)
        end
      else
        hash.delete(context.keyspace)
      end
    end
  end
  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.



113
114
115
116
117
 
# File 'lib/timber/current_context.rb', line 113

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.



122
123
124
 
# File 'lib/timber/current_context.rb', line 122

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.

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

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) { ... }


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

def with(*objects)
  add(*objects)
  yield
ensure
  remove(*objects)
end