# Exception Reports
[](https://pepy.tech/project/exception-reports)
[](https://pypi.org/project/exception-reports/)
[](https://github.com/ambv/black)
Generate an interactive stack trace that includes variable state at each level.
## Features
- Get the variable state you need to understand what caused an exception
- Normal python tracebacks only show the stack up to where an exception was caught,
this library shows the entire traceback.
- Get full stack traces for logger.error calls (not just for exceptions)
- Exception reports can output to either the local filesystem or S3
- Shows beginning and end of large values (django's report only shows beginning)
- Decorator available for debugging or cases where you don't control logging.
## Installation
`pip install exception_reports`
## Usage
Basic Setup (local filesystem)
```python
import logging
import sys
from logging.config import dictConfig
from exception_reports.logs import uncaught_exception_handler, DEFAULT_LOGGING_CONFIG
# configure logging to use our filter and formatter
dictConfig(DEFAULT_LOGGING_CONFIG)
logger = logging.getLogger(__name__)
# configure uncaught exceptions to be logged
sys.excepthook = uncaught_exception_handler
raise Exception("YOLO!!!!")
```
Change report output location
```python
import logging
import sys
from logging.config import dictConfig
from exception_reports.logs import uncaught_exception_handler, ExtraDataLogFormatter, AddExceptionReportFilter
from exception_reports.storages import LocalErrorStorage
LOGGING_CONFIG = {
'version': 1,
'disable_existing_loggers': False,
'formatters': {
'standard': {
'()': ExtraDataLogFormatter,
'format': '%(asctime)s %(process)d [%(levelname)s] %(name)s.%(funcName)s: %(message)s; %(data_as_kv)s'
},
},
'filters': {
'add_exception_report': {
'()': AddExceptionReportFilter,
'storage_backend': LocalErrorStorage(output_path='/myproject/bug-reports/')
},
},
'handlers': {
'console': {
'level': 'DEBUG',
'filters': ['add_exception_report'],
'class': 'logging.StreamHandler',
'formatter': 'standard'
},
},
'loggers': {
'': {
'handlers': ['console'],
'level': 'INFO',
'propagate': True
}
}
}
# configure logging to use our filter and formatter
dictConfig(LOGGING_CONFIG)
logger = logging.getLogger(__name__)
# configure uncaught exceptions to be logged
sys.excepthook = uncaught_exception_handler
raise Exception("YOLO!!!!")
```
Output reports to S3
```python
import logging
import sys
from logging.config import dictConfig
from exception_reports.logs import uncaught_exception_handler, ExtraDataLogFormatter, AddExceptionReportFilter
from exception_reports.storages import S3ErrorStorage
LOGGING_CONFIG = {
'version': 1,
'disable_existing_loggers': False,
'formatters': {
'standard': {
'()': ExtraDataLogFormatter,
'format': '%(asctime)s %(process)d [%(levelname)s] %(name)s.%(funcName)s: %(message)s; %(data_as_kv)s'
},
},
'filters': {
'add_exception_report': {
'()': AddExceptionReportFilter,
'storage_backend': S3ErrorStorage(
access_key='MY_ACCESS_KEY',
secret_key='MY_SECRET_KEY',
bucket='MY_BUCKET',
prefix='bugs'
),
},
},
'handlers': {
'console': {
'level': 'DEBUG',
'filters': ['add_exception_report'],
'class': 'logging.StreamHandler',
'formatter': 'standard'
},
},
'loggers': {
'': {
'handlers': ['console'],
'level': 'INFO',
'propagate': True
}
}
}
# configure logging to use our filter and formatter
dictConfig(LOGGING_CONFIG)
logger = logging.getLogger(__name__)
# configure uncaught exceptions to be logged
sys.excepthook = uncaught_exception_handler
raise Exception("YOLO!!!!")
```
### Decorators
Useful to do some quick debugging, only get reports for specific exceptions, or when you don't control the
logging config. Can be used to provide debugging information in UDFs in PySpark.
```python
from exception_reports.decorators import exception_report
from exception_reports.storages import S3ErrorStorage
# defaults to local file storage
@exception_report()
def foobar(text):
raise Exception("bad things!!")
# s3 storage
storage_backend = S3ErrorStorage(
access_key='access_key',
secret_key='secret_key',
bucket='my_bucket',
prefix='all-exceptions/'
)
@exception_report(storage_backend=storage_backend)
def foobar(text):
raise Exception("bad things!!")
# custom decorator
def my_exception_report(f):
storage_backend = S3ErrorStorage(
access_key='access_key',
secret_key='secret_key',
bucket='my_bucket',
prefix='all-exceptions/'
)
return exception_report(storage_backend=storage_backend)(f)
@my_exception_report
def foobar(text):
raise Exception("bad things!!")
```
## Updating package on pypi
- `make deploy`
## Changelog
#### 2.0.0
- feature: support python 3.8 through 3.11
- build: update to latest version of dependencies
- ci: switch to github actions
- style: fix lints
- fix: support newer jinja2 (autoescape no longer an extension)
#### 1.1.0
- Bugfix. tinys3 was abandoned. switching to boto3
- Dev: Added black autoformatter.
- Dev: Added makefile with `test`, `lint`, and `autoformat` commands
- Dev: Autoformatted code, fixed lint issues
#### 1.0.0
- Feature: Default to not showing less usefull "full stacktrace"
- Feature: Add platform data to report
- Feature: Allow specification of a data_processor function that can alter the exception data
- Feature: Safer filenames (no colon characters)
- Bugfix: Handle all builtin exception types when attaching a message to an exception object
- Refactor: Combine repetitive code into create_exception_report
- Refactor: Simplify logging API
- Refactor: Split ExceptionReporter into component functions.
#### 0.4.0
- Ensure the JSON version of exception data has the same data as the html version
- Add decorator support for outputting json versions
- bugfix: Handle exceptions throw from `Exception` directly
#### 0.3.1
- If an error happens while loading the source context it's now gracefully handled instead of stopping the report from being generated
#### 0.3.0
- Can now handle exceptions that require special init args. Uses a modified class instead of creating a new exception instance. Thanks to @munro for noticing
the issue and finding the right solution.
Raw data
{
"_id": null,
"home_page": "https://github.com/brycedrennan/exception-reports",
"name": "exception-reports",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "exception handler,exceptions,error logs",
"author": "Bryce Drennan",
"author_email": "exception_reports@brycedrennan.org",
"download_url": "https://github.com/brycedrennan/exception-reports/tarball/2.0.0",
"platform": null,
"description": "# Exception Reports\n\n[](https://pepy.tech/project/exception-reports)\n[](https://pypi.org/project/exception-reports/)\n\n[](https://github.com/ambv/black)\n\nGenerate an interactive stack trace that includes variable state at each level.\n\n## Features\n\n - Get the variable state you need to understand what caused an exception\n - Normal python tracebacks only show the stack up to where an exception was caught, \n this library shows the entire traceback.\n - Get full stack traces for logger.error calls (not just for exceptions)\n - Exception reports can output to either the local filesystem or S3\n - Shows beginning and end of large values (django's report only shows beginning)\n - Decorator available for debugging or cases where you don't control logging.\n\n## Installation\n\n`pip install exception_reports`\n\n## Usage\n\nBasic Setup (local filesystem)\n```python\nimport logging\nimport sys\nfrom logging.config import dictConfig\n\nfrom exception_reports.logs import uncaught_exception_handler, DEFAULT_LOGGING_CONFIG\n\n# configure logging to use our filter and formatter\ndictConfig(DEFAULT_LOGGING_CONFIG)\n\nlogger = logging.getLogger(__name__)\n\n# configure uncaught exceptions to be logged\nsys.excepthook = uncaught_exception_handler\n\nraise Exception(\"YOLO!!!!\")\n```\n\nChange report output location\n\n```python\nimport logging\nimport sys\nfrom logging.config import dictConfig\n\nfrom exception_reports.logs import uncaught_exception_handler, ExtraDataLogFormatter, AddExceptionReportFilter\nfrom exception_reports.storages import LocalErrorStorage\n\nLOGGING_CONFIG = {\n 'version': 1,\n 'disable_existing_loggers': False,\n 'formatters': {\n 'standard': {\n '()': ExtraDataLogFormatter,\n 'format': '%(asctime)s %(process)d [%(levelname)s] %(name)s.%(funcName)s: %(message)s; %(data_as_kv)s'\n },\n },\n 'filters': {\n 'add_exception_report': {\n '()': AddExceptionReportFilter,\n 'storage_backend': LocalErrorStorage(output_path='/myproject/bug-reports/')\n },\n },\n 'handlers': {\n 'console': {\n 'level': 'DEBUG',\n 'filters': ['add_exception_report'],\n 'class': 'logging.StreamHandler',\n 'formatter': 'standard'\n },\n },\n 'loggers': {\n '': {\n 'handlers': ['console'],\n 'level': 'INFO',\n 'propagate': True\n }\n }\n}\n\n# configure logging to use our filter and formatter\ndictConfig(LOGGING_CONFIG)\n\nlogger = logging.getLogger(__name__)\n\n# configure uncaught exceptions to be logged\nsys.excepthook = uncaught_exception_handler\n\nraise Exception(\"YOLO!!!!\")\n```\n\nOutput reports to S3\n\n```python\nimport logging\nimport sys\nfrom logging.config import dictConfig\n\nfrom exception_reports.logs import uncaught_exception_handler, ExtraDataLogFormatter, AddExceptionReportFilter\nfrom exception_reports.storages import S3ErrorStorage\n\nLOGGING_CONFIG = {\n 'version': 1,\n 'disable_existing_loggers': False,\n 'formatters': {\n 'standard': {\n '()': ExtraDataLogFormatter,\n 'format': '%(asctime)s %(process)d [%(levelname)s] %(name)s.%(funcName)s: %(message)s; %(data_as_kv)s'\n },\n },\n 'filters': {\n 'add_exception_report': {\n '()': AddExceptionReportFilter,\n 'storage_backend': S3ErrorStorage(\n access_key='MY_ACCESS_KEY', \n secret_key='MY_SECRET_KEY', \n bucket='MY_BUCKET',\n prefix='bugs'\n ),\n },\n },\n 'handlers': {\n 'console': {\n 'level': 'DEBUG',\n 'filters': ['add_exception_report'],\n 'class': 'logging.StreamHandler',\n 'formatter': 'standard'\n },\n },\n 'loggers': {\n '': {\n 'handlers': ['console'],\n 'level': 'INFO',\n 'propagate': True\n }\n }\n}\n\n# configure logging to use our filter and formatter\ndictConfig(LOGGING_CONFIG)\n\nlogger = logging.getLogger(__name__)\n\n# configure uncaught exceptions to be logged\nsys.excepthook = uncaught_exception_handler\n\nraise Exception(\"YOLO!!!!\")\n```\n\n### Decorators\n\nUseful to do some quick debugging, only get reports for specific exceptions, or when you don't control the\nlogging config. Can be used to provide debugging information in UDFs in PySpark. \n```python\nfrom exception_reports.decorators import exception_report\nfrom exception_reports.storages import S3ErrorStorage\n\n# defaults to local file storage\n@exception_report()\ndef foobar(text):\n raise Exception(\"bad things!!\")\n\n\n# s3 storage\nstorage_backend = S3ErrorStorage(\n access_key='access_key',\n secret_key='secret_key',\n bucket='my_bucket',\n prefix='all-exceptions/'\n)\n\n@exception_report(storage_backend=storage_backend)\ndef foobar(text):\n raise Exception(\"bad things!!\")\n\n\n# custom decorator\ndef my_exception_report(f):\n storage_backend = S3ErrorStorage(\n access_key='access_key',\n secret_key='secret_key',\n bucket='my_bucket',\n prefix='all-exceptions/'\n )\n\n return exception_report(storage_backend=storage_backend)(f)\n\n@my_exception_report\ndef foobar(text):\n raise Exception(\"bad things!!\")\n```\n\n## Updating package on pypi\n - `make deploy`\n \n\n## Changelog\n\n#### 2.0.0\n - feature: support python 3.8 through 3.11\n - build: update to latest version of dependencies\n - ci: switch to github actions\n - style: fix lints\n - fix: support newer jinja2 (autoescape no longer an extension)\n\n#### 1.1.0\n - Bugfix. tinys3 was abandoned. switching to boto3\n - Dev: Added black autoformatter.\n - Dev: Added makefile with `test`, `lint`, and `autoformat` commands\n - Dev: Autoformatted code, fixed lint issues\n\n#### 1.0.0\n - Feature: Default to not showing less usefull \"full stacktrace\"\n - Feature: Add platform data to report\n - Feature: Allow specification of a data_processor function that can alter the exception data\n - Feature: Safer filenames (no colon characters)\n - Bugfix: Handle all builtin exception types when attaching a message to an exception object\n - Refactor: Combine repetitive code into create_exception_report\n - Refactor: Simplify logging API\n - Refactor: Split ExceptionReporter into component functions.\n\n#### 0.4.0\n - Ensure the JSON version of exception data has the same data as the html version\n - Add decorator support for outputting json versions\n - bugfix: Handle exceptions throw from `Exception` directly\n\n#### 0.3.1\n - If an error happens while loading the source context it's now gracefully handled instead of stopping the report from being generated\n\n#### 0.3.0\n - Can now handle exceptions that require special init args. Uses a modified class instead of creating a new exception instance. Thanks to @munro for noticing \n the issue and finding the right solution.\n",
"bugtrack_url": null,
"license": "",
"summary": "Interactive stacktraces with variable state at each level.",
"version": "2.0.0",
"project_urls": {
"Download": "https://github.com/brycedrennan/exception-reports/tarball/2.0.0",
"Homepage": "https://github.com/brycedrennan/exception-reports"
},
"split_keywords": [
"exception handler",
"exceptions",
"error logs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c31bcb07d2248ce3faeb9dd2b453b96c363afd9b3f5fe5daafe0fe300c5163c7",
"md5": "ecf71c03ae07a960c8140f1a3f4db456",
"sha256": "3f773e930089c95dc59057d5e25e746e946d8fecdefdcfcf3cb50205a2809123"
},
"downloads": -1,
"filename": "exception_reports-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ecf71c03ae07a960c8140f1a3f4db456",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17032,
"upload_time": "2023-07-16T05:35:17",
"upload_time_iso_8601": "2023-07-16T05:35:17.344606Z",
"url": "https://files.pythonhosted.org/packages/c3/1b/cb07d2248ce3faeb9dd2b453b96c363afd9b3f5fe5daafe0fe300c5163c7/exception_reports-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-16 05:35:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "brycedrennan",
"github_project": "exception-reports",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "exception-reports"
}
JSON
