{"id":7431,"library":"mozlog","title":"mozlog","description":"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.","status":"active","version":"8.1.0","language":"en","source_language":"en","source_url":"https://firefox-source-docs.mozilla.org/mozlog/index.html","tags":["logging","structured-logging","mozilla","testing","json-logging"],"install":[{"cmd":"pip install mozlog","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The core logger class for emitting structured logs.","symbol":"StructuredLogger","correct":"from mozlog.structuredlog import StructuredLogger"},{"note":"Convenience function for initializing a logger, often with command-line arguments.","symbol":"setup_logging","correct":"from mozlog.commandline import setup_logging"},{"note":"A logger that forwards calls to a default logger instance, requiring prior initialization.","symbol":"ProxyLogger","correct":"from mozlog.proxy import ProxyLogger"}],"quickstart":{"code":"from mozlog.commandline import setup_logging\nfrom mozlog.structuredlog import StructuredLogger\nimport sys\n\n# Setup logging, directing output to stdout\n# This initializes the default logger that ProxyLogger would use,\n# and adds handlers/formatters based on default commandline args.\n# For a simple script, you might pass minimal args or defaults.\n# setup_logging returns a StructuredLogger instance.\nlogger = setup_logging()\n\n# Emit a simple info message\nlogger.info('application_start', data={'version': '1.0.0', 'environment': 'dev'})\n\n# Emit a testsuite start message (common in Mozilla's use case)\nlogger.testsuite_start('my_test_suite', tests=[{'id': 'test1.html'}, {'id': 'test2.js'}]\n)\n\n# Emit a log message with a specific action\nlogger.log(action='my_custom_event', message='Something happened', details={'key': 'value'})\n\nprint(\"\\n--- Raw JSON output on stdout (if default formatter used) ---\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Familiarize yourself with the `mozlog` API and its structured JSON message format, rather than assuming `stdlib` `logging` patterns.","message":"mozlog 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"mozlog 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `mozlog.commandline.setup_logging()` or `mozlog.structuredlog.set_default_logger()` is called at application startup before any `ProxyLogger` instances are used.","message":"Using `mozlog.proxy.ProxyLogger` without prior initialization of a default logger (e.g., via `mozlog.commandline.setup_logging()`) will raise a `RuntimeError`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Loggers with the same name in `mozlog` share the same internal state (a 'Borg' pattern). Typically, only one logger object should be instantiated per program.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Severity 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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()`.","cause":"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()`.","error":"RuntimeError: Default logger not initialized"},{"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.","cause":"The `MOZ_LOG` environment variable is primarily used for configuring *internal Firefox* logging and is not related to the Python `mozlog` library.","error":"My MOZ_LOG environment variable isn't affecting my mozlog output."},{"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.","cause":"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.","error":"TypeError: 'StructuredLogger' object has no attribute 'addHandler'"}]}