Class: Timber::CurrentContext

Inherits:
Object
  • Object
show all
Includes:
Singleton
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 full details and examples.



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

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

.hash(*args) ⇒ Object 



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

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

.remove(*args) ⇒ Object

Convenience method for #remove. See #remove for full details and examples.



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

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

.reset(*args) ⇒ Object 



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

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

.with(*args, &block) ⇒ Object

Convenience method for #with. See #with for full details and examples.



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

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.



75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/timber/current_context.rb', line 75

def add(*objects)
  objects.each do |object|
    context = Contexts.build(object) # Normalizes objects into a Timber::Context descendant.
    key = context.keyspace
    json = context.as_json # Convert to json now so that we aren't doing it for every line
    if key == :custom
      # Custom contexts are merged into the space
      hash[key] ||= {}
      hash[key].merge!(json)
    else
      hash[key] = json
    end
  end
end

#hash ⇒ Object

The internal hash that is maintained. It is recommended that you use #with and #add for hash maintenance.



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

def hash
  Thread.current[THREAD_NAMESPACE] ||= {}
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.



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/timber/current_context.rb', line 98

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
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.



120
121
122
 
# File 'lib/timber/current_context.rb', line 120

def reset
  hash.clear
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.



126
127
128
 
# File 'lib/timber/current_context.rb', line 126

def 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 with a map

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

Adding a custom context with a struct

BuildContext = Struct.new(:version) do
  def type; :build; end
 end
 build_context = BuildContext.new("1.0.0")
 Timber::CurrentContext.with(build_context) do
  # ... anything logged here will include the context ...
end
# Be sure to checkout Timber::Contexts! These are officially supported and many of these
# will be automatically included via Timber::Integrations

Adding multiple contexts

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


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

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