Logging Integration

Relevant source files

• docs/source/logging.rst
• docs/source/traceback.rst
• rich/_log_render.py
• rich/logging.py
• tests/test_log.py
• tests/test_logging.py

RichHandler integrates Rich's rendering pipeline with Python's standard logging module. Log output is formatted as a structured table with color-coded levels, syntax-highlighted messages, optional clickable source paths, and optionally Rich-formatted tracebacks. For Rich's standalone traceback system, see page 6.2.

Overview

RichHandler (in rich/logging.py) subclasses logging.Handler and delegates layout to LogRender (in rich/_log_render.py). The rendered output is a Table grid printed to a Console instance.

Component relationships:

Sources: rich/logging.py1-18 rich/_log_render.py1-12

Basic Usage

Pass a RichHandler instance to logging.basicConfig():

By default, the handler uses the global Console instance (via get_console()). You can supply your own Console to control output destination, width, and color system.

Sources: rich/logging.py242-296 docs/source/logging.rst1-18 rich/logging.py92

Message Flow and Rendering

emit() call sequence:

Sources: rich/logging.py132-180 rich/_log_render.py32-86

RichHandler Constructor Parameters

RichHandler.__init__() accepts the following parameters:

Display Columns

Parameter	Type	Default	Description
show_time	bool	True	Render a time column
omit_repeated_times	bool	True	Blank time cell when it repeats the previous row's time
show_level	bool	True	Render a level column
show_path	bool	True	Render a source file/line column
enable_link_path	bool	True	Make the path a clickable file:// terminal hyperlink
log_time_format	str or FormatTimeCallable	"[%x %X]"	strftime format string, or a callable (datetime) -> Text

Message Styling

Parameter	Type	Default	Description
markup	bool	False	Parse Rich console markup in log messages
highlighter	Highlighter or None	None (uses ReprHighlighter)	Highlighter applied to message text
keywords	List[str] or None	None (uses KEYWORDS)	Words highlighted with the logging.keyword style

Rich Tracebacks

Parameter	Type	Default	Description
rich_tracebacks	bool	False	Use Traceback.from_exception() for exception rendering
tracebacks_width	int or None	None	Traceback render width; None = full console width
tracebacks_code_width	int or None	88	Max width of code in traceback panels
tracebacks_extra_lines	int	3	Extra context lines shown around the error line
tracebacks_theme	str or None	None	Pygments theme override for syntax-highlighted code
tracebacks_word_wrap	bool	True	Word-wrap long traceback lines
tracebacks_show_locals	bool	False	Show local variable values per frame
tracebacks_suppress	Iterable[str or ModuleType]	()	Modules or path strings to suppress from tracebacks
tracebacks_max_frames	int	100	Maximum frames to render (see below)
locals_max_length	int	10	Max container items before abbreviating in locals display
locals_max_string	int	80	Max string length before truncating in locals display

Other

Parameter	Type	Default	Description
console	Console or None	None	Target console; defaults to the global console from get_console()
level	int or str	logging.NOTSET	Minimum log level to handle

Sources: rich/logging.py65-115

LogRender Table Structure

LogRender (in rich/_log_render.py) is instantiated by RichHandler.__init__() and stored as self._log_render. When called, it produces a Table.grid() with up to four columns:

Column	Style key	Condition	Content
Time	log.time	show_time=True	Formatted datetime; blanked when repeated if omit_repeated_times=True
Level	log.level	show_level=True	Level name, left-justified to 8 chars, styled logging.level.<name>
Message	log.message	Always	Renderables wrapping the message Text and optional Traceback
Path	log.path	show_path=True and path not empty	Filename + :lineno; optionally a file:// hyperlink

The time format can be a strftime string or a FormatTimeCallable (Callable[[datetime], Text]). The level_width is set to None by RichHandler (letting the column size naturally), while Console.log() uses 8.

Sources: rich/_log_render.py14-86 rich/logging.py94-101

Advanced Features

Rich Tracebacks

When rich_tracebacks=True, emit() calls Traceback.from_exception() instead of relying on the standard formatter's exception rendering. The resulting Traceback renderable is appended to the message column alongside the log message text.

When rich_tracebacks=True and a formatter is attached, emit() manually re-runs formatter.formatMessage(record) (stripping the exception) so that the traceback is not also embedded in the formatted string. See rich/logging.py134-166

Markup and Highlighting

markup=False by default to avoid misinterpreting square brackets in third-party log messages. Enable it in two scopes:

• Handler-wide: RichHandler(markup=True)
• Per-message: log.error("[bold red]Alert![/]", extra={"markup": True})

The render_message() method checks getattr(record, "markup", self.markup) so the extra dict value takes precedence over the handler default. See rich/logging.py192-193

The highlighter (default: ReprHighlighter) is similarly overridable per-record:

• log.error("raw text", extra={"highlighter": None}) — disables highlighting for that message.

The HIGHLIGHTER_CLASS class variable (ReprHighlighter) controls the default. Override it on a subclass to change the default globally.

See rich/logging.py53-63 rich/logging.py192-205 docs/source/logging.rst19-26

Keywords

RichHandler.KEYWORDS is a class-level list of strings highlighted with the logging.keyword style:

["GET", "POST", "HEAD", "PUT", "DELETE", "OPTIONS", "TRACE", "PATCH"]

Pass keywords=[...] to the constructor to replace this list for a specific handler instance, or set keywords=[] to disable keyword highlighting entirely. See rich/logging.py53-62 rich/logging.py199-203

Suppressing Framework Frames in Tracebacks

tracebacks_suppress accepts a list of modules or path strings. Frames originating in those modules are shown as a single collapsed line (file + line number only, no code context).

This is passed directly to Traceback.from_exception(suppress=...). See rich/logging.py156 docs/source/logging.rst53-71

Limiting Traceback Depth

tracebacks_max_frames (default 100) caps the number of frames rendered. When the traceback exceeds this limit, only the first 50 and last 50 frames are shown. Set to 0 to disable the cap. This mirrors the same parameter on Traceback directly. See rich/logging.py85 docs/source/traceback.rst74-77

Internal Architecture

Key attributes set by RichHandler.__init__():

Attribute	Type	Set from
self.console	Console	console param or get_console()
self.highlighter	Highlighter	highlighter param or HIGHLIGHTER_CLASS()
self._log_render	LogRender	Always created internally
self.markup	bool	markup param
self.rich_tracebacks	bool	rich_tracebacks param
self.keywords	List[str] or None	keywords param
self.enable_link_path	bool	enable_link_path param

Key methods:

Method	Signature	Role
emit()	(record: LogRecord) -> None	Entry point called by the logging framework; orchestrates all rendering
render_message()	(record, message) -> ConsoleRenderable	Converts the string message to a Text object with highlighting applied
render()	(*, record, traceback, message_renderable) -> ConsoleRenderable	Delegates to _log_render to produce the final Table
get_level_text()	(record: LogRecord) -> Text	Returns level name styled with logging.level.<name>

Sources: rich/logging.py17-116 rich/logging.py117-239 rich/_log_render.py14-86

Implementation Details

The RichHandler class provides custom rendering for log records:

• The emit() method processes the log record and handles exceptions
• The render_message() method applies styling and highlighting to the message
• The render() method creates the final layout with all components
• The get_level_text() method formats the log level with appropriate styling

The LogRender class creates a table grid with columns for different log components and handles the actual layout of the log entry.

Sources: rich/logging.py117-239 rich/_log_render.py14-86

Testing and Compatibility

Rich's logging system is designed to work with Python's standard logging module and is compatible with existing logging configurations. The handler includes special handling for edge cases such as:

• Windows terminal compatibility
• Handling of None stdout/stderr when using pythonw
• Proper integration with logging formatters

Tests validate the correct rendering of log messages, exception handling, and styling.

Sources: tests/test_logging.py1-169 tests/test_log.py1-66 rich/logging.py171-180