mozlog

Common errors

• RuntimeError: Default logger not initialized

  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()`.
  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.

  cause 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'

  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.
  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.

Warnings

• gotcha 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.
  Fix: Familiarize yourself with the `mozlog` API and its structured JSON message format, rather than assuming `stdlib` `logging` patterns.
• gotcha 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.
  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.
• gotcha Using `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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install mozlog Install latest version

Imports

• 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.

Quickstart

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) ---")