feat: improve exception handling

Author: ErikKalkoken

.gitignore

@@ -208,3 +208,6 @@ __marimo__/
 
 # VS Code
 .vscode/
+
+# Misc
+.temp/

README.md

@@ -1,4 +1,4 @@
-# python-victorialogs-handler
+# victorialogs-handler
 
 A Python log handler for Victoria Logs.
 
@@ -12,11 +12,48 @@ STATUS: In development
 
 ## Description
 
-This package provides a Python log handler for Victoria Logs. The log handler is designed to work with Python's default logging module and will send all log events to a configured Victoria Logs server for log ingestion.
+**victorialogs-handler** is a high-performance Python log handler tailored for [VictoriaLogs](https://victoriametrics.com/products/victorialogs/). It integrates seamlessly with Python’s native logging module, allowing you to stream log events to a VictoriaLogs instance with minimal configuration and zero friction.
 
 ## Key Features
 
-- Asynchronous design: Log events are queued and then processed in a separate thread so that the performance impact on the main program remains minimal.
-- Request batching: Log events are processed without delay. Multiple log events will be sent in a single request as batch to minimize the number of requests to the VictoriaLogs server.
-- Supports extras: Extra fields are supported. This includes non-standard types like sets and datetime objects. Fields that can not be serialized to JSON (e.g. functions) will be converted into their string representation
-- Supports dict config: The handler supports dict configuration, e.g. for a Django server
+- **Asynchronous Processing**: Log events are queued and dispatched in a dedicated background thread, ensuring your application's main execution flow remains non-blocking and highly responsive.
+
+- **Efficient Request Batching**: To optimize network throughput and reduce overhead on your VictoriaLogs server, multiple log events are automatically combined into single-request batches.
+
+- **Rich Exception Handling**: Automatically captures and flattens stack traces. Log messages include both the exception name and the full traceback as searchable fields.
+
+- **Smart Serialization**: Supports extra fields out of the box. It intelligently handles non-standard types like set and datetime. Any non-serializable objects (such as functions or custom classes) are gracefully converted to their string representation.
+
+- **Standard Configuration Support**: Fully compatible with `logging.config.dictConfig`, making it easy to drop into frameworks like Django, Flask, or FastAPI.
+
+## Technical details
+
+This section documents technical details of the solution.
+
+### LogRecord fields
+
+The following fields will be transferred for each log event. They are derived from Python's [LogRecord](https://docs.python.org/3/library/logging.html#logrecord-objects):
+
+Name | Description | Example | Optional
+-- | -- | -- | --
+`exception_name` | Name of the exception | `ZeroDivisionError` | yes
+`exception` | Full traceback of the exception | `Traceback ...` | yes
+`function` | Name of the function that emitted the log event | `my_function` | no
+`level` | Name of the level of the emitted log event | `INFO` | no
+`line_number` | Line number where the log event was emitted | `89` | no
+`logger` | Name of the related Python logger | `my_package.my_module` | no
+`message` | The logged message | 'This is a log entry' | no
+`stream` | Name of the top-level Python package that emitted the log the event. | `my_package` | no
+`timestamp` | Timestamp of the log event, represented as fractional UNIX epoch | `1775081468.4308655` | no
+
+In addition any custom `extras' fields will be added as they are encountered.
+
+### VictoriaLogs special fields
+
+VictoriaLogs handles three fields in a special:
+
+- `_msg`: The logged message. This is a mandatory field and is mapped to `message`.
+- `_time`: The timestamp of the log event. This field and is mapped to `timestamp`.
+- `_stream`: The source of a log event, which is used to group and filter logs. This field is mapped to `stream`.
+
+For more information please also see [VictoriaLogs Data model](https://docs.victoriametrics.com/victorialogs/keyconcepts/#data-model).

src/vlogs_handler/__init__.py

@@ -3,7 +3,7 @@
 from .handler import VictoriaLogsHandler  # noqa: F401
 
 __title__ = "Victoria Logs Handler"
-__version__ = "0.1.0dev2"
+__version__ = "0.1.0dev3"
 
 # TO-DOs
 # [ ] Options for defining stream

src/vlogs_handler/handler.py

@@ -7,7 +7,7 @@
 import queue
 import threading
 import traceback
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Tuple
 
 import requests
 
@@ -19,6 +19,7 @@
 
 _STANDARD_ATTRS = {
     "args",
+    "asctime",
     "created",
     "exc_info",
     "exc_text",
@@ -37,18 +38,14 @@
     "processName",
     "relativeCreated",
     "stack_info",
+    "taskName",
     "thread",
     "threadName",
 }
 
 
 class VictoriaLogsHandler(logging.Handler):
-    """VictoriaLogsHandler dispatches log events to a Victoria Logs server.
-
-    Events are sent asynchronously for best performance.
-    Events are sent without delay.
-    Events are batched together to reduce the amount of requests to the vlogs server.
-    """
+    """VictoriaLogsHandler dispatches log events to a Victoria Logs server."""
 
     def __init__(
         self,
@@ -98,7 +95,9 @@ def format_log_entry(self, record: logging.LogRecord) -> Dict[str, Any]:
             "process_name": record.processName,
         }
         if record.exc_info:
-            entry["exception"] = _format_exception(record.exc_info)
+            entry["exception_name"], entry["exception"] = _format_exception(
+                record.exc_info
+            )
 
         for k, v in record.__dict__.items():
             if k not in _STANDARD_ATTRS:
@@ -123,7 +122,7 @@ def _send(self, entries: List[Dict[str, Any]]):
         lines = []
         for entry in entries:
             try:
-                data = json.dumps(entry, cls=JSONEncoderPlus)
+                data = json.dumps(entry, cls=_JSONEncoderPlus)
                 lines.append(data)
             except Exception as ex:
                 log.exception("convert entry to JSON", ex, entry=entry)
@@ -142,14 +141,15 @@ def _send(self, entries: List[Dict[str, Any]]):
             log.exception("send entry", ex)
 
 
-def _format_exception(ei):
+def _format_exception(ei) -> Tuple[str, str]:
     """
-    Format and return the specified exception information as a string.
+    Format and return the name of the exception
+    and specified exception information as strings.
 
     This default implementation just uses
     traceback.print_exception()
 
-    Source: logging.Formatter.formatException()
+    Based on: logging.Formatter.formatException()
     """
     sio = io.StringIO()
     tb = ei[2]
@@ -158,7 +158,9 @@ def _format_exception(ei):
     sio.close()
     if s[-1:] == "\n":
         s = s[:-1]
-    return s
+
+    name = ei[0].__name__ if ei[0] is not None else ""
+    return name, s
 
 
 def _calc_stream_from_record(record: logging.LogRecord):
@@ -173,7 +175,7 @@ def _calc_stream_from_record(record: logging.LogRecord):
     return stream
 
 
-class JSONEncoderPlus(json.JSONEncoder):
+class _JSONEncoderPlus(json.JSONEncoder):
     """JSONEncoderPlus is an improved encoder that can convert dates and does not break.
 
     Instead of breaking it will return a string representation

tests/test_handler.py

@@ -7,7 +7,7 @@
 import requests_mock
 
 from vlogs_handler import VictoriaLogsHandler
-from vlogs_handler.handler import JSONEncoderPlus
+from vlogs_handler.handler import _JSONEncoderPlus
 
 
 @requests_mock.Mocker()
@@ -48,6 +48,7 @@ def test_handler_should_send_normal_log(self, m: requests_mock.Mocker):
         self.assertEqual(got["level"], "INFO")
         self.assertEqual(got["logger"], "test_logger")
         self.assertEqual(got["message"], "Alpha")
+        self.assertNotIn("exception", got)
 
     def test_handler_should_send_log_with_extras(self, m: requests_mock.Mocker):
         # given
@@ -97,6 +98,7 @@ def test_handler_should_send_exception_log(self, m: requests_mock.Mocker):
         self.assertEqual(got["level"], "ERROR")
         self.assertEqual(got["logger"], "test_logger")
         self.assertEqual(got["message"], "Bravo")
+        self.assertEqual("ZeroDivisionError", got["exception_name"])
         self.assertIn("ZeroDivisionError", got["exception"])
 
 
@@ -157,7 +159,7 @@ def my_func():
 
         my_date = dt.datetime(2026, 1, 11, 12, 15, 42, 99, tzinfo=dt.timezone.utc)
         data = {
-            "class": JSONEncoderPlus,
+            "class": _JSONEncoderPlus,
             "date": my_date.date(),
             "datetime": my_date,
             "float": 1.23,
@@ -168,11 +170,11 @@ def my_func():
         }
 
         # when
-        got = json.loads(json.dumps(data, cls=JSONEncoderPlus))
+        got = json.loads(json.dumps(data, cls=_JSONEncoderPlus))
 
         # then
         self.assertEqual(
-            got["class"], "<class 'vlogs_handler.handler.JSONEncoderPlus'>"
+            got["class"], "<class 'vlogs_handler.handler._JSONEncoderPlus'>"
         )
         self.assertEqual(got["date"], "2026-01-11")
         self.assertEqual(got["datetime"], "2026-01-11T12:15:42.000099+00:00")