Module: Logging::MappedDiagnosticContext

### Home Classes Methods

### In Files

- lib/logging/diagnostic_context.rb

### Methods

- #[]
- #[]=
- #clear
- #context
- #delete
- #inherit

### Files

- History.txt
- README.rdoc

### Class/Module Index

Quicksearch

- Logging
- Logging::Appender
- Logging::Appenders
- Logging::Appenders::Buffering
- Logging::Appenders::Email
- Logging::Appenders::File
- Logging::Appenders::Growl
- Logging::Appenders::IO
- Logging::Appenders::RollingFile
- Logging::Appenders::Stderr
- Logging::Appenders::Stdout
- Logging::Appenders::StringIo
- Logging::Appenders::Syslog
- Logging::ColorScheme
- Logging::Config
- Logging::Config::Configurator
- Logging::Config::Configurator::DSL
- Logging::Config::Configurator::Error
- Logging::Config::Configurator::TopLevelDSL
- Logging::Config::YamlConfigurator
- Logging::Config::YamlConfigurator::Error
- Logging::Layout
- Logging::Layouts
- Logging::Layouts::Basic
- Logging::Layouts::Parseable
- Logging::Layouts::Pattern
- Logging::Logger
- Logging::MappedDiagnosticContext
- Logging::NestedDiagnosticContext
- Logging::Proxy
- Logging::RailsCompat
- Logging::Repository
- Logging::Repository::Singleton
- Logging::RootLogger
- Logging::Stats
- Logging::Stats::Sampler
- Logging::Stats::Tracker
- RSpec
- RSpec::Core
- RSpec::Core::Configuration
- RSpec::LoggingHelper
- RSpec::LoggingHelper
- Spec
- Spec::Runner
- Spec::Runner::Configuration
- Object
- Object::LoggingHelper
- File
- FileUtils
- Hash
- Kernel
- Module
- ReentrantMutex
- String

No matching classes.

# Logging::MappedDiagnosticContext

A Mapped Diagnostic Context, or MDC in short, is an instrument used to distinguish interleaved log output from different sources. Log output is typically interleaved when a server handles multiple clients near-simultaneously.

Interleaved log output can still be meaningful if each log entry from different contexts had a distinctive stamp. This is where MDCs come into play.

The MDC provides a hash of contextual messages that are identified by unique keys. These unique keys are set by the application and appended to log messages to identify groups of log events. One use of the Mapped Diagnostic Context is to store HTTP request headers associated with a Rack request. These headers can be included with all log messages emitted while generating the HTTP response.

When configured to do so, PatternLayout instances will automatically retrieve the mapped diagnostic context for the current thread with out any user intervention. This context information can be used to track user sessions in a Rails application, for example.

Note that MDCs are managed on a per thread basis. MDC operations such as `[]`, `[]=`, and `clear` affect the MDC of the current thread only. MDCs of other threads remain unaffected.

By default, when a new thread is created it will inherit the context of its parent thread. However, the `inherit` method may be used to inherit context for any other thread in the application.

### Constants

NAME

  The name used to retrieve the MDC from thread-local storage.

### Public Instance Methods

[]( key ) click to toggle source

Public: Get the context value identified with the key parameter.

key - The String identifier for the context.

Returns the value associated with the key or nil if there is no value present.

    # File lib/logging/diagnostic_context.rb, line 58
    def []( key )
      context.fetch(key.to_s, nil)
    end

[]=( key, value ) click to toggle source

Public: Put a context value as identified with the key parameter into the current thread's context map.

key - The String identifier for the context. value - The String value to store.

Returns the value.

    # File lib/logging/diagnostic_context.rb, line 47
    def []=( key, value )
      context.store(key.to_s, value)
    end

clear() click to toggle source

Public: Clear all mapped diagnostic information if any. This method is useful in cases where the same thread can be potentially used over and over in different unrelated contexts.

Returns the MappedDiagnosticContext.

    # File lib/logging/diagnostic_context.rb, line 79
    def clear
      context.clear if Thread.current[NAME]
      self
    end

context() click to toggle source

Returns the Hash acting as the storage for this NestedDiagnosticContext. A new storage Hash is created for each Thread running in the application.

    # File lib/logging/diagnostic_context.rb, line 110
    def context
      Thread.current[NAME] ||= Hash.new
    end

delete( key ) click to toggle source

Public: Remove the context value identified with the key parameter.

key - The String identifier for the context.

Returns the value associated with the key or nil if there is no value present.

    # File lib/logging/diagnostic_context.rb, line 69
    def delete( key )
      context.delete(key.to_s)
    end

inherit( obj ) click to toggle source

Public: Inherit the diagnostic context of another thread. In the vast majority of cases the other thread will the parent that spawned the current thread. The diagnostic context from the parent thread is cloned before being inherited; the two diagnostic contexts can be changed independently.

Returns the MappedDiagnosticContext.

    # File lib/logging/diagnostic_context.rb, line 92
    def inherit( obj )
      case obj
      when Hash
        Thread.current[NAME] = obj.dup
      when Thread
        return if Thread.current == obj
        Thread.exclusive {
          Thread.current[NAME] = obj[NAME].dup if obj[NAME]
        }
      end

      self
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.