Add Structlog Processor as Instrumentation

.changelog/4286.added

@@ -0,0 +1 @@
+Add `opentelemetry-instrumentation-structlog` instrumentation package and shared `log_utils` helpers for emitting structlog events as OpenTelemetry logs.

.github/workflows/core_contrib_test.yml

@@ -1707,6 +1707,66 @@ jobs:
       - name: Run tests
         run: tox -e py310-test-instrumentation-starlette-latest -- -ra
 
+  py310-test-instrumentation-structlog-oldest:
+    name: instrumentation-structlog-oldest 
+    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-structlog-oldest -- -ra
+
+  py310-test-instrumentation-structlog-latest:
+    name: instrumentation-structlog-latest 
+    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-structlog-latest -- -ra
+
   py310-test-instrumentation-jinja2:
     name: instrumentation-jinja2 
     runs-on: ubuntu-latest

.github/workflows/lint.yml

@@ -556,6 +556,25 @@ jobs:
       - name: Run tests
         run: tox -e lint-instrumentation-starlette
 
+  lint-instrumentation-structlog:
+    name: instrumentation-structlog
+    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-structlog
+
   lint-instrumentation-jinja2:
     name: instrumentation-jinja2
     runs-on: ubuntu-latest

.github/workflows/test.yml

@@ -5705,6 +5705,234 @@ jobs:
       - name: Run tests
         run: tox -e pypy3-test-instrumentation-starlette-latest -- -ra
 
+  py310-test-instrumentation-structlog-oldest_ubuntu-latest:
+    name: instrumentation-structlog-oldest 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-structlog-oldest -- -ra
+
+  py310-test-instrumentation-structlog-latest_ubuntu-latest:
+    name: instrumentation-structlog-latest 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-structlog-latest -- -ra
+
+  py311-test-instrumentation-structlog-oldest_ubuntu-latest:
+    name: instrumentation-structlog-oldest 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-structlog-oldest -- -ra
+
+  py311-test-instrumentation-structlog-latest_ubuntu-latest:
+    name: instrumentation-structlog-latest 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-structlog-latest -- -ra
+
+  py312-test-instrumentation-structlog-oldest_ubuntu-latest:
+    name: instrumentation-structlog-oldest 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-structlog-oldest -- -ra
+
+  py312-test-instrumentation-structlog-latest_ubuntu-latest:
+    name: instrumentation-structlog-latest 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-structlog-latest -- -ra
+
+  py313-test-instrumentation-structlog-oldest_ubuntu-latest:
+    name: instrumentation-structlog-oldest 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-structlog-oldest -- -ra
+
+  py313-test-instrumentation-structlog-latest_ubuntu-latest:
+    name: instrumentation-structlog-latest 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-structlog-latest -- -ra
+
+  py314-test-instrumentation-structlog-oldest_ubuntu-latest:
+    name: instrumentation-structlog-oldest 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-structlog-oldest -- -ra
+
+  py314-test-instrumentation-structlog-latest_ubuntu-latest:
+    name: instrumentation-structlog-latest 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-structlog-latest -- -ra
+
+  pypy3-test-instrumentation-structlog-oldest_ubuntu-latest:
+    name: instrumentation-structlog-oldest 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-structlog-oldest -- -ra
+
+  pypy3-test-instrumentation-structlog-latest_ubuntu-latest:
+    name: instrumentation-structlog-latest 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-structlog-latest -- -ra
+
   py310-test-instrumentation-jinja2_ubuntu-latest:
     name: instrumentation-jinja2 3.10 Ubuntu
     runs-on: ubuntu-latest

docs-requirements.txt

@@ -47,6 +47,7 @@ remoulade[limits]>=5.0.0 ; python_version >= "3.12"
 remoulade>=0.50.0 ; python_version < "3.12"
 sqlalchemy>=1.0
 starlette~=0.50
+structlog>=21.1
 tornado>=5.1.1
 tortoise-orm>=0.17.0
 wrapt~=2.1

docs/instrumentation/structlog/structlog.rst

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

instrumentation/README.md

@@ -44,6 +44,7 @@
 | [opentelemetry-instrumentation-sqlalchemy](./opentelemetry-instrumentation-sqlalchemy) | sqlalchemy >= 1.0.0, < 2.1.0 | Yes | migration
 | [opentelemetry-instrumentation-sqlite3](./opentelemetry-instrumentation-sqlite3) | sqlite3 | No | migration
 | [opentelemetry-instrumentation-starlette](./opentelemetry-instrumentation-starlette) | starlette >= 0.13 | Yes | development
+| [opentelemetry-instrumentation-structlog](./opentelemetry-instrumentation-structlog) | structlog >= 21.1 | No | development
 | [opentelemetry-instrumentation-system-metrics](./opentelemetry-instrumentation-system-metrics) | psutil >= 5 | No | development
 | [opentelemetry-instrumentation-threading](./opentelemetry-instrumentation-threading) | threading | No | development
 | [opentelemetry-instrumentation-tornado](./opentelemetry-instrumentation-tornado) | tornado >= 5.1.1 | Yes | migration