Debian Codegraph @

docs/usage/logging.rst

raw
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.