New package: unhandled Exceptions logging instrumentation

.github/component_owners.yml

@@ -12,6 +12,9 @@ components:
   instrumentation/opentelemetry-instrumentation-asyncio:
     - bourbonkk
 
+  instrumentation/opentelemetry-instrumentation-exceptions:
+    - iblancasa
+
   instrumentation/opentelemetry-instrumentation-botocore:
     - lukeina2z
     - yiyuan-he

.github/workflows/core_contrib_test.yml

@@ -1827,6 +1827,36 @@ jobs:
       - name: Run tests
         run: tox -e py310-test-instrumentation-logging -- -ra
 
+  py310-test-instrumentation-exceptions:
+    name: instrumentation-exceptions 
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout contrib repo @ SHA - ${{ env.CONTRIB_REPO_SHA }}
+        uses: actions/checkout@v4
+        with:
+          repository: open-telemetry/opentelemetry-python-contrib
+          ref: ${{ env.CONTRIB_REPO_SHA }}
+
+      - name: Checkout core repo @ SHA - ${{ env.CORE_REPO_SHA }}
+        uses: actions/checkout@v4
+        with:
+          repository: open-telemetry/opentelemetry-python
+          ref: ${{ env.CORE_REPO_SHA }}
+          path: opentelemetry-python
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          architecture: "x64"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -e py310-test-instrumentation-exceptions -- -ra
+
   py310-test-exporter-richconsole:
     name: exporter-richconsole 
     runs-on: ubuntu-latest

.github/workflows/lint.yml

@@ -613,6 +613,25 @@ jobs:
       - name: Run tests
         run: tox -e lint-instrumentation-logging
 
+  lint-instrumentation-exceptions:
+    name: instrumentation-exceptions
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -e lint-instrumentation-exceptions
+
   lint-exporter-richconsole:
     name: exporter-richconsole
     runs-on: ubuntu-latest

.github/workflows/test.yml

@@ -6142,6 +6142,120 @@ jobs:
       - name: Run tests
         run: tox -e pypy3-test-instrumentation-logging -- -ra
 
+  py310-test-instrumentation-exceptions_ubuntu-latest:
+    name: instrumentation-exceptions 3.10 Ubuntu
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -e py310-test-instrumentation-exceptions -- -ra
+
+  py311-test-instrumentation-exceptions_ubuntu-latest:
+    name: instrumentation-exceptions 3.11 Ubuntu
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -e py311-test-instrumentation-exceptions -- -ra
+
+  py312-test-instrumentation-exceptions_ubuntu-latest:
+    name: instrumentation-exceptions 3.12 Ubuntu
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -e py312-test-instrumentation-exceptions -- -ra
+
+  py313-test-instrumentation-exceptions_ubuntu-latest:
+    name: instrumentation-exceptions 3.13 Ubuntu
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -e py313-test-instrumentation-exceptions -- -ra
+
+  py314-test-instrumentation-exceptions_ubuntu-latest:
+    name: instrumentation-exceptions 3.14 Ubuntu
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -e py314-test-instrumentation-exceptions -- -ra
+
+  pypy3-test-instrumentation-exceptions_ubuntu-latest:
+    name: instrumentation-exceptions pypy-3.10 Ubuntu
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python pypy-3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "pypy-3.10"
+
+      - name: Install tox
+        run: pip install tox-uv
+
+      - name: Run tests
+        run: tox -e pypy3-test-instrumentation-exceptions -- -ra
+
   py310-test-exporter-richconsole_ubuntu-latest:
     name: exporter-richconsole 3.10 Ubuntu
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#4335](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4335))
 - Expand `AGENTS.md` with instrumentation/GenAI guidance and add PR review instructions.
   ([#4457](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4457))
+- `opentelemetry-instrumentation-exceptions`: Add instrumentation to emit OpenTelemetry logs for uncaught exceptions, uncaught thread exceptions, and unhandled asyncio task exceptions.
+  ([#4209](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/4209))
 
 ### Fixed
 

docs/instrumentation/exceptions/exceptions.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Exceptions Instrumentation
+========================================
+
+.. automodule:: opentelemetry.instrumentation.exceptions
+    :members:
+    :undoc-members:
+    :show-inheritance:

instrumentation/README.md

@@ -20,6 +20,7 @@
 | [opentelemetry-instrumentation-dbapi](./opentelemetry-instrumentation-dbapi) | dbapi | No | development
 | [opentelemetry-instrumentation-django](./opentelemetry-instrumentation-django) | django >= 2.0 | Yes | development
 | [opentelemetry-instrumentation-elasticsearch](./opentelemetry-instrumentation-elasticsearch) | elasticsearch >= 6.0 | No | development
+| [opentelemetry-instrumentation-exceptions](./opentelemetry-instrumentation-exceptions) | exceptions | No | development
 | [opentelemetry-instrumentation-falcon](./opentelemetry-instrumentation-falcon) | falcon >= 1.4.1, < 5.0.0 | Yes | migration
 | [opentelemetry-instrumentation-fastapi](./opentelemetry-instrumentation-fastapi) | fastapi ~= 0.92 | Yes | migration
 | [opentelemetry-instrumentation-flask](./opentelemetry-instrumentation-flask) | flask >= 1.0 | Yes | migration

instrumentation/opentelemetry-instrumentation-exceptions/LICENSE

@@ -0,0 +1,13 @@
+# 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.

instrumentation/opentelemetry-instrumentation-exceptions/README.rst

@@ -0,0 +1,35 @@
+OpenTelemetry unhandled exceptions instrumentation
+==================================================
+
+|pypi|
+
+.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-exceptions.svg
+   :target: https://pypi.org/project/opentelemetry-instrumentation-exceptions/
+
+Installation
+------------
+
+::
+
+    pip install opentelemetry-instrumentation-exceptions
+
+Usage
+-----
+
+.. code-block:: python
+
+    from opentelemetry.instrumentation.exceptions import (
+        UnhandledExceptionInstrumentor,
+    )
+
+    UnhandledExceptionInstrumentor().instrument()
+
+This instrumentation captures uncaught process exceptions, uncaught thread
+exceptions, and unhandled asyncio task exceptions and emits them as OpenTelemetry
+logs.
+
+References
+----------
+
+* `OpenTelemetry Python Contrib repository <https://github.com/open-telemetry/opentelemetry-python-contrib>`_
+* `OpenTelemetry Project <https://opentelemetry.io/>`_

instrumentation/opentelemetry-instrumentation-exceptions/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "opentelemetry-instrumentation-exceptions"
+dynamic = ["version"]
+description = "OpenTelemetry unhandled exceptions instrumentation"
+readme = "README.rst"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+  { name = "OpenTelemetry Authors", email = "cncf-opentelemetry-contributors@lists.cncf.io" },
+]
+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.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+  "opentelemetry-api >= 1.42.0.dev, < 2.0.0",
+  "opentelemetry-instrumentation == 0.63b0.dev",
+  "opentelemetry-semantic-conventions == 0.63b0.dev",
+]
+
+[project.optional-dependencies]
+instruments = []
+
+[project.entry-points.opentelemetry_instrumentor]
+exceptions = "opentelemetry.instrumentation.exceptions:UnhandledExceptionInstrumentor"
+
+[project.urls]
+Homepage = "https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-exceptions"
+Repository = "https://github.com/open-telemetry/opentelemetry-python-contrib"
+
+[tool.hatch.version]
+path = "src/opentelemetry/instrumentation/exceptions/version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opentelemetry"]