From 5b222b3d75335b77d2a02160744ce0ddfd00bf16 Mon Sep 17 00:00:00 2001 From: Don Bowman Date: Mon, 2 Nov 2026 08:41:00 -0500 Subject: [PATCH 1/5] fix: emit unhandled exceptions as a single JSON record logging.basicConfig() installs a root handler whose formatter is an explicit logging.Formatter, so logging._defaultFormatter never applies to it, and the formatter sweep in init_*() skipped the root logger because Logger.manager.loggerDict does not contain it. Records that propagate to root, which is where Flask and connexion report unhandled exceptions, therefore stayed plain multi-line text with no level and no single exc_info field, so level-based search and alerting could not see them. Sweep the root logger together with the named loggers, and convert the handler Flask may attach to the app logger (flask.logging.default_handler) plus any handler the application already added, without reading app.logger: that property attaches Flask's handler and would duplicate the output of applications that add their own handler after initialisation. tests/test_error_handling.py covers the non-web case and the Flask and connexion paths, with and without a root handler. --- json_logging/__init__.py | 3 +- json_logging/framework/connexion/__init__.py | 7 + json_logging/framework/flask/__init__.py | 10 + json_logging/util.py | 15 ++ tests/test_error_handling.py | 190 +++++++++++++++++++ 5 files changed, 223 insertions(+), 2 deletions(-) create mode 100644 tests/test_error_handling.py diff --git a/json_logging/__init__.py b/json_logging/__init__.py index add1870..e666e8d 100644 --- a/json_logging/__init__.py +++ b/json_logging/__init__.py @@ -140,8 +140,7 @@ def __init(framework_name=None, custom_formatter=None, enable_json=False): ENABLE_JSON_LOGGING and _logger.debug("Update all existing logger to using JSONLogFormatter") - existing_loggers = list(map(logging.getLogger, logging.Logger.manager.loggerDict)) - util.update_formatter_for_loggers(existing_loggers, _default_formatter) + util.update_formatter_for_all_loggers(_default_formatter) def init_request_instrument(app=None, custom_formatter=None, exclude_url_patterns=[], diff --git a/json_logging/framework/connexion/__init__.py b/json_logging/framework/connexion/__init__.py index 10ba189..7229196 100644 --- a/json_logging/framework/connexion/__init__.py +++ b/json_logging/framework/connexion/__init__.py @@ -51,6 +51,13 @@ def config(self, app, request_response_dto_class, exclude_url_patterns=[]): json_logging.util.update_formatter_for_loggers([logging.getLogger('werkzeug')], JSONLogWebFormatter) + # Connexion wraps a Flask app: unhandled exceptions are reported through its app logger. Flask may attach + # flask.logging.default_handler to it on first use, so convert that handler and any handler the application + # already added, without reading app.app.logger (which would attach Flask's handler and duplicate the output). + from flask.logging import default_handler + default_handler.setFormatter(JSONLogWebFormatter()) + json_logging.util.update_formatter_for_loggers([logging.getLogger(app.app.name)], JSONLogWebFormatter) + # noinspection PyAttributeOutsideInit self.request_logger = logging.getLogger('connexion-request-logger') diff --git a/json_logging/framework/flask/__init__.py b/json_logging/framework/flask/__init__.py index 9278bc4..039d186 100644 --- a/json_logging/framework/flask/__init__.py +++ b/json_logging/framework/flask/__init__.py @@ -42,6 +42,16 @@ def config(self, app, request_response_dto_class, exclude_url_patterns=[]): json_logging.util.update_formatter_for_loggers([logging.getLogger('werkzeug')], json_logging.formatters.JSONLogWebFormatter) + # Flask reports unhandled exceptions through app.logger. When no handler covers its level, Flask attaches + # flask.logging.default_handler on first use, and that handler's plain text formatter splits a traceback over + # many lines. Convert the handler Flask may attach, plus any handler the application already added to the app + # logger. Reading app.logger here is not an option: the property attaches Flask's handler and duplicates the + # output of applications that add their own handler after initialisation. + from flask.logging import default_handler + default_handler.setFormatter(json_logging.formatters.JSONLogWebFormatter()) + json_logging.util.update_formatter_for_loggers([logging.getLogger(app.name)], + json_logging.formatters.JSONLogWebFormatter) + # noinspection PyAttributeOutsideInit self.request_logger = logging.getLogger('flask-request-logger') diff --git a/json_logging/util.py b/json_logging/util.py index 062bde8..130d5ea 100644 --- a/json_logging/util.py +++ b/json_logging/util.py @@ -48,6 +48,21 @@ def update_formatter_for_loggers(loggers_iter, formatter): handler.formatter = formatter() +def update_formatter_for_all_loggers(formatter): + """Apply *formatter* to the root logger and to every logger that exists right now. + + The root logger is not part of ``logging.Logger.manager.loggerDict``, so it has to be added + explicitly. A handler installed by ``logging.basicConfig()`` carries an explicit + ``logging.Formatter`` and is therefore not affected by ``logging._defaultFormatter``; without + this, records propagated to root (for example Flask's unhandled exception log) stay plain text. + + :param formatter: formatter class to apply + """ + # Materialise the names first: logging.getLogger() replaces placeholders in loggerDict while we iterate. + logger_names = list(logging.Logger.manager.loggerDict) + update_formatter_for_loggers([logging.root] + [logging.getLogger(name) for name in logger_names], formatter) + + # noinspection PyPep8 def parse_int(input_int, default): # noinspection PyBroadException diff --git a/tests/test_error_handling.py b/tests/test_error_handling.py new file mode 100644 index 0000000..08cdfe9 --- /dev/null +++ b/tests/test_error_handling.py @@ -0,0 +1,190 @@ +"""Error-path formatting: an exception must reach the log as one JSON record. + +Regression coverage for the 2026-11-02 API incident: unhandled exceptions reported by the +Flask/connexion app logger were emitted as plain multi-line text, so they never carried a +``level`` or a single ``exc_info`` field and could not be alerted on. + +The toolchain was running ``logging.basicConfig()`` before ``json_logging.init_*()``. That call +installs a root handler whose formatter is an explicit ``logging.Formatter`` (default format +``%(levelname)s:%(name)s:%(message)s``); the handler is therefore not covered by +``logging._defaultFormatter`` and, before the fix, the root logger was not part of the formatter +sweep either. Every record propagating to root - including Flask's exception log - stayed plain. +""" +import io +import json +import logging + +import pytest + +from helpers.imports import undo_imports_from_package + +EXCEPTION_MESSAGE = "'NoneType' object is not iterable" +LOGGER_NAME = "user_db_api.app" + + +@pytest.fixture +def fresh_json_logging(): + """Import a pristine json_logging so module level init state does not leak between tests.""" + undo_imports_from_package("json_logging") + import json_logging + yield json_logging + undo_imports_from_package("json_logging") + + +@pytest.fixture(autouse=True) +def restore_process_logging(): + """Undo the process-global logging changes these tests deliberately make.""" + import flask.logging as flask_logging + + # Flask attaches its shared default_handler to the app logger; keep each test's logger clean for the next one. + touched_loggers = [LOGGER_NAME, __name__] + saved_logger_handlers = {name: logging.getLogger(name).handlers[:] for name in touched_loggers} + saved_root_handlers = logging.root.handlers[:] + saved_root_level = logging.root.level + saved_default_formatter = logging._defaultFormatter + saved_flask_default_formatter = flask_logging.default_handler.formatter + saved_flask_default_stream = flask_logging.default_handler.stream + yield + for name, handlers in saved_logger_handlers.items(): + logging.getLogger(name).handlers[:] = handlers + logging.root.handlers[:] = saved_root_handlers + logging.root.setLevel(saved_root_level) + logging._defaultFormatter = saved_default_formatter + flask_logging.default_handler.setFormatter(saved_flask_default_formatter) + flask_logging.default_handler.stream = saved_flask_default_stream + + +def raise_type_error(): + raise TypeError(EXCEPTION_MESSAGE) + + +def configure_root_logger_like_basic_config(buffer): + """Reproduce the toolchain setup: a root handler with an explicit default Formatter.""" + for handler in logging.root.handlers[:]: + logging.root.removeHandler(handler) + logging.root.setLevel(logging.INFO) + logging.basicConfig() + handler = logging.root.handlers[0] + assert type(handler.formatter) is logging.Formatter, "basicConfig() must install an explicit Formatter" + handler.stream = buffer + + +def remove_root_handlers(): + for handler in logging.root.handlers[:]: + logging.root.removeHandler(handler) + + +def error_records(text): + """The ERROR log records in *text*, ignoring plain text and request records.""" + return [ + record + for record in (json.loads(line) for line in text.splitlines() if line.startswith("{")) + if record.get("type") == "log" and record.get("level") == "ERROR" + ] + + +def assert_single_exception_record(records, message, logger_name=LOGGER_NAME): + assert len(records) == 1, [record.get("msg") for record in records] + record = records[0] + assert record["logger"] == logger_name + assert record["msg"] == message + assert "Traceback (most recent call last)" in record["exc_info"] + assert EXCEPTION_MESSAGE in record["exc_info"] + + +def test_exception_through_root_handler_configured_before_init_is_one_json_record(fresh_json_logging): + buffer = io.StringIO() + configure_root_logger_like_basic_config(buffer) + + fresh_json_logging.init_non_web(enable_json=True) + + try: + raise_type_error() + except TypeError: + logging.getLogger(LOGGER_NAME).error("Exception on /v1/user_resource_access_info [GET]", exc_info=True) + + assert_single_exception_record(error_records(buffer.getvalue()), "Exception on /v1/user_resource_access_info [GET]") + + +def test_flask_unhandled_exception_with_root_handler_is_one_json_record(fresh_json_logging): + import flask + + buffer = io.StringIO() + configure_root_logger_like_basic_config(buffer) + fresh_json_logging.init_flask(enable_json=True) + app = flask.Flask(LOGGER_NAME) + fresh_json_logging.init_request_instrument(app) + + @app.route("/boom") + def boom(): + raise_type_error() + + assert app.test_client().get("/boom").status_code == 500 + + assert_single_exception_record(error_records(buffer.getvalue()), "Exception on /boom [GET]") + + +def test_flask_app_logger_handler_added_before_instrumentation_is_one_json_record(fresh_json_logging): + import flask + + remove_root_handlers() + fresh_json_logging.init_flask(enable_json=True) + app = flask.Flask(LOGGER_NAME) + app.logger # the application used its logger before instrumentation, so Flask has attached its own handler + assert app.logger.handlers, "expected Flask to attach its own handler" + fresh_json_logging.init_request_instrument(app) + + buffer = io.StringIO() + app.logger.handlers[0].stream = buffer + + @app.route("/boom") + def boom(): + raise_type_error() + + assert app.test_client().get("/boom").status_code == 500 + + assert_single_exception_record(error_records(buffer.getvalue()), "Exception on /boom [GET]") + + +def test_flask_handler_attached_on_first_use_is_json(fresh_json_logging, capfd): + import flask + + remove_root_handlers() + fresh_json_logging.init_flask(enable_json=True) + app = flask.Flask(LOGGER_NAME) + fresh_json_logging.init_request_instrument(app) + + # json_logging must not attach a handler of its own: Flask attaches flask.logging.default_handler on first use. + assert logging.getLogger(LOGGER_NAME).handlers == [] + + @app.route("/boom") + def boom(): + raise_type_error() + + assert app.test_client().get("/boom").status_code == 500 + + assert app.logger.handlers, "expected Flask to attach its own handler on first use" + assert_single_exception_record(error_records(capfd.readouterr().err), "Exception on /boom [GET]") + + +def test_connexion_app_logger_exception_is_one_json_record(fresh_json_logging): + connexion = pytest.importorskip("connexion") + + remove_root_handlers() + fresh_json_logging.init_connexion(enable_json=True) + app = connexion.FlaskApp(__name__, specification_dir=".") + app.app.logger # the application used its logger before instrumentation + fresh_json_logging.init_request_instrument(app) + + logger = app.app.logger + assert logger.handlers, "expected Flask to attach its own handler" + buffer = io.StringIO() + logger.handlers[0].stream = buffer + + try: + raise_type_error() + except TypeError: + logger.error("Exception on /v1/user_resource_access_info [GET]", exc_info=True) + + assert_single_exception_record( + error_records(buffer.getvalue()), "Exception on /v1/user_resource_access_info [GET]", logger.name) From d11370c766a99e78e28d9e49847ee83100c16fb2 Mon Sep 17 00:00:00 2001 From: Don Bowman Date: Mon, 2 Nov 2026 08:42:59 -0500 Subject: [PATCH 2/5] fix: keep the app logger conversion opt-in and formatter aware Follow up on review findings: - Only convert the Flask/connexion app logger when JSON logging is enabled. With enable_json=False the library promises plain text, so converting it would contradict the documented behaviour. - Use the configured default formatter (custom_formatter when the application passed one) instead of a hard coded JSONLogWebFormatter, so a custom formatter is not silently replaced for the logger that reports exceptions. - Leave flask.logging.default_handler alone when it already carries the target formatter, matching update_formatter_for_loggers semantics. - Cover the JSON-disabled path with a test. - Document on config_root_logger() that init_*() already converts the root handlers present at initialisation, and that the call is for handlers attached to root afterwards. --- json_logging/__init__.py | 10 ++++++---- json_logging/framework/connexion/__init__.py | 9 ++++++--- json_logging/framework/flask/__init__.py | 10 ++++++---- tests/test_error_handling.py | 18 ++++++++++++++++++ 4 files changed, 36 insertions(+), 11 deletions(-) diff --git a/json_logging/__init__.py b/json_logging/__init__.py index e666e8d..5d4a3ed 100644 --- a/json_logging/__init__.py +++ b/json_logging/__init__.py @@ -55,10 +55,12 @@ def get_correlation_id(request=None): def config_root_logger(): """ - You must call this if you are using root logger. - Make all root logger' handlers produce JSON format - & remove duplicate handlers for request instrumentation logging. - Please made sure that you call this after you called "logging.basicConfig() or logging.getLogger() + Make all root logger handlers produce JSON format. + + init_*() already converts the root logger handlers that exist at initialisation time. Call this + when a handler with a plain text formatter is attached to the root logger afterwards, for example + by a logging.basicConfig() call made after initialisation. The handler must exist before this is + called. """ if not logging.root.handlers: diff --git a/json_logging/framework/connexion/__init__.py b/json_logging/framework/connexion/__init__.py index 7229196..21fafa7 100644 --- a/json_logging/framework/connexion/__init__.py +++ b/json_logging/framework/connexion/__init__.py @@ -54,9 +54,12 @@ def config(self, app, request_response_dto_class, exclude_url_patterns=[]): # Connexion wraps a Flask app: unhandled exceptions are reported through its app logger. Flask may attach # flask.logging.default_handler to it on first use, so convert that handler and any handler the application # already added, without reading app.app.logger (which would attach Flask's handler and duplicate the output). - from flask.logging import default_handler - default_handler.setFormatter(JSONLogWebFormatter()) - json_logging.util.update_formatter_for_loggers([logging.getLogger(app.app.name)], JSONLogWebFormatter) + if json_logging.ENABLE_JSON_LOGGING: + from flask.logging import default_handler + formatter = json_logging._default_formatter or JSONLogWebFormatter + if not isinstance(default_handler.formatter, formatter): + default_handler.setFormatter(formatter()) + json_logging.util.update_formatter_for_loggers([logging.getLogger(app.app.name)], formatter) # noinspection PyAttributeOutsideInit self.request_logger = logging.getLogger('connexion-request-logger') diff --git a/json_logging/framework/flask/__init__.py b/json_logging/framework/flask/__init__.py index 039d186..78039fb 100644 --- a/json_logging/framework/flask/__init__.py +++ b/json_logging/framework/flask/__init__.py @@ -47,10 +47,12 @@ def config(self, app, request_response_dto_class, exclude_url_patterns=[]): # many lines. Convert the handler Flask may attach, plus any handler the application already added to the app # logger. Reading app.logger here is not an option: the property attaches Flask's handler and duplicates the # output of applications that add their own handler after initialisation. - from flask.logging import default_handler - default_handler.setFormatter(json_logging.formatters.JSONLogWebFormatter()) - json_logging.util.update_formatter_for_loggers([logging.getLogger(app.name)], - json_logging.formatters.JSONLogWebFormatter) + if json_logging.ENABLE_JSON_LOGGING: + from flask.logging import default_handler + formatter = json_logging._default_formatter or json_logging.formatters.JSONLogWebFormatter + if not isinstance(default_handler.formatter, formatter): + default_handler.setFormatter(formatter()) + json_logging.util.update_formatter_for_loggers([logging.getLogger(app.name)], formatter) # noinspection PyAttributeOutsideInit self.request_logger = logging.getLogger('flask-request-logger') diff --git a/tests/test_error_handling.py b/tests/test_error_handling.py index 08cdfe9..29f95c7 100644 --- a/tests/test_error_handling.py +++ b/tests/test_error_handling.py @@ -167,6 +167,24 @@ def boom(): assert_single_exception_record(error_records(capfd.readouterr().err), "Exception on /boom [GET]") +def test_flask_app_logger_is_left_plain_when_json_logging_is_disabled(fresh_json_logging): + import flask + from flask.logging import default_handler + + remove_root_handlers() + plain_formatter = logging.Formatter("%(levelname)s in app: %(message)s") + default_handler.setFormatter(plain_formatter) + fresh_json_logging.init_flask() # enable_json defaults to False + app = flask.Flask(LOGGER_NAME) + app.logger # Flask attaches its own handler, with a plain text formatter + assert app.logger.handlers + + fresh_json_logging.init_request_instrument(app) + + assert default_handler.formatter is plain_formatter, "JSON is disabled, the formatter must not change" + assert app.logger.handlers[0].formatter is plain_formatter + + def test_connexion_app_logger_exception_is_one_json_record(fresh_json_logging): connexion = pytest.importorskip("connexion") From b004e8a45e5fd349f99f8307cf4d1a0fec023ee7 Mon Sep 17 00:00:00 2001 From: Don Bowman Date: Mon, 2 Nov 2026 09:12:47 -0500 Subject: [PATCH 3/5] fix: refresh the Flask default handler formatter and isolate the tests Review follow up: - Always construct a new formatter for flask.logging.default_handler instead of keeping an existing instance of the same class: a formatter snapshots EXCLUDED_FIELDS and the component fields when it is built, so a retained instance can carry a stale configuration. Same change for connexion. - Test isolation: snapshot and restore each handler's formatter as well as the logger handler lists, and include flask-request-logger and connexion-request-logger, which init_request_instrument() appends a handler to on every call. - Parse every captured line as JSON in the error assertion, so a JSON record followed by a plain text traceback fails instead of being filtered out. - Cover a real failing Connexion 3 request through its middleware, which is the path that actually reports the exception, in addition to the app logger case. - Docstrings for the new tests and helpers. --- json_logging/framework/connexion/__init__.py | 4 +- json_logging/framework/flask/__init__.py | 4 +- tests/test_error_handling.py | 101 +++++++++++++++---- 3 files changed, 87 insertions(+), 22 deletions(-) diff --git a/json_logging/framework/connexion/__init__.py b/json_logging/framework/connexion/__init__.py index 21fafa7..8b2c9d6 100644 --- a/json_logging/framework/connexion/__init__.py +++ b/json_logging/framework/connexion/__init__.py @@ -57,8 +57,8 @@ def config(self, app, request_response_dto_class, exclude_url_patterns=[]): if json_logging.ENABLE_JSON_LOGGING: from flask.logging import default_handler formatter = json_logging._default_formatter or JSONLogWebFormatter - if not isinstance(default_handler.formatter, formatter): - default_handler.setFormatter(formatter()) + # Always construct a new formatter: an existing instance may have captured an older EXCLUDED_FIELDS. + default_handler.setFormatter(formatter()) json_logging.util.update_formatter_for_loggers([logging.getLogger(app.app.name)], formatter) # noinspection PyAttributeOutsideInit diff --git a/json_logging/framework/flask/__init__.py b/json_logging/framework/flask/__init__.py index 78039fb..6157210 100644 --- a/json_logging/framework/flask/__init__.py +++ b/json_logging/framework/flask/__init__.py @@ -50,8 +50,8 @@ def config(self, app, request_response_dto_class, exclude_url_patterns=[]): if json_logging.ENABLE_JSON_LOGGING: from flask.logging import default_handler formatter = json_logging._default_formatter or json_logging.formatters.JSONLogWebFormatter - if not isinstance(default_handler.formatter, formatter): - default_handler.setFormatter(formatter()) + # Always construct a new formatter: an existing instance may have captured an older EXCLUDED_FIELDS. + default_handler.setFormatter(formatter()) json_logging.util.update_formatter_for_loggers([logging.getLogger(app.name)], formatter) # noinspection PyAttributeOutsideInit diff --git a/tests/test_error_handling.py b/tests/test_error_handling.py index 29f95c7..ce07ac3 100644 --- a/tests/test_error_handling.py +++ b/tests/test_error_handling.py @@ -8,7 +8,7 @@ installs a root handler whose formatter is an explicit ``logging.Formatter`` (default format ``%(levelname)s:%(name)s:%(message)s``); the handler is therefore not covered by ``logging._defaultFormatter`` and, before the fix, the root logger was not part of the formatter -sweep either. Every record propagating to root - including Flask's exception log - stayed plain. +sweep either. Every record propagating to root, including Flask's exception log, stayed plain. """ import io import json @@ -20,6 +20,7 @@ EXCEPTION_MESSAGE = "'NoneType' object is not iterable" LOGGER_NAME = "user_db_api.app" +REQUEST_LOGGER_NAMES = ["flask-request-logger", "connexion-request-logger"] @pytest.fixture @@ -31,23 +32,40 @@ def fresh_json_logging(): undo_imports_from_package("json_logging") +def _loggers_to_restore(): + """The root logger, every logger that exists now, and the shared loggers these tests create.""" + shared_names = [LOGGER_NAME, __name__] + REQUEST_LOGGER_NAMES + loggers = [logging.root] + [logging.getLogger(name) for name in shared_names] + loggers.extend(entry for entry in logging.Logger.manager.loggerDict.values() if isinstance(entry, logging.Logger)) + unique_loggers = [] + seen = set() + for logger in loggers: + if id(logger) not in seen: + seen.add(id(logger)) + unique_loggers.append(logger) + return unique_loggers + + @pytest.fixture(autouse=True) def restore_process_logging(): """Undo the process-global logging changes these tests deliberately make.""" import flask.logging as flask_logging - # Flask attaches its shared default_handler to the app logger; keep each test's logger clean for the next one. - touched_loggers = [LOGGER_NAME, __name__] - saved_logger_handlers = {name: logging.getLogger(name).handlers[:] for name in touched_loggers} - saved_root_handlers = logging.root.handlers[:] + # init_*() rewrites the formatter of every handler it finds, and init_request_instrument() adds an output + # handler to a shared request logger, so snapshot each handler list and each handler's formatter. + saved_loggers = [ + (logger, logger.handlers[:], [(handler, handler.formatter) for handler in logger.handlers]) + for logger in _loggers_to_restore() + ] saved_root_level = logging.root.level saved_default_formatter = logging._defaultFormatter saved_flask_default_formatter = flask_logging.default_handler.formatter saved_flask_default_stream = flask_logging.default_handler.stream yield - for name, handlers in saved_logger_handlers.items(): - logging.getLogger(name).handlers[:] = handlers - logging.root.handlers[:] = saved_root_handlers + for logger, handlers, handler_formatters in saved_loggers: + logger.handlers[:] = handlers + for handler, formatter in handler_formatters: + handler.setFormatter(formatter) logging.root.setLevel(saved_root_level) logging._defaultFormatter = saved_default_formatter flask_logging.default_handler.setFormatter(saved_flask_default_formatter) @@ -55,35 +73,49 @@ def restore_process_logging(): def raise_type_error(): + """Raise the exception type that the production incident logged.""" raise TypeError(EXCEPTION_MESSAGE) -def configure_root_logger_like_basic_config(buffer): - """Reproduce the toolchain setup: a root handler with an explicit default Formatter.""" - for handler in logging.root.handlers[:]: - logging.root.removeHandler(handler) +def configure_root_logger_like_basic_config(): + """Reproduce the toolchain setup: a root handler with an explicit default Formatter, and return the handler.""" + remove_root_handlers() logging.root.setLevel(logging.INFO) logging.basicConfig() handler = logging.root.handlers[0] assert type(handler.formatter) is logging.Formatter, "basicConfig() must install an explicit Formatter" + return handler + + +def capture_stream(handler): + """Point *handler* at a fresh buffer, so only records emitted afterwards are captured.""" + buffer = io.StringIO() handler.stream = buffer + return buffer def remove_root_handlers(): + """Leave the root logger without handlers, as a gunicorn-hosted worker does.""" for handler in logging.root.handlers[:]: logging.root.removeHandler(handler) +def parse_records(text): + """Parse every non-empty line as JSON, so a plain text line fails the test instead of being skipped.""" + return [json.loads(line) for line in text.splitlines() if line.strip()] + + def error_records(text): - """The ERROR log records in *text*, ignoring plain text and request records.""" + """The ERROR log records in *text*, which must contain JSON lines only.""" return [ record - for record in (json.loads(line) for line in text.splitlines() if line.startswith("{")) + for record in parse_records(text) if record.get("type") == "log" and record.get("level") == "ERROR" ] def assert_single_exception_record(records, message, logger_name=LOGGER_NAME): + """Assert that exactly one exception record carried the message and the traceback.""" assert len(records) == 1, [record.get("msg") for record in records] record = records[0] assert record["logger"] == logger_name @@ -93,10 +125,11 @@ def assert_single_exception_record(records, message, logger_name=LOGGER_NAME): def test_exception_through_root_handler_configured_before_init_is_one_json_record(fresh_json_logging): - buffer = io.StringIO() - configure_root_logger_like_basic_config(buffer) + """A root handler with an explicit formatter is converted by init_{non_web}.""" + handler = configure_root_logger_like_basic_config() fresh_json_logging.init_non_web(enable_json=True) + buffer = capture_stream(handler) try: raise_type_error() @@ -107,13 +140,14 @@ def test_exception_through_root_handler_configured_before_init_is_one_json_recor def test_flask_unhandled_exception_with_root_handler_is_one_json_record(fresh_json_logging): + """An unhandled Flask exception propagated to a configured root handler is one JSON record.""" import flask - buffer = io.StringIO() - configure_root_logger_like_basic_config(buffer) + handler = configure_root_logger_like_basic_config() fresh_json_logging.init_flask(enable_json=True) app = flask.Flask(LOGGER_NAME) fresh_json_logging.init_request_instrument(app) + buffer = capture_stream(handler) @app.route("/boom") def boom(): @@ -125,6 +159,7 @@ def boom(): def test_flask_app_logger_handler_added_before_instrumentation_is_one_json_record(fresh_json_logging): + """A handler Flask attached to the app logger before instrumentation is converted.""" import flask remove_root_handlers() @@ -147,6 +182,7 @@ def boom(): def test_flask_handler_attached_on_first_use_is_json(fresh_json_logging, capfd): + """The handler Flask attaches on first use is JSON, and json_logging adds no handler of its own.""" import flask remove_root_handlers() @@ -168,6 +204,7 @@ def boom(): def test_flask_app_logger_is_left_plain_when_json_logging_is_disabled(fresh_json_logging): + """With JSON logging disabled the app logger keeps its plain text formatter.""" import flask from flask.logging import default_handler @@ -185,7 +222,30 @@ def test_flask_app_logger_is_left_plain_when_json_logging_is_disabled(fresh_json assert app.logger.handlers[0].formatter is plain_formatter +def test_connexion_unhandled_request_exception_is_one_json_record(fresh_json_logging): + """A failing Connexion 3 request, through its real middleware, logs one JSON exception record.""" + connexion = pytest.importorskip("connexion") + + handler = configure_root_logger_like_basic_config() + fresh_json_logging.init_connexion(enable_json=True) + app = connexion.FlaskApp(__name__, specification_dir=".") + app.add_api({ + "openapi": "3.0.0", + "info": {"title": "exception logging", "version": "1"}, + "paths": {"/boom": {"get": {"operationId": f"{__name__}.boom", "responses": {"200": {"description": "ok"}}}}}, + }) + fresh_json_logging.init_request_instrument(app) + buffer = capture_stream(handler) + + assert app.test_client().get("/boom").status_code == 500 + + # Connexion 3 reports the failure through its own middleware logger, which propagates to the converted root handler. + assert_single_exception_record( + error_records(buffer.getvalue()), f"TypeError({EXCEPTION_MESSAGE!r})", "connexion.middleware.exceptions") + + def test_connexion_app_logger_exception_is_one_json_record(fresh_json_logging): + """The app logger of a Connexion application is converted, which Connexion 2 and app code rely on.""" connexion = pytest.importorskip("connexion") remove_root_handlers() @@ -206,3 +266,8 @@ def test_connexion_app_logger_exception_is_one_json_record(fresh_json_logging): assert_single_exception_record( error_records(buffer.getvalue()), "Exception on /v1/user_resource_access_info [GET]", logger.name) + + +def boom(): + """Operation used by the Connexion specification above; it fails the way production did.""" + raise_type_error() From cb5467da9b80c48a476bacc767f078c82b412481 Mon Sep 17 00:00:00 2001 From: Don Bowman Date: Fri, 6 Nov 2026 17:03:20 -0500 Subject: [PATCH 4/5] test: restore werkzeug state and document error-path change The error handling tests disable the shared werkzeug logger through init_flask()/init_connexion(), but the autouse fixture did not restore the disabled flag, so later tests could not observe werkzeug logs depending on order. Save and restore the flag alongside the handler and formatter state. Also describe the logging setup generically instead of referring to one production incident, and add a CHANGELOG entry for the root and Flask default handler conversion, since applications with a plain root handler now emit JSON when JSON logging is enabled. --- CHANGELOG.md | 4 ++++ tests/test_error_handling.py | 37 ++++++++++++++++++++---------------- 2 files changed, 25 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 88d2a42..46b89b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/). ### Fixed - `get_request_logger()` now raises the documented `RuntimeError` instead of `AttributeError` when called before `init_request_instrument()`. +- `init_*()` now converts handlers already attached to the root logger, and `init_flask()`/`init_connexion()` convert + `flask.logging.default_handler`, so an unhandled exception is emitted as one JSON record with `level` and `exc_info` + instead of a plain multi-line traceback. This is a behaviour change for applications that configure a root handler + with their own formatter before `init_*()`: when JSON logging is enabled, that handler now emits JSON as well. (#147) ## 1.6.0 - 2026-10-21 diff --git a/tests/test_error_handling.py b/tests/test_error_handling.py index ce07ac3..32bf594 100644 --- a/tests/test_error_handling.py +++ b/tests/test_error_handling.py @@ -1,14 +1,14 @@ """Error-path formatting: an exception must reach the log as one JSON record. -Regression coverage for the 2026-11-02 API incident: unhandled exceptions reported by the -Flask/connexion app logger were emitted as plain multi-line text, so they never carried a -``level`` or a single ``exc_info`` field and could not be alerted on. - -The toolchain was running ``logging.basicConfig()`` before ``json_logging.init_*()``. That call -installs a root handler whose formatter is an explicit ``logging.Formatter`` (default format -``%(levelname)s:%(name)s:%(message)s``); the handler is therefore not covered by -``logging._defaultFormatter`` and, before the fix, the root logger was not part of the formatter -sweep either. Every record propagating to root, including Flask's exception log, stayed plain. +The setup under test is an application that configures logging before calling ``json_logging.init_*()``. +``logging.basicConfig()`` installs a root handler whose formatter is an explicit ``logging.Formatter`` +(default format ``%(levelname)s:%(name)s:%(message)s``), so ``logging._defaultFormatter`` does not apply +to it. Before the fix, ``init_*()`` swept only named loggers, which left such a handler, and every record +propagating to root, including an unhandled exception reported by Flask, as plain multi-line text instead +of a single JSON record carrying ``level`` and ``exc_info``. + +Flask and Connexion also attach ``flask.logging.default_handler`` to the app logger on first use, so the +tests cover both that lazy attachment and a handler the application added before instrumentation. """ import io import json @@ -19,7 +19,7 @@ from helpers.imports import undo_imports_from_package EXCEPTION_MESSAGE = "'NoneType' object is not iterable" -LOGGER_NAME = "user_db_api.app" +LOGGER_NAME = "example.app" REQUEST_LOGGER_NAMES = ["flask-request-logger", "connexion-request-logger"] @@ -51,6 +51,10 @@ def restore_process_logging(): """Undo the process-global logging changes these tests deliberately make.""" import flask.logging as flask_logging + # Flask and Connexion instrumentation disable the shared werkzeug logger; snapshot its flag as well. + werkzeug_logger = logging.getLogger("werkzeug") + saved_werkzeug_disabled = werkzeug_logger.disabled + # init_*() rewrites the formatter of every handler it finds, and init_request_instrument() adds an output # handler to a shared request logger, so snapshot each handler list and each handler's formatter. saved_loggers = [ @@ -70,10 +74,11 @@ def restore_process_logging(): logging._defaultFormatter = saved_default_formatter flask_logging.default_handler.setFormatter(saved_flask_default_formatter) flask_logging.default_handler.stream = saved_flask_default_stream + werkzeug_logger.disabled = saved_werkzeug_disabled def raise_type_error(): - """Raise the exception type that the production incident logged.""" + """Raise the exception type used throughout these error-path tests.""" raise TypeError(EXCEPTION_MESSAGE) @@ -134,9 +139,9 @@ def test_exception_through_root_handler_configured_before_init_is_one_json_recor try: raise_type_error() except TypeError: - logging.getLogger(LOGGER_NAME).error("Exception on /v1/user_resource_access_info [GET]", exc_info=True) + logging.getLogger(LOGGER_NAME).error("Exception on /boom [GET]", exc_info=True) - assert_single_exception_record(error_records(buffer.getvalue()), "Exception on /v1/user_resource_access_info [GET]") + assert_single_exception_record(error_records(buffer.getvalue()), "Exception on /boom [GET]") def test_flask_unhandled_exception_with_root_handler_is_one_json_record(fresh_json_logging): @@ -262,12 +267,12 @@ def test_connexion_app_logger_exception_is_one_json_record(fresh_json_logging): try: raise_type_error() except TypeError: - logger.error("Exception on /v1/user_resource_access_info [GET]", exc_info=True) + logger.error("Exception on /boom [GET]", exc_info=True) assert_single_exception_record( - error_records(buffer.getvalue()), "Exception on /v1/user_resource_access_info [GET]", logger.name) + error_records(buffer.getvalue()), "Exception on /boom [GET]", logger.name) def boom(): - """Operation used by the Connexion specification above; it fails the way production did.""" + """Operation used by the Connexion specification above; it raises an unhandled exception.""" raise_type_error() From 47c34ec432e0a4132a1e0eb9bce739449cd44015 Mon Sep 17 00:00:00 2001 From: Srinivas Chippagiri Date: Fri, 6 Nov 2026 16:11:48 -0800 Subject: [PATCH 5/5] docs: say that init_request_instrument() converts Flask's default handler --- CHANGELOG.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 46b89b0..5ec1deb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,9 +9,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/). ### Fixed - `get_request_logger()` now raises the documented `RuntimeError` instead of `AttributeError` when called before `init_request_instrument()`. -- `init_*()` now converts handlers already attached to the root logger, and `init_flask()`/`init_connexion()` convert - `flask.logging.default_handler`, so an unhandled exception is emitted as one JSON record with `level` and `exc_info` - instead of a plain multi-line traceback. This is a behaviour change for applications that configure a root handler +- `init_*()` now converts handlers already attached to the root logger, and `init_request_instrument(app)` for Flask + and Connexion converts `flask.logging.default_handler`, so an unhandled exception is emitted as one JSON record with + `level` and `exc_info` instead of a plain multi-line traceback. This is a behaviour change for applications that configure a root handler with their own formatter before `init_*()`: when JSON logging is enabled, that handler now emits JSON as well. (#147) ## 1.6.0 - 2026-10-21