docs: clarify part about error handling in docs

Author: danfimov

docs/contrib.md

@@ -26,12 +26,12 @@ uv sync --all-extras
 
 ## Linting
 
-We have `pre-commit` configured with all our settings. We highly recommend you to install it as a git hook using `pre-commit install` command.
+We have `prek` configured with all our settings. We highly recommend you to install it as a git hook using `prek install` command.
 
 But even without installation, you can run all lints manually:
 
 ```bash
-pre-commit run -a
+prek run -a
 ```
 
 ## Testing

docs/examples/errors/error_middleware.py

@@ -0,0 +1,21 @@
+from typing import Any
+
+from taskiq import InMemoryBroker, TaskiqMessage, TaskiqMiddleware, TaskiqResult
+
+
+class ErrorReporterMiddleware(TaskiqMiddleware):
+    def on_error(
+        self,
+        message: "TaskiqMessage",
+        result: "TaskiqResult[Any]",
+        exception: BaseException,
+    ) -> None:
+        # This code runs on the worker, so the traceback
+        # of the exception is still available here.
+        print(
+            f"Task {message.task_name} with id {message.task_id} "
+            f"failed: {exception!r}",
+        )
+
+
+broker = InMemoryBroker().with_middlewares(ErrorReporterMiddleware())

docs/examples/errors/raise_for_error.py

@@ -0,0 +1,30 @@
+import asyncio
+from typing import Any
+
+from taskiq import InMemoryBroker
+
+broker = InMemoryBroker()
+
+
+@broker.task
+async def divide(a: int, b: int) -> Any:
+    return a / b
+
+
+async def main() -> None:
+    await broker.startup()
+
+    task = await divide.kiq(1, 0)
+    try:
+        # Raises ZeroDivisionError, otherwise returns the result itself.
+        result = (await task.wait_result()).raise_for_error()
+    except ZeroDivisionError:
+        print("Cannot divide by zero.")
+    else:
+        print(f"Returned value: {result.return_value}")
+
+    await broker.shutdown()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/examples/errors/result_error.py

@@ -0,0 +1,29 @@
+import asyncio
+from typing import Any
+
+from taskiq import InMemoryBroker
+
+broker = InMemoryBroker()
+
+
+@broker.task
+async def divide(a: int, b: int) -> Any:
+    return a / b
+
+
+async def main() -> None:
+    await broker.startup()
+
+    task = await divide.kiq(1, 0)
+    result = await task.wait_result()
+
+    if result.is_err:
+        print(f"Task failed with {type(result.error).__name__}: {result.error}")
+    else:
+        print(f"Returned value: {result.return_value}")
+
+    await broker.shutdown()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/examples/state/events_example.py

@@ -45,10 +45,9 @@ async def main() -> None:
     await broker.startup()
 
     set_task = await set_val.kiq("key", "value")
-    set_result = await set_task.wait_result(with_logs=True)
+    set_result = await set_task.wait_result()
     if set_result.is_err:
-        print(set_result.log)
-        raise ValueError("Cannot set value in redis. See logs.")
+        raise ValueError("Cannot set value in redis.") from set_result.error
 
     get_task = await get_val.kiq("key")
     get_res = await get_task.wait_result()

docs/examples/state/events_example_annot.py

@@ -53,10 +53,9 @@ async def main() -> None:
     await broker.startup()
 
     set_task = await set_val.kiq("key", "value")
-    set_result = await set_task.wait_result(with_logs=True)
+    set_result = await set_task.wait_result()
     if set_result.is_err:
-        print(set_result.log)
-        raise ValueError("Cannot set value in redis. See logs.")
+        raise ValueError("Cannot set value in redis.") from set_result.error
 
     get_task = await get_val.kiq("key")
     get_res = await get_task.wait_result()

docs/guide/architecture-overview.md

@@ -137,6 +137,8 @@ async def my_async_task() -> None:
 
 Result backend is used to store and get results of the execution.
 Results have type `TaskiqResult` from [taskiq.result](https://github.com/taskiq-python/taskiq/blob/master/taskiq/result.py).
+It holds the returned value, the execution time and the exception, if the task has failed.
+See [Error handling](./error-handling.md) for more info about failed tasks.
 
 Every ResultBackend must implement `AsyncResultBackend` from [taskiq.abc.result_backend](https://github.com/taskiq-python/taskiq/blob/master/taskiq/abc/result_backend.py). By default, brokers use `DummyResultBackend`. It doesn't do anything and cannot be used
 in real-world scenarios. But some brokers can override it. For example `InMemoryBroker` by default uses `InMemoryResultBackend` and returns correct results.
@@ -223,7 +225,7 @@ Here are methods you can implement in the order they are executed:
 - `pre_send` - executed on the client side before the message is sent. Here you can modify the message.
 - `post_send` - executed right after the message was sent.
 - `pre_execute` - executed on the worker side after the message was received by a worker and before its execution.
-- `on_error` - executed after the task was executed if an exception was found.
+- `on_error` - executed after the task was executed if an exception was found. See [Error handling](./error-handling.md).
 - `post_execute` - executed after the message was executed.
 - `post_save` - executed after the result was saved in the result backend.
 

docs/guide/error-handling.md

@@ -0,0 +1,122 @@
+---
+title: Error handling
+order: 10
+---
+
+# Error handling
+
+When a task raises an exception, the worker doesn't crash. It catches the exception, logs it and stores it in the 
+`TaskiqResult` along with everything else. What you do with it afterwards depends on where you want to handle the error:
+on the client side, where the result is awaited, or on the worker side, where the exception happened.
+
+## Handling errors on the client
+
+`TaskiqResult` has two fields related to errors:
+
+* `is_err` - `True` if the task has failed;
+* `error` - the exception itself, or `None` if the task succeeded.
+
+@[code python](../examples/errors/result_error.py)
+
+If you'd rather work with exceptions than with flags, use the `raise_for_error` method. It raises the stored exception 
+if there is one and returns the result itself otherwise, so it can be chained right after `wait_result`.
+
+@[code python](../examples/errors/raise_for_error.py)
+
+Tracebacks are not transferred to the client. Only the exception type, its arguments and the chain of `__cause__`/`__context__` 
+exceptions are serialized. Sending tracebacks over the network is unreliable and may leak sensitive information from the
+worker, so Taskiq intentionally doesn't do it.
+
+Also, the client has to be able to import the exception class to restore it. If the exception is defined in a module 
+unavailable on the client side, Taskiq creates a synthetic exception class with the same name in the `taskiq.exceptions`
+namespace, so `except MyError` won't catch it, while `except Exception` still will.
+
+## Handling errors on the worker
+
+Client-side handling is only possible if you use a result backend and wait for the result. Fire-and-forget tasks have 
+nobody to report to. Besides, sometimes you want to react to every failure in one place instead of duplicating 
+the same handling in every caller.
+
+For these cases, use the `on_error` hook of a middleware. It's called on the worker right after the exception is caught, so the full traceback is still available.
+
+@[code python](../examples/errors/error_middleware.py)
+
+That's the recommended way to integrate taskiq with error tracking systems. For example, here's how you can send all task failures to Sentry:
+
+```python
+from typing import Any
+
+import sentry_sdk
+from sentry_sdk.integrations.logging import LoggingIntegration, ignore_logger
+
+from taskiq import (
+    TaskiqEvents,
+    TaskiqMessage,
+    TaskiqMiddleware,
+    TaskiqResult,
+    TaskiqState,
+)
+
+
+class SentryMiddleware(TaskiqMiddleware):
+    def on_error(
+        self,
+        message: "TaskiqMessage",
+        result: "TaskiqResult[Any]",
+        exception: BaseException,
+    ) -> None:
+        sentry_sdk.capture_exception(
+            exception,
+            tags={
+                "taskiq_task_name": message.task_name,
+                "taskiq_task_id": message.task_id,
+            },
+        )
+
+
+# Here `broker` is the broker you defined for your project.
+broker = broker.with_middlewares(SentryMiddleware())
+
+
+@broker.on_event(TaskiqEvents.WORKER_STARTUP)
+def init_sentry(_: TaskiqState) -> None:
+    # We ignore this logger, because its events may overwrite the exception 
+    # we capture in the middleware with new tags.
+    ignore_logger("taskiq.receiver.receiver")
+    sentry_sdk.init(
+        "https://key@your-sentry-instance",
+        environment="dev",
+        integrations=[LoggingIntegration()],
+    )
+```
+
+If your framework integration initializes Sentry on its own, you can drop the startup event and keep the middleware only.
+
+::: tip Retries
+
+If you want failed tasks to be retried instead of being reported, take a look at the [`SimpleRetryMiddleware`](../available-components/middlewares.md)
+or the [`SmartRetryMiddleware`](../available-components/middlewares.md).
+
+:::
+
+## Errors in dependencies
+
+Generator dependencies can catch exceptions raised by the task they are injected into. It's useful if you want to roll 
+back a transaction that was opened in the dependency. This is described in 
+[State and Dependencies](./state-and-deps.md#exception-handling), along with the `--no-propagate-errors` option 
+that turns this behaviour off.
+
+## Skipping the result
+
+Sometimes a task shouldn't store any result at all. Raising `NoResultError` inside a task tells the worker to skip 
+saving the result to the result backend, so waiting for the result of such a task will time out. 
+Note that `NoResultError` is still treated as an exception internally, so `on_error` middlewares are called for it as well.
+
+```python
+from taskiq import NoResultError
+
+
+@broker.task
+async def my_task() -> None:
+    raise NoResultError
+```