mozlog

library8.1.0pypypi✓ verified 90d ago

mozlog is a Python library from Mozilla designed for robust, structured logging, particularly within test harnesses and the broader Mozilla ecosystem. It outputs a stream of JSON-compatible objects, making it distinct from the standard `logging` module. As of version 8.1.0, it remains actively maintained with regular updates.

observability

pip install mozlog

package ↗homepage ↗

INSTALL

IMPORT

SIG · MOZLOG

mozlog

observabilitypythonv8.1.0

Install

2.4s avg

Import

228ms

Disk

24MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v8.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.237s · 28.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.4s · import 0.219s · 29MB

24MB installed

● package 24MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

StructuredLogger

✓ from mozlog.structuredlog import StructuredLogger

The core logger class for emitting structured logs.

setup_logging

✓ from mozlog.commandline import setup_logging

Convenience function for initializing a logger, often with command-line arguments.

ProxyLogger

✓ from mozlog.proxy import ProxyLogger

A logger that forwards calls to a default logger instance, requiring prior initialization.

This example demonstrates how to set up `mozlog` using `setup_logging` and emit various types of structured log messages. The `setup_logging` function provides a convenient way to initialize the logger with default handlers and formatters, often sending JSON output to stdout.

from mozlog.commandline import setup_logging from mozlog.structuredlog import StructuredLogger import sys # Setup logging, directing output to stdout # This initializes the default logger that ProxyLogger would use, # and adds handlers/formatters based on default commandline args. # For a simple script, you might pass minimal args or defaults. # setup_logging returns a StructuredLogger instance. logger = setup_logging() # Emit a simple info message logger.info('application_start', data={'version': '1.0.0', 'environment': 'dev'}) # Emit a testsuite start message (common in Mozilla's use case) logger.testsuite_start('my_test_suite', tests=[{'id': 'test1.html'}, {'id': 'test2.js'}] ) # Emit a log message with a specific action logger.log(action='my_custom_event', message='Something happened', details={'key': 'value'}) print("\n--- Raw JSON output on stdout (if default formatter used) ---")

Debug

Known issues

gotchamozlog is NOT based on Python's standard `logging` module. It uses its own API and internal data model, which can be a common source of confusion for developers expecting `logging` module compatibility.

fix

Familiarize yourself with the `mozlog` API and its structured JSON message format, rather than assuming `stdlib` `logging` patterns.

affects: All versions

gotchamozlog is NOT process-safe for applications using multiple processes (e.g., via `multiprocessing`). All logging should be arranged to happen in a single process to avoid issues.

fix

Design your multi-process application to centralize all `mozlog` calls within a single, dedicated logging process or thread, passing messages to it via inter-process communication.

affects: All versions

gotchaUsing `mozlog.proxy.ProxyLogger` without prior initialization of a default logger (e.g., via `mozlog.commandline.setup_logging()`) will raise a `RuntimeError`.

fix

Ensure `mozlog.commandline.setup_logging()` or `mozlog.structuredlog.set_default_logger()` is called at application startup before any `ProxyLogger` instances are used.

affects: All versions

gotchaLoggers with the same name in `mozlog` share the same internal state (a 'Borg' pattern). Typically, only one logger object should be instantiated per program.

fix

When using `mozlog`, generally create only one `StructuredLogger` instance or rely on the default logger set by `setup_logging` to avoid unexpected state sharing or configuration conflicts.

affects: All versions

gotchaSeverity levels used by `mozlog` might not directly map to those used by external logging systems like Google Cloud Logging (GCL), potentially causing incorrect rendering of log records in cloud platforms.

fix

When integrating with cloud logging services, verify the mapping of `mozlog`'s severity actions to the external system's levels. Custom remapping or a wrapper might be necessary.

affects: All versions

Errors

Common errors & fixes

RuntimeError: Default logger not initialized

This error occurs when a `ProxyLogger` is instantiated or attempts to log before a default `StructuredLogger` has been set up using `mozlog.commandline.setup_logging()` or `mozlog.structuredlog.set_default_logger()`.

fix

Call `mozlog.commandline.setup_logging()` early in your application's lifecycle to ensure the default logger is properly initialized. For example: `logger = setup_logging()`.

My MOZ_LOG environment variable isn't affecting my mozlog output.

The `MOZ_LOG` environment variable is primarily used for configuring *internal Firefox* logging and is not related to the Python `mozlog` library.

fix

To configure the Python `mozlog` library, use its dedicated API (e.g., `setup_logging` parameters, `StructuredLogger` methods) or adjust the handlers/formatters programmatically. The `MOZ_LOG` environment variable has no effect on this Python library.

TypeError: 'StructuredLogger' object has no attribute 'addHandler'

Developers accustomed to Python's `stdlib` `logging` module often try to use `addHandler` or other standard `logging` methods. `mozlog` has a different API and does not provide these methods.

fix

Review the `mozlog` documentation for its specific methods for adding handlers (`mozlog.commandline.setup_handlers`) and configuring output, which are distinct from the `stdlib` `logging` module. You interact with `mozlog` by calling specific action methods like `info`, `warning`, `test_start`, etc., which accept structured data.

Upgrade

Version history

8.1.0latest on PyPI · released Mar 23, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/mozlog/ ↗

homepagehttps://wiki.mozilla.org/Auto-tools/Projects/Mozbase ↗