| 1 |
.. _logging-usage: |
| 2 |
|
| 3 |
Logging |
| 4 |
======= |
| 5 |
|
| 6 |
Application and request level loggers can be configured using the :class:`~litestar.logging.config.LoggingConfig`: |
| 7 |
|
| 8 |
.. code-block:: python |
| 9 |
|
| 10 |
import logging |
| 11 |
|
| 12 |
from litestar import Litestar, Request, get |
| 13 |
from litestar.logging import LoggingConfig |
| 14 |
|
| 15 |
|
| 16 |
@get("/") |
| 17 |
def my_router_handler(request: Request) -> None: |
| 18 |
request.logger.info("inside a request") |
| 19 |
return None |
| 20 |
|
| 21 |
|
| 22 |
logging_config = LoggingConfig( |
| 23 |
root={"level": "INFO", "handlers": ["queue_listener"]}, |
| 24 |
formatters={ |
| 25 |
"standard": {"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"} |
| 26 |
}, |
| 27 |
log_exceptions="always", |
| 28 |
) |
| 29 |
|
| 30 |
app = Litestar(route_handlers=[my_router_handler], logging_config=logging_config) |
| 31 |
|
| 32 |
.. attention:: |
| 33 |
|
| 34 |
Litestar configures a non-blocking ``QueueListenerHandler`` which |
| 35 |
is keyed as ``queue_listener`` in the logging configuration. The above example is using this handler, |
| 36 |
which is optimal for async applications. Make sure to use it in your own loggers as in the above example. |
| 37 |
|
| 38 |
.. attention:: |
| 39 |
|
| 40 |
Exceptions won't be logged by default, except in debug mode. Make sure to use ``log_exceptions="always"`` as in the |
| 41 |
example above to log exceptions if you need it. |
| 42 |
|
| 43 |
Controlling Exception Logging |
| 44 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 45 |
|
| 46 |
While ``log_exceptions`` controls when exceptions are logged, sometimes you may want to suppress stack traces for specific |
| 47 |
exception types or HTTP status codes. The ``disable_stack_trace`` parameter allows you to specify a set of exception types |
| 48 |
or status codes that should not generate stack traces in logs: |
| 49 |
|
| 50 |
.. code-block:: python |
| 51 |
|
| 52 |
from litestar import Litestar |
| 53 |
from litestar.logging import LoggingConfig |
| 54 |
|
| 55 |
# Don't log stack traces for 404 errors and ValueError exceptions |
| 56 |
logging_config = LoggingConfig( |
| 57 |
debug=True, |
| 58 |
disable_stack_trace={404, ValueError}, |
| 59 |
) |
| 60 |
|
| 61 |
app = Litestar(logging_config=logging_config) |
| 62 |
|
| 63 |
This is particularly useful for common exceptions that you expect in normal operation and don't need detailed stack traces for. |
| 64 |
|
| 65 |
Using Python standard library |
| 66 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 67 |
|
| 68 |
`logging <https://docs.python.org/3/howto/logging.html>`_ is Python's builtin standard logging library and can be |
| 69 |
configured through ``LoggingConfig``. |
| 70 |
|
| 71 |
The ``LoggingConfig.configure()`` method returns a reference to ``logging.getLogger`` which can be used to access a |
| 72 |
logger instance. Thus, the root logger can retrieved with ``logging_config.configure()()`` as shown in the example |
| 73 |
below: |
| 74 |
|
| 75 |
.. code-block:: python |
| 76 |
|
| 77 |
import logging |
| 78 |
|
| 79 |
from litestar import Litestar, Request, get |
| 80 |
from litestar.logging import LoggingConfig |
| 81 |
|
| 82 |
logging_config = LoggingConfig( |
| 83 |
root={"level": "INFO", "handlers": ["queue_listener"]}, |
| 84 |
formatters={ |
| 85 |
"standard": {"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"} |
| 86 |
}, |
| 87 |
log_exceptions="always", |
| 88 |
) |
| 89 |
|
| 90 |
logger = logging_config.configure()() |
| 91 |
|
| 92 |
|
| 93 |
@get("/") |
| 94 |
def my_router_handler(request: Request) -> None: |
| 95 |
request.logger.info("inside a request") |
| 96 |
logger.info("here too") |
| 97 |
|
| 98 |
|
| 99 |
app = Litestar( |
| 100 |
route_handlers=[my_router_handler], |
| 101 |
logging_config=logging_config, |
| 102 |
) |
| 103 |
|
| 104 |
The above example is the same as using logging without the litestar ``LoggingConfig``. |
| 105 |
|
| 106 |
.. code-block:: python |
| 107 |
|
| 108 |
import logging |
| 109 |
|
| 110 |
from litestar import Litestar, Request, get |
| 111 |
from litestar.logging.config import LoggingConfig |
| 112 |
|
| 113 |
|
| 114 |
def get_logger(mod_name: str) -> logging.Logger: |
| 115 |
"""Return logger object.""" |
| 116 |
format = "%(asctime)s: %(name)s: %(levelname)s: %(message)s" |
| 117 |
logger = logging.getLogger(mod_name) |
| 118 |
# Writes to stdout |
| 119 |
ch = logging.StreamHandler() |
| 120 |
ch.setLevel(logging.INFO) |
| 121 |
ch.setFormatter(logging.Formatter(format)) |
| 122 |
logger.addHandler(ch) |
| 123 |
return logger |
| 124 |
|
| 125 |
|
| 126 |
logger = get_logger(__name__) |
| 127 |
|
| 128 |
|
| 129 |
@get("/") |
| 130 |
def my_router_handler(request: Request) -> None: |
| 131 |
logger.info("logger inside a request") |
| 132 |
|
| 133 |
|
| 134 |
app = Litestar( |
| 135 |
route_handlers=[my_router_handler], |
| 136 |
) |
| 137 |
|
| 138 |
|
| 139 |
Using Picologging |
| 140 |
^^^^^^^^^^^^^^^^^ |
| 141 |
|
| 142 |
`Picologging <https://github.com/microsoft/picologging>`_ is a high performance logging library that is developed by |
| 143 |
Microsoft. Litestar will default to using this library automatically if its installed - requiring zero configuration on |
| 144 |
the part of the user. That is, if ``picologging`` is present the previous example will work with it automatically. |
| 145 |
|
| 146 |
Using StructLog |
| 147 |
^^^^^^^^^^^^^^^ |
| 148 |
|
| 149 |
`StructLog <https://www.structlog.org/en/stable/>`_ is a powerful structured-logging library. Litestar ships with a |
| 150 |
dedicated logging plugin and config for using it: |
| 151 |
|
| 152 |
.. code-block:: python |
| 153 |
|
| 154 |
from litestar import Litestar, Request, get |
| 155 |
from litestar.plugins.structlog import StructlogPlugin |
| 156 |
|
| 157 |
|
| 158 |
@get("/") |
| 159 |
def my_router_handler(request: Request) -> None: |
| 160 |
request.logger.info("inside a request") |
| 161 |
return None |
| 162 |
|
| 163 |
|
| 164 |
structlog_plugin = StructlogPlugin() |
| 165 |
|
| 166 |
app = Litestar(route_handlers=[my_router_handler], plugins=[StructlogPlugin()]) |
| 167 |
|
| 168 |
Subclass Logging Configs |
| 169 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
| 170 |
|
| 171 |
You can easily create you own ``LoggingConfig`` class by subclassing |
| 172 |
:class:`BaseLoggingConfig <.logging.config.BaseLoggingConfig>` and implementing the ``configure`` method. |