# Instrumenting
## install
- install with your favorite Python package manager
```sh
pip3 install shopcloud-django-instrumenting
```
### LogRequestMiddleware
add additional Information from request in AppEngine to Log
#### usage
add to MIDDLEWARE in django-app settings.py:
```python
MIDDLEWARE = [
...
'shopcloud_django_instrumenting.middleware.LogRequestMiddleware',
]
```
## tracing
```py
from shopcloud_django_instrumenting import tracing
tr = tracing.Tracer('name_of_service', 'name_of_operation')
with tr.start_span('event.processing') as span:
pass
data = tr.close()
```
## error management
A special layer on top of the API is the error boundary within the with blocks of spans. This layer catches exceptions and prints them. The pattern here is to catch all runtime errors and return a 422 status, indicating that an unexpected error has occurred, not a validation error. If you need to return validation data to the user, you must return a Result object on your own.
```py
@action(detail=True, methods=["post"], url_path="my-action")
def my_action(self, request, pk):
tr = tracing.DjangoAPITracer(request)
serializer = serializers.ProductSyncSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
with tr.start_span('proceed') as span:
raise Exception('something unhandle')
trace_data = tr.close()
return Response({
'trace': trace_data,
}, status=status.HTTP_201_CREATED if tr.is_success else status.HTTP_422_UNPROCESSABLE_ENTITY)
```
Another pattern to note is that every `with` block should contain a repeatable operation. You can create structures where you can run blocks side by side and only repeat some of them. However, be careful: while the `with` block catches exceptions, it may not guarantee that all variables are set.
```py
tr = tracing.DjangoAPITracer(request)
is_a_success = False
is_b_success = False
is_c_success = False
with tr.start_span('A') as span_a:
is_a_success = False
with tr.start_span('B') as span_b:
is_b_success = True
with tr.start_span('C') as span_c:
if is_a_success:
pass
```
## develop
```sh
$ pytest
$ pip3 install coverage
# shell report
$ coverage run -m pytest && coverage report --show-missing
# html report
$ coverage run -m pytest && coverage html
$ cd htmlcov
$ python3 -m http.server
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Talk-Point/shopcloud-django-instrumenting",
"name": "shopcloud-django-instrumenting",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Konstantin Stoldt",
"author_email": "konstantin.stoldt@talk-point.de",
"download_url": "https://files.pythonhosted.org/packages/82/9a/7e29f807fd167539d313af663bf9ba8ee0d7b721a0b63a93968ce3142187/shopcloud_django_instrumenting-1.4.0.tar.gz",
"platform": null,
"description": "# Instrumenting\n\n## install\n\n- install with your favorite Python package manager\n\n```sh\npip3 install shopcloud-django-instrumenting\n```\n\n### LogRequestMiddleware\n\nadd additional Information from request in AppEngine to Log\n\n#### usage\n\nadd to MIDDLEWARE in django-app settings.py:\n\n```python\nMIDDLEWARE = [\n ...\n 'shopcloud_django_instrumenting.middleware.LogRequestMiddleware',\n]\n```\n\n## tracing\n\n```py\nfrom shopcloud_django_instrumenting import tracing\n\ntr = tracing.Tracer('name_of_service', 'name_of_operation')\nwith tr.start_span('event.processing') as span:\n pass\n\ndata = tr.close()\n```\n\n## error management\n\nA special layer on top of the API is the error boundary within the with blocks of spans. This layer catches exceptions and prints them. The pattern here is to catch all runtime errors and return a 422 status, indicating that an unexpected error has occurred, not a validation error. If you need to return validation data to the user, you must return a Result object on your own.\n\n```py\n@action(detail=True, methods=[\"post\"], url_path=\"my-action\")\ndef my_action(self, request, pk):\n tr = tracing.DjangoAPITracer(request)\n\n serializer = serializers.ProductSyncSerializer(data=request.data)\n serializer.is_valid(raise_exception=True)\n\n with tr.start_span('proceed') as span:\n raise Exception('something unhandle')\n\n trace_data = tr.close()\n return Response({\n 'trace': trace_data,\n }, status=status.HTTP_201_CREATED if tr.is_success else status.HTTP_422_UNPROCESSABLE_ENTITY)\n\n```\n\nAnother pattern to note is that every `with` block should contain a repeatable operation. You can create structures where you can run blocks side by side and only repeat some of them. However, be careful: while the `with` block catches exceptions, it may not guarantee that all variables are set.\n\n\n```py\ntr = tracing.DjangoAPITracer(request)\n\nis_a_success = False\nis_b_success = False\nis_c_success = False\n\nwith tr.start_span('A') as span_a:\n is_a_success = False\n\nwith tr.start_span('B') as span_b:\n is_b_success = True\n\nwith tr.start_span('C') as span_c:\n if is_a_success:\n pass\n```\n\n## develop\n\n```sh\n$ pytest\n$ pip3 install coverage\n# shell report\n$ coverage run -m pytest && coverage report --show-missing\n# html report\n$ coverage run -m pytest && coverage html\n$ cd htmlcov\n$ python3 -m http.server\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django tool for instrumenting",
"version": "1.4.0",
"project_urls": {
"Homepage": "https://github.com/Talk-Point/shopcloud-django-instrumenting"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "42d232fc138517c51a5a06096341d22ef82e53f2a05573377815ee417ec01dc1",
"md5": "c6f64fae59f40d5bcbddee2592b7468b",
"sha256": "e574757d34520e13d2e1a413b7aee3eeb1bec2cfd0de5b266a18654496ab35ae"
},
"downloads": -1,
"filename": "shopcloud_django_instrumenting-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c6f64fae59f40d5bcbddee2592b7468b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5892,
"upload_time": "2024-01-27T11:38:30",
"upload_time_iso_8601": "2024-01-27T11:38:30.555161Z",
"url": "https://files.pythonhosted.org/packages/42/d2/32fc138517c51a5a06096341d22ef82e53f2a05573377815ee417ec01dc1/shopcloud_django_instrumenting-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "829a7e29f807fd167539d313af663bf9ba8ee0d7b721a0b63a93968ce3142187",
"md5": "24d337526c218ff2524715c8f6e46e5e",
"sha256": "4e6a04d4fbcbc271c73c19b36aa7f140248f99822597d72e332de54445dff69d"
},
"downloads": -1,
"filename": "shopcloud_django_instrumenting-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "24d337526c218ff2524715c8f6e46e5e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5384,
"upload_time": "2024-01-27T11:38:33",
"upload_time_iso_8601": "2024-01-27T11:38:33.024508Z",
"url": "https://files.pythonhosted.org/packages/82/9a/7e29f807fd167539d313af663bf9ba8ee0d7b721a0b63a93968ce3142187/shopcloud_django_instrumenting-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-27 11:38:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Talk-Point",
"github_project": "shopcloud-django-instrumenting",
"github_not_found": true,
"lcname": "shopcloud-django-instrumenting"
}
JSON
