Metadata-Version: 2.4
Name: shopcloud_django_instrumenting
Version: 1.5.0
Summary: Django tool for instrumenting
Home-page: https://github.com/Talk-Point/shopcloud-django-instrumenting
Author: Konstantin Stoldt
Author-email: konstantin.stoldt@talk-point.de
License: MIT
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django<7.0,>=5.2
Requires-Dist: djangorestframework
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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
```
