How are MDC.pushByKey() and related methods supposed to work?

[dglynch]

There are three related methods in the MDC class:

• pushByKey()
• popByKey()
• getCopyOfDequeByKey()

Similarly, there are four related methods in the MDCAdapter interface:

• pushByKey()
• popByKey()
• getCopyOfDequeByKey()
• clearDequeByKey()

I say these methods are "related" because, in all the implementations of the MDCAdapter interface I can find, these four methods have zero coupling with the other methods of the class. Pushing or popping does not call put() or remove(), or otherwise affect the contents of the threadlocal map field(s), nor the return value of get(). Instead, these three or four methods just interact with their own dedicated field. Crucially, calling them has no impact on logging.

Specifically, these are the implementations which have this design:

• org.slf4j.helpers.BasicMDCAdapter
• org.slf4j.reload4j.Reload4jMDCAdapter
• ch.qos.logback.classic.util.LogbackMDCAdapter
• ch.qos.logback.classic.util.LogbackMDCAdapterSimple

There are some method header JavaDoc comments in the MDC class, but they don't really explain how these methods are supposed to be used, nor why they are even part of this class.

Since these methods don't interact with put() or get(), it seems like the caller is supposed to do that itself. Is that correct? For example, is the caller always supposed to do something like this?

try {
  MDC.pushByKey("foo", MDC.get("foo"));
  MDC.put("foo", "bar");
  // business code
} finally {
  MDC.put("foo", MDC.popByKey("foo"));
}

If this is the expected way to use these methods, why does the following alternative code appear as an example in issue #461? Doesn't this code do nothing at all?

try {
  MDC.pushByKey("foo", "bar");
  // business code
} finally {
  MDC.popByKey("foo");
}

[ceki]

@dglynch Hi Dan,

The methods pushByKey(), popByKey(), and getCopyOfDequeByKey() operate on values of type Deque<String>, allowing multiple values to be associated with a single MDC key (typically used to maintain a stack of values, e.g., for nested diagnostic contexts).

In contrast, the standard get(), put(), and remove() methods work with plain String values and support only a single value per key.

Although the SLF4J MDCAdapter interface defines these deque-based operations (and SLF4J implementations do support them at the adapter level), logging back-ends — in particular Logback — do not propagate or preserve the Deque<String> structure in the actual logging events.

In short, nested diagnostic contexts are part of the SLF4J MDC API, but back-ends tend to ignore it in practice.

[ppkarwasz]

The SLF4J-to-Log4j API bridge maps SLF4J’s deque-based MDC operations to the Log4j API ThreadContext (Log4j API equivalent of MDC/NDC). Concretely:

• MDC.pushByKey(null, "bar") pushes "bar" onto the NDC stack.
• MDC.popByKey(null, "bar") pops the top element from the NDC stack.
• MDC.pushByKey("foo", "bar") updates the "foo" key in the thread context to the top value of the corresponding deque (in this case "bar").
• MDC.popByKey("foo") does the inverse operation and restore the previous value of the "foo" key in the thread context.

Because of this mapping, log4j-slf4j2-impl treats the key namespace as shared between deque-based and traditional MDC operations. As a result, log4j-slf4j2-impl considers calling both MDC.pushByKey("foo", "bar") and MDC.put("foo", "bar") is invalid and will trigger a warning.

Personally, I find the design of the deque API safer: the API is essentially write-only from the application’s perspective, preventing it from being misused as a general-purpose storage mechanism. Only the logging implementation can read the deque values, keeping them strictly confined to logging concerns.