formatted message for troubleshooting

Author: pcrespov

packages/service-library/src/servicelib/logging_utils.py

@@ -16,6 +16,9 @@
 from pathlib import Path
 from typing import Any, TypeAlias, TypedDict, TypeVar
 
+from models_library.utils.json_serialization import json_dumps
+
+from .error_codes import ErrorCodeStr
 from .utils_secrets import mask_sensitive_data
 
 _logger = logging.getLogger(__name__)
@@ -320,24 +323,62 @@ def log_catch(logger: logging.Logger, *, reraise: bool = True) -> Iterator[None]
 
 class LogExtra(TypedDict, total=False):
     log_uid: str
+    log_oec: str
 
 
 LogLevelInt: TypeAlias = int
 LogMessageStr: TypeAlias = str
 
 
-def get_log_record_extra(*, user_id: int | str | None = None) -> LogExtra | None:
+def get_log_record_extra(
+    *,
+    user_id: int | str | None = None,
+    error_code: str | None = None,
+) -> LogExtra | None:
     extra: LogExtra = {}
+
     if user_id:
         assert int(user_id) > 0  # nosec
         extra["log_uid"] = f"{user_id}"
+    if error_code:
+        extra["log_oec"] = error_code
+
     return extra or None
 
 
 def _un_capitalize(s: str) -> str:
     return s[:1].lower() + s[1:] if s else ""
 
 
+def create_troubleshotting_log_message(
+    message_to_user: str,
+    error: BaseException,
+    error_code: ErrorCodeStr,
+    error_context: dict[str, Any] | None = None,
+    tip: str | None = None,
+) -> str:
+    """Create a formatted message for _logger.exception(...)
+
+    Arguments:
+        message_to_user -- A user-friendly message to be displayed on the front-end explaining the issue in simple terms.
+        error -- the instance of the handled exception
+        error_code -- A unique error code (e.g., OEC or osparc-specific) to identify the type or source of the error for easier tracking.
+        error_context -- Additional context surrounding the exception, such as environment variables or function-specific data. This can be derived from exc.error_context() (relevant when using the OsparcErrorMixin)
+        tip -- Helpful suggestions or possible solutions explaining why the error may have occurred and how it could potentially be resolved
+    """
+    debug_data = json_dumps(
+        {
+            "exception_details": f"{error}",
+            "error_code": error_code,
+            "context": error_context,
+            "tip": tip,
+        },
+        indent=1,
+    )
+
+    return f"{message_to_user}.\n{debug_data}"
+
+
 @contextmanager
 def log_context(
     logger: logging.Logger,

packages/service-library/tests/test_error_codes.py

@@ -5,50 +5,50 @@
 
 import logging
 
+import pytest
 from servicelib.error_codes import create_error_code, parse_error_code
 
 logger = logging.getLogger(__name__)
 
 
-def test_error_code_use_case(caplog):
+def test_error_code_use_case(caplog: pytest.LogCaptureFixture):
     """use case for error-codes"""
-    try:
+    with pytest.raises(RuntimeError) as exc_info:
         raise RuntimeError("Something unexpected went wrong")
-    except Exception as err:
-        # 1. Unexpected ERROR
 
-        # 2. create error-code
-        error_code = create_error_code(err)
+    # 1. Unexpected ERROR
+    err = exc_info.value
 
-        # 3. log all details in service
-        caplog.clear()
+    # 2. create error-code
+    error_code = create_error_code(err)
 
-        # Can add a formatter that prefix error-codes
-        syslog = logging.StreamHandler()
-        syslog.setFormatter(
-            logging.Formatter("%(asctime)s %(error_code)s : %(message)s")
-        )
-        logger.addHandler(syslog)
+    # 3. log all details in service
+    caplog.clear()
 
-        logger.error("Fake Unexpected error", extra={"error_code": error_code})
+    # Can add a formatter that prefix error-codes
+    syslog = logging.StreamHandler()
+    syslog.setFormatter(logging.Formatter("%(asctime)s %(error_code)s : %(message)s"))
+    logger.addHandler(syslog)
 
-        # logs something like E.g. 2022-07-06 14:31:13,432 OEC:140350117529856 : Fake Unexpected error
-        assert parse_error_code(
-            f"2022-07-06 14:31:13,432 {error_code} : Fake Unexpected error"
-        ) == {
-            error_code,
-        }
+    logger.exception("Fake Unexpected error", extra={"error_code": error_code})
 
-        assert caplog.records[0].error_code == error_code
-        assert caplog.records[0]
+    # logs something like E.g. 2022-07-06 14:31:13,432 OEC:140350117529856 : Fake Unexpected error
+    assert parse_error_code(
+        f"2022-07-06 14:31:13,432 {error_code} : Fake Unexpected error"
+    ) == {
+        error_code,
+    }
 
-        logger.error("Fake without error_code")
+    assert caplog.records[0].error_code == error_code
+    assert caplog.records[0]
 
-        # 4. inform user (e.g. with new error or sending message)
-        user_message = (
-            f"This is a user-friendly message to inform about an error. [{error_code}]"
-        )
+    logger.exception("Fake without error_code")
 
-        assert parse_error_code(user_message) == {
-            error_code,
-        }
+    # 4. inform user (e.g. with new error or sending message)
+    user_message = (
+        f"This is a user-friendly message to inform about an error. [{error_code}]"
+    )
+
+    assert parse_error_code(user_message) == {
+        error_code,
+    }