hexkit 8.4.1__tar.gz → 8.6.0__tar.gz

hexkit-8.6.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: hexkit
+Version: 8.6.0
+Summary: A Toolkit for Building Microservices using the Hexagonal Architecture
+Author-email: "German Human Genome Phenome Archive (GHGA)" <contact@ghga.de>
+License: Apache 2.0
+Project-URL: Repository, https://github.com/ghga-de/hexkit
+Project-URL: Documentation, https://ghga-de.github.io/hexkit/
+Project-URL: Release Notes, https://github.com/ghga-de/hexkit/releases
+Project-URL: Issue Tracker, https://github.com/ghga-de/hexkit/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Operating System :: POSIX :: Linux
+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: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opentelemetry-api<2,>=1.44
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: pydantic_settings<3,>=2.12
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: akafka
+Requires-Dist: aiokafka[lz4,snappy,zstd]~=0.14.0; extra == "akafka"
+Requires-Dist: jsonschema<5,>=4.25; extra == "akafka"
+Provides-Extra: s3
+Requires-Dist: boto3<2,>=1.42; extra == "s3"
+Requires-Dist: botocore<2,>=1.42; extra == "s3"
+Provides-Extra: mongodb
+Requires-Dist: pymongo<5,>=4.16; extra == "mongodb"
+Provides-Extra: redis
+Requires-Dist: redis<8,>=7.1; extra == "redis"
+Provides-Extra: vault
+Requires-Dist: hvac<3,>=2.4; extra == "vault"
+Provides-Extra: opentelemetry-base
+Requires-Dist: opentelemetry-sdk<2,>=1.44; extra == "opentelemetry-base"
+Requires-Dist: opentelemetry-exporter-otlp<2,>=1.44; extra == "opentelemetry-base"
+Requires-Dist: opentelemetry-instrumentation>=0.65b0; extra == "opentelemetry-base"
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.65b0; extra == "opentelemetry-base"
+Requires-Dist: opentelemetry-distro>=0.65b0; extra == "opentelemetry-base"
+Provides-Extra: opentelemetry-akafka
+Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-akafka"
+Requires-Dist: hexkit[akafka]; extra == "opentelemetry-akafka"
+Requires-Dist: opentelemetry-instrumentation-aiokafka>=0.65b0; extra == "opentelemetry-akafka"
+Provides-Extra: opentelemetry-mongodb
+Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-mongodb"
+Requires-Dist: hexkit[mongodb]; extra == "opentelemetry-mongodb"
+Requires-Dist: opentelemetry-instrumentation-pymongo>=0.65b0; extra == "opentelemetry-mongodb"
+Provides-Extra: opentelemetry-fastapi
+Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-fastapi"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.65b0; extra == "opentelemetry-fastapi"
+Provides-Extra: opentelemetry-s3
+Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-s3"
+Requires-Dist: hexkit[s3]; extra == "opentelemetry-s3"
+Requires-Dist: opentelemetry-instrumentation-botocore>=0.65b0; extra == "opentelemetry-s3"
+Provides-Extra: opentelemetry-redis
+Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-redis"
+Requires-Dist: hexkit[redis]; extra == "opentelemetry-redis"
+Requires-Dist: opentelemetry-instrumentation-redis>=0.65b0; extra == "opentelemetry-redis"
+Provides-Extra: opentelemetry
+Requires-Dist: hexkit[opentelemetry-akafka]; extra == "opentelemetry"
+Requires-Dist: hexkit[opentelemetry-mongodb]; extra == "opentelemetry"
+Requires-Dist: hexkit[opentelemetry-fastapi]; extra == "opentelemetry"
+Requires-Dist: hexkit[opentelemetry-s3]; extra == "opentelemetry"
+Provides-Extra: test-akafka
+Requires-Dist: hexkit[akafka]; extra == "test-akafka"
+Requires-Dist: testcontainers[kafka]<5,>=4.14; extra == "test-akafka"
+Provides-Extra: test-s3
+Requires-Dist: hexkit[s3]; extra == "test-s3"
+Requires-Dist: testcontainers<5,>=4.14; extra == "test-s3"
+Provides-Extra: test-mongodb
+Requires-Dist: hexkit[mongodb]; extra == "test-mongodb"
+Requires-Dist: testcontainers[mongo]<5,>=4.14; extra == "test-mongodb"
+Provides-Extra: test-redis
+Requires-Dist: hexkit[redis]; extra == "test-redis"
+Requires-Dist: testcontainers[redis]<5,>=4.14; extra == "test-redis"
+Provides-Extra: test-vault
+Requires-Dist: hexkit[vault]; extra == "test-vault"
+Requires-Dist: testcontainers<5,>=4.14; extra == "test-vault"
+Provides-Extra: test
+Requires-Dist: hexkit[test-akafka,test-mongodb,test-s3,test-vault]; extra == "test"
+Provides-Extra: all
+Requires-Dist: hexkit[test]; extra == "all"
+Requires-Dist: hexkit[opentelemetry]; extra == "all"
+Dynamic: license-file
+
+[![PyPI version shields.io](https://img.shields.io/pypi/v/hexkit.svg)](https://pypi.python.org/pypi/hexkit/)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/hexkit.svg)](https://pypi.python.org/pypi/hexkit/)
+![tests](https://github.com/ghga-de/hexkit/actions/workflows/tests.yaml/badge.svg)
+[![Coverage Status](https://coveralls.io/repos/github/ghga-de/hexkit/badge.svg?branch=main)](https://coveralls.io/github/ghga-de/hexkit?branch=main)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+
+# hexkit
+
+*A chassis library for building domain-focused, infrastructure-agnostic,
+and event-driven microservices in Python*
+
+Read the short summary below, or jump straight to our full
+📖 **[User Guide](https://ghga-de.github.io/hexkit/user-guide/)** to learn the abstract
+concepts and patterns as well as the concrete infrastructure integrations and testing
+tools that hexkit provides for building better microservices.
+
+<!--
+NOTE: This README doubles as the landing page of the documentation site built with
+great-docs. Therefore, all links must be absolute URLs — repo-relative links like
+./examples or ./src would resolve correctly on GitHub but break on the site.
+-->
+
+## In a Nutshell
+
+hexkit implements the *Triple Hexagonal Architecture* pattern, an optimization of the
+ordinary
+[Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architecture/) for
+use with microservices: adapters (as per the hexagonal architecture) are divided into
+two parts. One part called *translator* is specific to one individual microservice
+and its domain-oriented ports. The other part called *provider* is service-agnostic
+but specific to one technology of the surrounding infrastructure. Both parts interact
+through a high-level interface called *protocol* (not to be confused with Python's
+typing.Protocol) which is neither specific to the technology nor to the microservice.
+
+As a chassis lib, hexkit reduces redundancy and boilerplate across microservices by
+providing the service-independent building blocks — protocols and providers — ready
+to use. The only task that remains for an individual service is to implement
+service-specific translators between the service's ports and the general-purpose
+protocols (in addition to implementing the domain functionality of the service, of
+course). For an in-depth introduction to the pattern, please read the
+[Architectural Concepts](https://ghga-de.github.io/hexkit/user-guide/arch_concepts/)
+chapter of the User Guide.
+
+The following protocols and providers are currently available:
+
+| Protocol           | Providers                              |
+| ------------------ | -------------------------------------- |
+| Event Publishing   | Apache Kafka, MongoDB + Kafka (outbox) |
+| Event Subscription | Apache Kafka                           |
+| Data Access Object | MongoDB                                |
+| Object Storage     | S3(-compatible)                        |
+| Key-Value Store    | MongoDB, Redis, S3, HashiCorp Vault    |
+
+In-memory implementations and per-backend test utilities are also included to
+support testing without real infrastructure.
+
+You are not forced to go all-in on the idea of Triple Hexagonal Architecture.
+You can use it just for the technologies where you see benefits and use another
+approach for the rest. For example, you could use hexkit for simplifying the exchange
+of events between microservices but use a classical web framework such as FastAPI for
+designing REST APIs and an ORM like SQLAlchemy for interacting with databases.
+
+## Getting Started
+
+The 📖 [User Guide](https://ghga-de.github.io/hexkit/user-guide/) covers all
+protocols, providers, testing utilities, and observability tools with example code,
+and the [API Reference](https://ghga-de.github.io/hexkit/reference/) documents all
+public classes and functions.
+
+For a complete example service built with hexkit, have a look at the
+[stream_calc](https://github.com/ghga-de/hexkit/tree/main/examples/stream_calc)
+example application. We also put a lot of effort into making the code
+self-documenting: you can find the protocols being defined at
+[src/hexkit/protocols](https://github.com/ghga-de/hexkit/tree/main/src/hexkit/protocols)
+and the providers being implemented at
+[src/hexkit/providers](https://github.com/ghga-de/hexkit/tree/main/src/hexkit/providers).
+
+## Installation
+
+This package is available at PyPI:
+<https://pypi.org/project/hexkit>
+
+You can install it from there using:
+
+```sh
+pip install hexkit
+```
+
+The following extras are available:
+
+- `akafka`: when using the Apache Kafka-based event publishing or subscription
+- `mongodb`: when using MongoDB as backend for the DAO protocol or key-value stores
+- `s3`: when interacting with S3-compatible object storages or key-value stores
+- `redis`: when using Redis-based key-value stores
+- `vault`: when using HashiCorp Vault-based key-value stores
+- `opentelemetry`: observability instrumentation (also available per backend, e.g.
+  `opentelemetry-akafka`, `opentelemetry-mongodb`, `opentelemetry-fastapi`)
+- `test-akafka`, `test-mongodb`, `test-s3`, `test-redis`, `test-vault`: testing
+  utils for the respective backend (`test` is a union of all of them)
+- `all`: a union of all the above
+
+## Contributing
+
+Contributions are welcome! Please see the
+[contribution guide](https://github.com/ghga-de/hexkit/blob/main/CONTRIBUTING.md)
+for how to set up the development environment and build the documentation locally.
+
+## Credits
+
+The hexkit library is developed and maintained by the developer team of GHGA. We would especially
+like to thank its original author, Kersten Breuer, who came up with the idea for the
+library and designed and coded its first versions.
+
+## License
+
+This repository is free to use and modify according to the
+[Apache 2.0 License](https://github.com/ghga-de/hexkit/blob/main/LICENSE).

hexkit-8.6.0/README.md

@@ -0,0 +1,118 @@
+[![PyPI version shields.io](https://img.shields.io/pypi/v/hexkit.svg)](https://pypi.python.org/pypi/hexkit/)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/hexkit.svg)](https://pypi.python.org/pypi/hexkit/)
+![tests](https://github.com/ghga-de/hexkit/actions/workflows/tests.yaml/badge.svg)
+[![Coverage Status](https://coveralls.io/repos/github/ghga-de/hexkit/badge.svg?branch=main)](https://coveralls.io/github/ghga-de/hexkit?branch=main)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+
+# hexkit
+
+*A chassis library for building domain-focused, infrastructure-agnostic,
+and event-driven microservices in Python*
+
+Read the short summary below, or jump straight to our full
+📖 **[User Guide](https://ghga-de.github.io/hexkit/user-guide/)** to learn the abstract
+concepts and patterns as well as the concrete infrastructure integrations and testing
+tools that hexkit provides for building better microservices.
+
+<!--
+NOTE: This README doubles as the landing page of the documentation site built with
+great-docs. Therefore, all links must be absolute URLs — repo-relative links like
+./examples or ./src would resolve correctly on GitHub but break on the site.
+-->
+
+## In a Nutshell
+
+hexkit implements the *Triple Hexagonal Architecture* pattern, an optimization of the
+ordinary
+[Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architecture/) for
+use with microservices: adapters (as per the hexagonal architecture) are divided into
+two parts. One part called *translator* is specific to one individual microservice
+and its domain-oriented ports. The other part called *provider* is service-agnostic
+but specific to one technology of the surrounding infrastructure. Both parts interact
+through a high-level interface called *protocol* (not to be confused with Python's
+typing.Protocol) which is neither specific to the technology nor to the microservice.
+
+As a chassis lib, hexkit reduces redundancy and boilerplate across microservices by
+providing the service-independent building blocks — protocols and providers — ready
+to use. The only task that remains for an individual service is to implement
+service-specific translators between the service's ports and the general-purpose
+protocols (in addition to implementing the domain functionality of the service, of
+course). For an in-depth introduction to the pattern, please read the
+[Architectural Concepts](https://ghga-de.github.io/hexkit/user-guide/arch_concepts/)
+chapter of the User Guide.
+
+The following protocols and providers are currently available:
+
+| Protocol           | Providers                              |
+| ------------------ | -------------------------------------- |
+| Event Publishing   | Apache Kafka, MongoDB + Kafka (outbox) |
+| Event Subscription | Apache Kafka                           |
+| Data Access Object | MongoDB                                |
+| Object Storage     | S3(-compatible)                        |
+| Key-Value Store    | MongoDB, Redis, S3, HashiCorp Vault    |
+
+In-memory implementations and per-backend test utilities are also included to
+support testing without real infrastructure.
+
+You are not forced to go all-in on the idea of Triple Hexagonal Architecture.
+You can use it just for the technologies where you see benefits and use another
+approach for the rest. For example, you could use hexkit for simplifying the exchange
+of events between microservices but use a classical web framework such as FastAPI for
+designing REST APIs and an ORM like SQLAlchemy for interacting with databases.
+
+## Getting Started
+
+The 📖 [User Guide](https://ghga-de.github.io/hexkit/user-guide/) covers all
+protocols, providers, testing utilities, and observability tools with example code,
+and the [API Reference](https://ghga-de.github.io/hexkit/reference/) documents all
+public classes and functions.
+
+For a complete example service built with hexkit, have a look at the
+[stream_calc](https://github.com/ghga-de/hexkit/tree/main/examples/stream_calc)
+example application. We also put a lot of effort into making the code
+self-documenting: you can find the protocols being defined at
+[src/hexkit/protocols](https://github.com/ghga-de/hexkit/tree/main/src/hexkit/protocols)
+and the providers being implemented at
+[src/hexkit/providers](https://github.com/ghga-de/hexkit/tree/main/src/hexkit/providers).
+
+## Installation
+
+This package is available at PyPI:
+<https://pypi.org/project/hexkit>
+
+You can install it from there using:
+
+```sh
+pip install hexkit
+```
+
+The following extras are available:
+
+- `akafka`: when using the Apache Kafka-based event publishing or subscription
+- `mongodb`: when using MongoDB as backend for the DAO protocol or key-value stores
+- `s3`: when interacting with S3-compatible object storages or key-value stores
+- `redis`: when using Redis-based key-value stores
+- `vault`: when using HashiCorp Vault-based key-value stores
+- `opentelemetry`: observability instrumentation (also available per backend, e.g.
+  `opentelemetry-akafka`, `opentelemetry-mongodb`, `opentelemetry-fastapi`)
+- `test-akafka`, `test-mongodb`, `test-s3`, `test-redis`, `test-vault`: testing
+  utils for the respective backend (`test` is a union of all of them)
+- `all`: a union of all the above
+
+## Contributing
+
+Contributions are welcome! Please see the
+[contribution guide](https://github.com/ghga-de/hexkit/blob/main/CONTRIBUTING.md)
+for how to set up the development environment and build the documentation locally.
+
+## Credits
+
+The hexkit library is developed and maintained by the developer team of GHGA. We would especially
+like to thank its original author, Kersten Breuer, who came up with the idea for the
+library and designed and coded its first versions.
+
+## License
+
+This repository is free to use and modify according to the
+[Apache 2.0 License](https://github.com/ghga-de/hexkit/blob/main/LICENSE).

{hexkit-8.4.1 → hexkit-8.6.0}/pyproject.toml

@@ -23,10 +23,10 @@ classifiers = [
     "Intended Audience :: Developers",
 ]
 name = "hexkit"
-version = "8.4.1"
+version = "8.6.0"
 description = "A Toolkit for Building Microservices using the Hexagonal Architecture"
 dependencies = [
-    "opentelemetry-api >=1.39, <2",
+    "opentelemetry-api >=1.44, <2",
     "pydantic >=2.12, <3",
     "pydantic_settings >=2.12, <3",
     "PyYAML >=6, <7",
@@ -54,35 +54,35 @@ vault = [
     "hvac >=2.4, <3",
 ]
 opentelemetry-base = [
-    "opentelemetry-sdk >=1.39.1, <2",
-    "opentelemetry-exporter-otlp >=1.39.1, <2",
-    "opentelemetry-instrumentation >=0.60b1",
-    "opentelemetry-instrumentation-httpx >=0.60b1",
-    "opentelemetry-distro >=0.60b1",
+    "opentelemetry-sdk >=1.44, <2",
+    "opentelemetry-exporter-otlp >=1.44, <2",
+    "opentelemetry-instrumentation >=0.65b0",
+    "opentelemetry-instrumentation-httpx >=0.65b0",
+    "opentelemetry-distro >=0.65b0",
 ]
 opentelemetry-akafka = [
     "hexkit[opentelemetry-base]",
     "hexkit[akafka]",
-    "opentelemetry-instrumentation-aiokafka >=0.60b1",
+    "opentelemetry-instrumentation-aiokafka >=0.65b0",
 ]
 opentelemetry-mongodb = [
     "hexkit[opentelemetry-base]",
     "hexkit[mongodb]",
-    "opentelemetry-instrumentation-pymongo >=0.60b1",
+    "opentelemetry-instrumentation-pymongo >=0.65b0",
 ]
 opentelemetry-fastapi = [
     "hexkit[opentelemetry-base]",
-    "opentelemetry-instrumentation-fastapi >=0.60b1",
+    "opentelemetry-instrumentation-fastapi >=0.65b0",
 ]
 opentelemetry-s3 = [
     "hexkit[opentelemetry-base]",
     "hexkit[s3]",
-    "opentelemetry-instrumentation-botocore >=0.60b1",
+    "opentelemetry-instrumentation-botocore >=0.65b0",
 ]
 opentelemetry-redis = [
     "hexkit[opentelemetry-base]",
     "hexkit[redis]",
-    "opentelemetry-instrumentation-redis >=0.60b1",
+    "opentelemetry-instrumentation-redis >=0.65b0",
 ]
 opentelemetry = [
     "hexkit[opentelemetry-akafka]",
@@ -157,6 +157,9 @@ ignore = [
     "E111",
     "E114",
     "E116",
+    "E117",
+    "E501",
+    "W191",
     "PLW",
     "RUF001",
     "RUF010",
@@ -185,6 +188,13 @@ select = [
     "RUF",
     "SIM",
     "D",
+    "E",
+    "W",
+    "ASYNC",
+    "LOG",
+    "PERF",
+    "RET",
+    "C4",
 ]
 
 [tool.ruff.lint.mccabe]
@@ -196,6 +206,7 @@ max-complexity = 10
     "S",
     "SIM",
     "D",
+    "E402",
 ]
 "tests/*" = [
     "S",
@@ -256,19 +267,14 @@ legacy_tox_ini = """
 
     [testenv:docs]
     basepython = python3.13
-    allowlist_externals =
-        mv
-        rm
     deps =
         --no-deps -r ./lock/requirements-dev.txt
+    commands_pre =
+        # great-docs (Python >= 3.11 only) is kept out of the shared dev lock so it
+        # does not break the py310 test env; install it here where docs are built.
+        pip install great-docs==0.14.1
     commands =
-        rm -rf site/api
-        pdoc -d google -o docs/api hexkit
-        mv docs/api/index.html docs/api/index.md
-        mkdocs build
-        mv docs/api/index.md docs/api/index.html
-        rm -rf site/api
-        mv docs/api site/api
+        great-docs build
 
     [testenv]
     pass_env =

{hexkit-8.4.1 → hexkit-8.6.0}/src/hexkit/log.py

@@ -105,7 +105,7 @@ class JsonFormatter(Formatter):
         """
         # Create a log record dictionary
         log_record = record.__dict__
-        output: dict[str, Any] = dict()
+        output: dict[str, Any] = {}
 
         output["timestamp"] = log_record["timestamp"]
         output["service"] = log_record["service"]

hexkit-8.6.0/src/hexkit/opentelemetry/__init__.py

@@ -0,0 +1,29 @@
+# Copyright 2021 - 2026 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# for the German Human Genome-Phenome Archive (GHGA)
+#
+# 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.
+#
+
+"""Subpackage containing OpenTelemetry instrumentation and related utilities."""
+
+from .instrumentation import (
+    OpenTelemetryConfig,
+    configure_opentelemetry,
+    instrument_installed_libraries,
+)
+
+__all__ = [
+    "OpenTelemetryConfig",
+    "configure_opentelemetry",
+    "instrument_installed_libraries",
+]

hexkit-8.6.0/src/hexkit/opentelemetry/instrumentation.py

@@ -0,0 +1,122 @@
+# Copyright 2021 - 2026 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# for the German Human Genome-Phenome Archive (GHGA)
+#
+# 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.
+
+"""OpenTelemetry specific configuration code. This is gated behind the opentelemetry extra."""
+
+import importlib
+import logging
+from typing import Annotated
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+from opentelemetry.sdk.trace import SpanProcessor, TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.trace.sampling import ParentBasedTraceIdRatio
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+__all__ = [
+    "OpenTelemetryConfig",
+    "configure_opentelemetry",
+    "instrument_installed_libraries",
+]
+
+logger = logging.getLogger(__name__)
+
+# Instrumentation modules corresponding to the `opentelemetry-*` optional extras.
+# Each entry is only instrumented if its module is installed.
+_INSTRUMENTOR_MODULES: tuple[tuple[str, str], ...] = (
+    ("opentelemetry.instrumentation.httpx", "HTTPXClientInstrumentor"),
+    ("opentelemetry.instrumentation.aiokafka", "AIOKafkaInstrumentor"),
+    ("opentelemetry.instrumentation.pymongo", "PymongoInstrumentor"),
+    ("opentelemetry.instrumentation.fastapi", "FastAPIInstrumentor"),
+    ("opentelemetry.instrumentation.botocore", "BotocoreInstrumentor"),
+    ("opentelemetry.instrumentation.redis", "RedisInstrumentor"),
+)
+
+
+def instrument_installed_libraries() -> None:
+    """Run `.instrument()` for every instrumentation library that is installed."""
+    for module_name, class_name in _INSTRUMENTOR_MODULES:
+        try:
+            module = importlib.import_module(module_name)
+        except ImportError:
+            logger.debug("'%s' not installed, skipping instrumentation.", module_name)
+            continue
+        try:
+            instrumentor_class = getattr(module, class_name)
+        except AttributeError:
+            logger.warning(
+                "Could not instrument '%s' for '%s'.", class_name, module_name
+            )
+        instrumentor_class().instrument()
+        logger.info("Instrumented '%s' for '%s'.", class_name, module_name)
+
+
+class OpenTelemetryConfig(BaseSettings):
+    """OpenTelemetry specific configuration options"""
+
+    enable_opentelemetry: bool = Field(
+        default=False,
+        description="If set to true, this will run necessary setup code."
+        "If set to false, no setup code is run, which leaves tracing disabled.",
+    )
+    otel_trace_sampling_rate: Annotated[float, Field(strict=True, ge=0, le=1)] = Field(
+        default=1.0,
+        description="Determines which proportion of spans should be sampled. "
+        "A value of 1.0 means all and is equivalent to the previous behaviour. "
+        "Setting this to 0 will result in no spans being sampled, but this does not "
+        "automatically set `enable_opentelemetry` to False.",
+    )
+
+
+def configure_opentelemetry(
+    *,
+    service_name: str,
+    config: OpenTelemetryConfig,
+    span_processor: SpanProcessor | None = None,
+):
+    """Configure all needed parts of OpenTelemetry.
+
+    This needs to be called before constructing any objects that are instrumented, e.g.
+    construction a FastAPI app before running this, will result in missing instrumentation.
+
+    Setup of the TracerProvider is done programmatically. If disabled, this is a no-op,
+    leaving the default no-op TracerProvider from the OpenTelemetry API in place.
+
+    By default, spans are exported via OTLP over HTTP using a `BatchSpanProcessor`.
+    """
+    if not config.enable_opentelemetry:
+        logger.info("OpenTelemetry disabled via config.")
+        return
+
+    resource = Resource(attributes={SERVICE_NAME: service_name})
+    # Replace the default static sampler with a probabilistic one that honors parent
+    # span sampling decisions
+    # This should consistently yield full traces within a service but not necessarily
+    # across service boundaries
+    # With the default sampling rate, behaviour does not change, but this allows to
+    # introduce head sampling by adjusting a config option on the service side later on
+    sampler = ParentBasedTraceIdRatio(rate=config.otel_trace_sampling_rate)
+
+    # Initialize service specific TracerProvider
+    trace_provider = TracerProvider(resource=resource, sampler=sampler)
+    trace_provider.add_span_processor(
+        span_processor or BatchSpanProcessor(OTLPSpanExporter())
+    )
+    trace.set_tracer_provider(trace_provider)
+
+    instrument_installed_libraries()