Add Global Error Handler

docs/examples/error_hander/README.rst

@@ -0,0 +1,153 @@
+Global Error Handler
+====================
+
+Overview
+--------
+
+This example shows how to use the global 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 exectued 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.

docs/examples/error_hander/error_handler_0/README.rst

@@ -0,0 +1,4 @@
+Error Handler 0
+===============
+
+This is just an error handler for this example.

docs/examples/error_hander/error_handler_0/setup.cfg

@@ -0,0 +1,46 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+[metadata]
+name = error-handler-0
+description = This is just an error handler example package
+author = OpenTelemetry Authors
+author_email = [email protected]
+platforms = any
+license = Apache-2.0
+classifiers =
+    Development Status :: 4 - Beta
+    Intended Audience :: Developers
+    License :: OSI Approved :: Apache Software License
+    Programming Language :: Python
+    Programming Language :: Python :: 3
+    Programming Language :: Python :: 3.5
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+
+[options]
+python_requires = >=3.5
+package_dir=
+    =src
+packages=find_namespace:
+install_requires =
+    opentelemetry-sdk == 0.14.dev0
+
+[options.packages.find]
+where = src
+
+[options.entry_points]
+opentelemetry_error_handler =
+    error_handler_0 = error_handler_0:ErrorHandler0

docs/examples/error_hander/error_handler_0/setup.py

@@ -0,0 +1,26 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+
+import setuptools
+
+BASE_DIR = os.path.dirname(__file__)
+VERSION_FILENAME = os.path.join(
+    BASE_DIR, "src", "error_handler_0", "version.py"
+)
+PACKAGE_INFO = {}
+with open(VERSION_FILENAME) as f:
+    exec(f.read(), PACKAGE_INFO)
+
+setuptools.setup(version=PACKAGE_INFO["__version__"])

docs/examples/error_hander/error_handler_0/src/error_handler_0/__init__.py

@@ -0,0 +1,25 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from logging import getLogger
+
+from opentelemetry.sdk.error_handler import ErrorHandler
+
+logger = getLogger(__name__)
+
+
+class ErrorHandler0(ErrorHandler, ZeroDivisionError):
+    def _handle(self, error: Exception, *args, **kwargs):
+
+        logger.exception("ErrorHandler0 handling a ZeroDivisionError")

docs/examples/error_hander/error_handler_0/src/error_handler_0/version.py

@@ -0,0 +1,15 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+__version__ = "0.14.dev0"

docs/examples/error_hander/error_handler_1/README.rst

@@ -0,0 +1,4 @@
+Error Handler 1
+===============
+
+This is just an error handler for this example.

docs/examples/error_hander/error_handler_1/setup.cfg

@@ -0,0 +1,46 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+[metadata]
+name = error_handler_1
+description = This is just an error handler example package
+author = OpenTelemetry Authors
+author_email = [email protected]
+platforms = any
+license = Apache-2.0
+classifiers =
+    Development Status :: 4 - Beta
+    Intended Audience :: Developers
+    License :: OSI Approved :: Apache Software License
+    Programming Language :: Python
+    Programming Language :: Python :: 3
+    Programming Language :: Python :: 3.5
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+
+[options]
+python_requires = >=3.5
+package_dir=
+    =src
+packages=find_namespace:
+install_requires =
+    opentelemetry-sdk == 0.14.dev0
+
+[options.packages.find]
+where = src
+
+[options.entry_points]
+opentelemetry_error_handler =
+    error_handler_1 = error_handler_1:ErrorHandler1

docs/examples/error_hander/error_handler_1/setup.py

@@ -0,0 +1,26 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+
+import setuptools
+
+BASE_DIR = os.path.dirname(__file__)
+VERSION_FILENAME = os.path.join(
+    BASE_DIR, "src", "error_handler_1", "version.py"
+)
+PACKAGE_INFO = {}
+with open(VERSION_FILENAME) as f:
+    exec(f.read(), PACKAGE_INFO)
+
+setuptools.setup(version=PACKAGE_INFO["__version__"])

docs/examples/error_hander/error_handler_1/src/error_handler_1/__init__.py

@@ -0,0 +1,30 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from logging import getLogger
+
+from opentelemetry.sdk.error_handler import ErrorHandler
+
+logger = getLogger(__name__)
+
+
+# pylint: disable=too-many-ancestors
+class ErrorHandler1(ErrorHandler, IndexError, KeyError):
+    def _handle(self, error: Exception, *args, **kwargs):
+
+        if isinstance(error, IndexError):
+            logger.exception("ErrorHandler1 handling an IndexError")
+
+        elif isinstance(error, KeyError):
+            logger.exception("ErrorHandler1 handling a KeyError")