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 



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

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

.remove(*args) ⇒ Object

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



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

def remove(*args)
  instance.remove(*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.



78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/timber/current_context.rb', line 78

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.



103
104
105
 
# File 'lib/timber/current_context.rb', line 103

def hash
  Thread.current[THREAD_NAMESPACE] ||= {}
end

#remove(*contexts) ⇒ Object

Removes a context. This must be a Timber::Context type. See Timber::Contexts for a list. If you wish to remove by key, or some other way, use #hash and modify the hash accordingly.



95
96
97
98
99
 
# File 'lib/timber/current_context.rb', line 95

def remove(*contexts)
  contexts.each do |context|
    hash.delete(context.keyspace)
  end
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.



109
110
111
 
# File 'lib/timber/current_context.rb', line 109

def snapshot
  hash.clone
end

#with(*contexts) ⇒ 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::Probes

Adding multiple contexts

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


59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/timber/current_context.rb', line 59

def with(*contexts)
  add(*contexts)
  yield
ensure
  contexts.each do |context|
    if context.keyspace == :custom
      # Custom contexts are merged and should be removed the same
      hash[context.keyspace].delete(context.type)
    else
      remove(context)
    end
  end
end