Documentation: https://structlog-sentry-logger.readthedocs.io
Source Code: https://github.com/TeoZosa/structlog-sentry-logger
A multi-purpose, pre-configured,
performance-optimized structlog logger with
(optional) Sentry integration
via structlog-sentry.
- Makes logging as easy as using print statements, but prettier and easier to capture and filter!
- Highly opinionated! There are only two (2) distinct configurations.
- Structured logs in JSON format means they are ready to be ingested by many of your favorite log analysis tools!
- Cloud Logging compatible!
The pre-configured options include:
- ⌚ Timestamps
- UTC time in ISO 8601 format
(
YYYY-MM-DDTHH:MM:SS.ffffffZ)
- UTC time in ISO 8601 format
(
- 🚦 Log levels
- Added to the JSON context for filtering and categorization
- 🔍 Logger names
- Automatically assigned to namespaced versions of the initializing python
modules (
.pyfiles), relative to your project directory.- e.g., the logger in
docs_src/sentry_integration.pyis nameddocs_src.sentry_integration
- e.g., the logger in
- Automatically assigned to namespaced versions of the initializing python
modules (
- 🔎 Function names and line numbers where logging calls were made
🔥 Tip
For easier at-a-glance analysis, you can also sort log fields by key by exporting theSTRUCTLOG_SENTRY_LOGGER_KEY_SORTING_ONenvironment variable. Note, however, that this has a substantial (~1.6x) performance penalty.
- See
orjson'sOPT_SORT_KEYSdocumentation for more information.
structlog-sentry-logger is C-compiled and fully-tuned,
leveraging orjson
as the JSON serializer for lightning-fast logging (more than a 4x speedup over Python's
built-in JSON library1; see
here
for sample performance benchmarks). Don't let your obligate cross-cutting concerns
cripple performance any longer!
For further reference, see:
- "
orjson: Serialize" for benchmarks - "
structlog: Performance" for salient performance-related configurations.
Automatically add much richer context to your Sentry reports.
- Your entire logging context is sent as a Sentry event when
the
structlog-sentry-loggerlog level iserroror higher.- i.e.,
logger.error(""),logger.exception("")
- i.e.,
- See
structlog-sentryfor more details.
Table of Contents
- 🎉 Installation
- 🚀 Usage
- 📉 Output: Formatting & Storage
- 📋 Summary
- 📚 Further Reading
- 🔧 Development
- 🧑⚖️ Legal
pip install structlog-sentry-loggerOptionally, install Sentry integration with
pip install "structlog-sentry-logger[sentry]"Simply import and instantiate the logger:
import structlog_sentry_logger
LOGGER = structlog_sentry_logger.get_logger()Now you can start adding logs as easily as print statements:
LOGGER.info("Your log message", extra_field="extra_value")📝 Note
All the regular Python logging levels are supported.
Which automatically produces this:
{
"event": "Your log message",
"extra_field": "extra_value",
"funcName": "<module>",
"level": "info",
"lineno": 5,
"logger": "docs_src.pure_structlog_logging_without_sentry",
"timestamp": "2022-01-11T07:05:37.164744Z"
}If you installed the library with the optional Sentry integration you can incorporate
custom messages in your exception handling which will automatically be
reported to Sentry (thanks to the structlog-sentry
module). To enable this behavior, export the
STRUCTLOG_SENTRY_LOGGER_CLOUD_SENTRY_INTEGRATION_MODE_ON environment variable.
An easy way to do this is to put it into a local .env file2:
echo "STRUCTLOG_SENTRY_LOGGER_CLOUD_SENTRY_INTEGRATION_MODE_ON=" >> .env📝 ️Note
By default, only logs at error-level or above are sent to Sentry. If you want to set a different minimum log level, you can specify a valid Python log level via theSTRUCTLOG_SENTRY_LOGGER_SENTRY_LOG_LEVELenvironment variable.For example, to send all logs at warning-level or above to Sentry you would simply set
STRUCTLOG_SENTRY_LOGGER_SENTRY_LOG_LEVEL=WARNING
For a concrete example, given the following Python code:
import uuid
import structlog_sentry_logger
LOGGER = structlog_sentry_logger.get_logger()
curr_user_logger = LOGGER.bind(uuid=uuid.uuid4().hex) # LOGGER instance with bound UUID
try:
curr_user_logger.warn("A dummy error for testing purposes is about to be thrown!")
x = 1 / 0
except ZeroDivisionError as err:
ERR_MSG = (
"I threw an error on purpose for this example!\n"
"Now throwing another that explicitly chains from that one!"
)
curr_user_logger.exception(ERR_MSG)
raise RuntimeError(ERR_MSG) from errWe would get the following output:
{
"event": "A dummy error for testing purposes is about to be thrown!\n",
"funcName": "<module>",
"level": "warning",
"lineno": 12,
"logger": "docs_src.sentry_integration",
"sentry": "skipped",
"timestamp": "2022-01-06T04:50:07.627633Z",
"uuid": "fe2bdcbe2ed74432a87bc76bcdc9def4"
}
{
"event": "I threw an error on purpose for this example!\nNow throwing another that explicitly chains from that one!\n",
"exc_info": true,
"funcName": "<module>",
"level": "error",
"lineno": 19,
"logger": "docs_src.sentry_integration",
"sentry": "sent",
"sentry_id": null,
"timestamp": "2022-01-06T04:50:07.628316Z",
"uuid": "fe2bdcbe2ed74432a87bc76bcdc9def4"
}
Traceback (most recent call last):
File "/app/structlog-sentry-logger/docs_src/sentry_integration.py", line 10, in <module>
x = 1 / 0
ZeroDivisionError: division by zero
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
File "/app/structlog-sentry-logger/docs_src/sentry_integration.py", line 17, in <module>
raise RuntimeError(ERR_MSG) from err
RuntimeError: I threw an error on purpose for this example!
Now throwing another that explicitly chains from that one!The logger will attempt to infer if an application is running in a cloud environment by
inspecting for the presence of environment variables that may be automatically injected
by cloud providers (namely, KUBERNETES_SERVICE_HOST, GCP_PROJECT,
and GOOGLE_CLOUD_PROJECT).
If any of these environment variables are detected, log levels will be duplicated to a
reserved severity key in the emitted logs to enable parsing of the log level and the
remaining log context (as jsonPayload) by Cloud Logging
(see: Cloud Logging: Structured logging).
📝 ️Note
This behavior can also be manually enabled by adding theSTRUCTLOG_SENTRY_LOGGER_CLOUD_LOGGING_COMPATIBILITY_MODE_ONvariable to your environment, e.g., via a.envfile2.
⚠️ ️ Warning
If a user manually specifies a value for theseveritykey, it will be overwritten! Avoid using this key if possible to preempt any future issues.
The default behavior is to stream JSON logs directly to the standard output stream like a proper 12 Factor App.
For local development, it often helps to prettify logging to stdout and save JSON logs
to a .logs folder at the root of your project directory for later debugging. To enable
this behavior, export the STRUCTLOG_SENTRY_LOGGER_LOCAL_DEVELOPMENT_LOGGING_MODE_ON
environment variable, e.g., in your local .env file2:
echo "STRUCTLOG_SENTRY_LOGGER_LOCAL_DEVELOPMENT_LOGGING_MODE_ON=" >> .envIn doing so, with our previous exception handling example we would get:
That's it. Now no excuses. Get out there and program with pride knowing no one will laugh at you in production! For not logging properly, that is. You're on your own for that other observability stuff.
For convenience, implementation details of the below processes are abstracted away and encapsulated in single Make targets.
🔥 Tip
Invokingmakewithout any arguments will display auto-generated documentation on available commands.
Make sure you have Python 3.9+ and poetry
installed and configured.
To install the package and all dev dependencies, run:
make provision-environment🔥 Tip
Invoking the above withoutpoetryinstalled will emit a helpful error message letting you know how you can install poetry.
The projects's build.py file specifies which modules to package.
For manual per-module compilation, see: Mypyc Documentation: Getting started - Compiling and running
We use tox
and pytest for our test automation and testing
frameworks, respectively.
To invoke the tests, run:
make testRun mutation tests to validate test suite robustness (Optional):
make test-mutationsℹ️ Technical Details
Test time scales with the complexity of the codebase. Results are cached in.mutmut-cache, so once you get past the initial cold start problem, subsequent mutation test runs will be much faster; new mutations will only be applied to modified code paths.
We use pre-commit for our static analysis automation and
management framework.
To invoke the analyses and auto-formatting over all version-controlled files, run:
make lint🚨 Danger
CI will fail if either testing or code quality fail, so it is recommended to automatically run the above locally prior to every commit that is pushed.
To automatically run code quality validation on every commit (over to-be-committed files), run:
make install-pre-commit-hooks
⚠️ ️ Warning
This will prevent commits if any single pre-commit hook fails (unless it is allowed to fail) or a file is modified by an auto-formatting job; in the latter case, you may simply repeat the commit and it should pass.
make docs-clean docs-html🔥 Tip
For faster feedback loops, this will attempt to automatically open the newly built documentation static HTML in your browser.
Structlog-Sentry-Logger is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.
This project was generated from
@TeoZosa's
cookiecutter-cruft-poetry-tox-pre-commit-ci-cd
template.
Footnotes
-
Source: Choosing a faster JSON library for Python: Benchmarking ↩
-
This library uses
python-dotenvto automatically populate your environment with this variable (if it exists) from the local.envfile. Alternatively, you may usedirenvand a.envrcfile. A sample.envrcfile (with all features enabled) has been provided at the root of the repository (.envrc.sample). Ifdirenvis already installed, it's as simple as copying.envrc.sampleto the root of your project, editing it to reflect your desired configurations, renaming it to.envrc, and runningdirenv allow🎉 ↩ ↩2 ↩3