MDC (Mapped Diagnostic Context)

1.2.1 verified Mon Apr 27 auth: no python

A Python implementation of Mapped Diagnostic Context (MDC) for structured logging. MDC allows you to enrich log records with contextual key-value pairs, propagate context across threads and async code, and format logs as JSON. Current version 1.2.1, released on PyPI, with irregular releases.

pip install mdc

Common errors

error ImportError: cannot import name 'MDCFormatter' from 'mdc' ↓

cause You are using an older version of mdc that doesn't include MDCFormatter.

fix

Install the latest version: pip install --upgrade mdc

error TypeError: 'int' object is not iterable ↓

cause MDC expects values to be strings or objects convertible to string. Passing non-string values may cause formatting errors.

fix

Convert values to strings before passing to MDC: MDC(user_id=str(1234))

error AttributeError: module 'mdc' has no attribute 'MDC' ↓

cause Possibly installed a different package named mdc, or very old version.

fix

Run pip install --upgrade mdc. If problem persists, check your environment for conflicting mdc installations.

Warnings

breaking In version 1.2.0, the MDC context was changed to support generators and argument catching. If you used MDC in older versions, ensure you are using the latest API. ↓

fix Upgrade to >=1.2.0 and review your usage of MDC as a decorator or context manager.

gotcha MDC context does NOT automatically propagate to child threads or async tasks unless you explicitly pass the context. Use MDC.copy() or MDC.get_context() to pass it manually. ↓

fix When spawning threads or tasks, manually copy the MDC context: context = MDC.get_context(); # pass to thread/task

deprecated MDCHandler is a legacy class kept for backward compatibility but may be removed in future versions. Use MDCFormatter with a standard logging Handler instead. ↓

fix Use from mdc import MDC, MDCFormatter and configure logging with MDCFormatter on any Handler.

gotcha When using MDC as a decorator on generator functions, context is lost after the first yield. Version 1.2.1 fixed this bug, but older versions (<1.2.1) had this issue. ↓

fix Upgrade to 1.2.1 or later to preserve context throughout generator execution.

Imports

MDC
```
from mdc import MDC
```
MDCFormatter
```
from mdc import MDCFormatter
```
MDCHandler
```
from mdc import MDCHandler
```
Legacy class kept for compatibility

Quickstart

Basic usage: use MDC as a context manager to add key-value pairs to log records.

from mdc import MDC
import logging

# Set up logging
handler = logging.StreamHandler()
handler.setFormatter(MDCFormatter())
logging.getLogger().addHandler(handler)
logging.getLogger().setLevel(logging.INFO)

# Use MDC context
with MDC(user_id='1234', ip='127.0.0.1'):
    logging.info('Processing request')  # Output includes MDC fields