Source code for sim_platform.diagnostics
"""Diagnostic logging for the platform process.
Every module logs through ``logging.getLogger(__name__)``, so all records sit under the
``sim_platform`` logger. As a library the package installs only a ``NullHandler``: nothing
is printed unless the application configures logging. The CLI and Desktop call
``configure_logging()``; Python users can call it too or attach their own handlers.
Logged records are diagnostics for maintainers (handled failures with their traceback,
lifecycle problems). They are not the experiment record: orders, fills and Agent activity
stay in the database and operation logs. Records never include credentials.
"""
from __future__ import annotations
import json
import logging
import os
import sys
from typing import Optional, TextIO
ROOT_LOGGER = 'sim_platform'
LEVEL_ENVIRONMENT = 'MARKET_LAB_LOG_LEVEL'
FORMAT_ENVIRONMENT = 'MARKET_LAB_LOG_FORMAT'
LEVELS = ('debug', 'info', 'warning', 'error', 'critical')
class _PlatformHandler(logging.StreamHandler): # type: ignore[type-arg]
"""The handler configure_logging() owns, so a second call can replace it."""
[docs]
class JsonFormatter(logging.Formatter):
"""Format one record per line as a JSON object for log collectors."""
[docs]
def format(self, record: logging.LogRecord) -> str:
entry = {
'time': self.formatTime(record, '%Y-%m-%dT%H:%M:%S%z'),
'level': record.levelname.lower(),
'logger': record.name,
'message': record.getMessage(),
'thread': record.threadName,
}
if record.exc_info:
entry['exception'] = self.formatException(record.exc_info)
return json.dumps(entry, ensure_ascii=False)
[docs]
def configure_logging(
level: Optional[str] = None,
*,
json_format: Optional[bool] = None,
stream: Optional[TextIO] = None,
) -> logging.Logger:
"""Send platform diagnostics to ``stream`` (standard error by default).
Args:
level: One of ``LEVELS``. None reads ``MARKET_LAB_LOG_LEVEL``, else ``warning``.
json_format: One JSON object per line when True. None reads
``MARKET_LAB_LOG_FORMAT`` (``json`` or ``text``), else text.
stream: Destination; standard error when omitted.
Returns:
The ``sim_platform`` logger. Calling again replaces the handler it added before.
Raises:
ValueError: If the level or format name is not recognised.
"""
name = (level or os.environ.get(LEVEL_ENVIRONMENT) or 'warning').lower()
if name not in LEVELS:
raise ValueError('log level must be one of: ' + ', '.join(LEVELS))
if json_format is None:
style = os.environ.get(FORMAT_ENVIRONMENT, 'text').lower()
if style not in ('json', 'text'):
raise ValueError('log format must be json or text')
json_format = style == 'json'
logger = logging.getLogger(ROOT_LOGGER)
for handler in list(logger.handlers):
if isinstance(handler, _PlatformHandler):
logger.removeHandler(handler)
handler = _PlatformHandler(stream or sys.stderr)
handler.setFormatter(
JsonFormatter()
if json_format
else logging.Formatter('%(asctime)s %(levelname)s %(name)s: %(message)s')
)
logger.addHandler(handler)
logger.setLevel(name.upper())
return logger