Structlog-Sentry-Loggerο
Documentation: https://structlog-sentry-logger.readthedocs.io
Source Code: https://github.com/TeoZosa/structlog-sentry-logger
π§βπ« Overviewο
A multi-purpose, pre-configured,
performance-optimized structlog
logger with
(optional) Sentry integration
via structlog-sentry
.
β¨ Featuresο
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!
π What You Getο
πͺ Powerful Automatic Context Fieldsο
The pre-configured options include:
βοΈ Timestamps
UTC time in ISO 8601 format (
YYYY-MM-DDTHH:MM:SS.ffffffZ
)
π¦ Log levels
Added to the JSON context for filtering and categorization
ποΈ Logger names
Automatically assigned to namespaced versions of the initializing python modules (
.py
files), relative to your project directory.e.g., the logger in
docs_src/sentry_integration.py
is nameddocs_src.sentry_integration
π 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_ON
environment variable. Note, however, that this has a substantial (~1.6x
) performance penalty.
See
orjson
βsOPT_SORT_KEYS
documentation for more information.
β‘οΈ Performanceο
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 library[1]; 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.
π€ Built-in Sentry Integration (Optional)ο
Automatically add much richer context to your Sentry reports.
Your entire logging context is sent as a Sentry event when the
structlog-sentry-logger
log level iserror
or higher.i.e.,
logger.error("")
,logger.exception("")
See
structlog-sentry
for more details.
Table of Contents
π Installationο
pip install structlog-sentry-logger
Optionally, install Sentry integration with
pip install "structlog-sentry-logger[sentry]"
π Usageο
π Pure structlog
Logging (Without 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"
}
π€οΈ Log Custom Context Directly to Sentry (optional)ο
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
file[2]:
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_LEVEL
environment 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 err
We 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!
βοΈ Cloud Logging Compatibilityο
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_ON
variable to your environment, e.g., via a.env
file[2].
β οΈοΈ Warning
If a user manually specifies a value for theseverity
key, it will be overwritten! Avoid using this key if possible to preempt any future issues.
π Output: Formatting & Storageο
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
file[2]:
echo "STRUCTLOG_SENTRY_LOGGER_LOCAL_DEVELOPMENT_LOGGING_MODE_ON=" >> .env
In doing so, with our previous exception handling example we would get:
ποΈ Summaryο
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.
ποΈ Further Readingο
1οΈβ£ structlog
: Structured Logging for Pythonο
2οΈβ£ Sentry
: Monitor and fix crashes in realtimeο
3οΈβ£ structlog-sentry
: Provides the structlog
integration for Sentryο
π§ Developmentο
For convenience, implementation details of the below processes are abstracted away and encapsulated in single Make targets.
π₯ Tip
Invokingmake
without any arguments will display auto-generated documentation on available commands.
ποΈ Package and Dependencies Installationο
Make sure you have Python 3.8+ and poetry
installed and configured.
To install the package and all dev dependencies, run:
make provision-environment
π₯ Tip
Invoking the above withoutpoetry
installed will emit a helpful error message letting you know how you can install poetry.
π¦οΈ Python Module to C-Extension Compilationο
The projectsβs build.py file specifies which modules to package.
For manual per-module compilation, see: Mypyc Documentation: Getting started - Compiling and running
β Testingο
We use tox
and pytest
for our test automation and testing
frameworks, respectively.
To invoke the tests, run:
make test
Run 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.
π¨ Code Qualityο
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.
π Automate via Git Pre-Commit Hooksο
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.
π Documentationο
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.
π§ββοΈ Legalο
π Licenseο
Structlog-Sentry-Logger is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.
π₯ Creditsο
This project was generated from
@TeoZosa
βs
cookiecutter-cruft-poetry-tox-pre-commit-ci-cd
template.