Module: Logging::NestedDiagnosticContext

### Home Classes Methods

### In Files

- lib/logging/diagnostic_context.rb

### Methods

- #<<
- #clear
- #context
- #inherit
- #peek
- #pop
- #push

### 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::NestedDiagnosticContext

A Nested Diagnostic Context, or NDC in short, is an instrument 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 NDCs come into play.

The NDC is a stack of contextual messages that are pushed and popped by the client as different contexts are encountered in the application. When a new context is entered, the client will `push` a new message onto the NDC stack. This message appears in all log messages. When this context is exited, the client will call `pop` to remove the message.

- Contexts can be nested

- When entering a context, call `Logging.ndc.push`

- When leaving a context, call `Logging.ndc.pop`

- Configure the PatternLayout to log context information

There is no penalty for forgetting to match each push operation with a corresponding pop, except the obvious mismatch between the real application context and the context set in the NDC.

When configured to do so, PatternLayout instance will automatically retrieve the nested 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 NDCs are managed on a per thread basis. NDC operations such as `push`, `pop`, and `clear` affect the NDC of the current thread only. NDCs 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 NDC from thread-local storage.

### Public Instance Methods

<<( message ) click to toggle source
Alias for: push
clear() click to toggle source

Public: Clear all nested 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 NestedDiagnosticContext.

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

context() click to toggle source

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

    # File lib/logging/diagnostic_context.rb, line 232
    def context
      Thread.current[NAME] ||= Array.new
    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 NestedDiagnosticContext.

    # File lib/logging/diagnostic_context.rb, line 214
    def inherit( obj )
      case obj
      when Array
        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

peek() click to toggle source

Public: Looks at the last diagnostic context at the top of this NDC without removing it. The returned value is the last pushed message. If no context is available then `nil` is returned.

Returns the last pushed diagnostic message String or nil if no messages exist.

    # File lib/logging/diagnostic_context.rb, line 191
    def peek
      context.last
    end

pop() click to toggle source

Public: Clients should call this method before leaving a diagnostic context. The returned value is the last pushed message. If no context is available then `nil` is returned.

Returns the last pushed diagnostic message String or nil if no messages exist.

    # File lib/logging/diagnostic_context.rb, line 180
    def pop
      context.pop
    end

push( message ) click to toggle source

Public: Push new diagnostic context information for the current thread. The contents of the message parameter is determined solely by the client.

message - The message String to add to the current context.

Returns the current NestedDiagnosticContext.

    # File lib/logging/diagnostic_context.rb, line 167
    def push( message )
      context.push(message)
      self
    end

Also aliased as: <<

[Validate]

Generated with the Darkfish Rdoc Generator 2.