1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
Global Error Handler
====================
Overview
--------
This example shows how to use the global error handler.
The source files of these examples are available :scm_web:`here <docs/examples/error_handler/>`.
Preparation
-----------
This example will be executed in a separate virtual environment:
.. code:: sh
$ mkdir global_error_handler
$ virtualenv global_error_handler
$ source global_error_handler/bin/activate
Installation
------------
Here we install first ``opentelemetry-sdk``, the only dependency. Afterwards, 2
error handlers are installed: ``error_handler_0`` will handle
``ZeroDivisionError`` exceptions, ``error_handler_1`` will handle
``IndexError`` and ``KeyError`` exceptions.
.. code:: sh
$ pip install opentelemetry-sdk
$ git clone https://github.com/open-telemetry/opentelemetry-python.git
$ pip install -e opentelemetry-python/docs/examples/error_handler/error_handler_0
$ pip install -e opentelemetry-python/docs/examples/error_handler/error_handler_1
Execution
---------
An example is provided in the
``opentelemetry-python/docs/examples/error_handler/example.py``.
You can just run it, you should get output similar to this one:
.. code:: pytb
ErrorHandler0 handling a ZeroDivisionError
Traceback (most recent call last):
File "test.py", line 5, in <module>
1 / 0
ZeroDivisionError: division by zero
ErrorHandler1 handling an IndexError
Traceback (most recent call last):
File "test.py", line 11, in <module>
[1][2]
IndexError: list index out of range
ErrorHandler1 handling a KeyError
Traceback (most recent call last):
File "test.py", line 17, in <module>
{1: 2}[2]
KeyError: 2
Error handled by default error handler:
Traceback (most recent call last):
File "test.py", line 23, in <module>
assert False
AssertionError
No error raised
The ``opentelemetry-sdk.error_handler`` module includes documentation that
explains how this works. We recommend you read it also, here is just a small
summary.
In ``example.py`` we use ``GlobalErrorHandler`` as a context manager in several
places, for example:
.. code:: python
with GlobalErrorHandler():
{1: 2}[2]
Running that code will raise a ``KeyError`` exception.
``GlobalErrorHandler`` will "capture" that exception and pass it down to the
registered error handlers. If there is one that handles ``KeyError`` exceptions
then it will handle it. That can be seen in the result of the execution of
``example.py``:
.. code::
ErrorHandler1 handling a KeyError
Traceback (most recent call last):
File "test.py", line 17, in <module>
{1: 2}[2]
KeyError: 2
There is no registered error handler that can handle ``AssertionError``
exceptions so this kind of errors are handled by the default error handler
which just logs the exception to standard logging, as seen here:
.. code::
Error handled by default error handler:
Traceback (most recent call last):
File "test.py", line 23, in <module>
assert False
AssertionError
When no exception is raised, the code inside the scope of
``GlobalErrorHandler`` is executed normally:
.. code::
No error raised
Users can create Python packages that provide their own custom error handlers
and install them in their virtual environments before running their code which
instantiates ``GlobalErrorHandler`` context managers. ``error_handler_0`` and
``error_handler_1`` can be used as examples to create these custom error
handlers.
In order for the error handlers to be registered, they need to create a class
that inherits from ``opentelemetry.sdk.error_handler.ErrorHandler`` and at
least one ``Exception``-type class. For example, this is an error handler that
handles ``ZeroDivisionError`` exceptions:
.. code:: python
from opentelemetry.sdk.error_handler import ErrorHandler
from logging import getLogger
logger = getLogger(__name__)
class ErrorHandler0(ErrorHandler, ZeroDivisionError):
def handle(self, error: Exception, *args, **kwargs):
logger.exception("ErrorHandler0 handling a ZeroDivisionError")
To register this error handler, use the ``opentelemetry_error_handler`` entry
point in the setup of the error handler package:
.. code::
[options.entry_points]
opentelemetry_error_handler =
error_handler_0 = error_handler_0:ErrorHandler0
This entry point should point to the error handler class, ``ErrorHandler0`` in
this case.
|
