plain.models 0.36.0__py3-none-any.whl → 0.37.0__py3-none-any.whl

plain/models/CHANGELOG.md

@@ -1,5 +1,16 @@
 # plain-models changelog
 
+## [0.37.0](https://github.com/dropseed/plain/releases/plain-models@0.37.0) (2025-07-18)
+
+### What's changed
+
+- Added OpenTelemetry instrumentation for database operations - all SQL queries now automatically generate OpenTelemetry spans with standardized attributes following semantic conventions ([b0224d0](https://github.com/dropseed/plain/commit/b0224d0))
+- Database operations in tests are now wrapped with tracing suppression to avoid generating telemetry noise during test execution ([b0224d0](https://github.com/dropseed/plain/commit/b0224d0))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.36.0](https://github.com/dropseed/plain/releases/plain-models@0.36.0) (2025-07-18)
 
 ### What's changed

plain/models/backends/utils.py

@@ -7,6 +7,7 @@ from contextlib import contextmanager
 from hashlib import md5
 
 from plain.models.db import NotSupportedError
+from plain.models.otel import db_span
 from plain.utils.dateparse import parse_time
 
 logger = logging.getLogger("plain.models.backends")
@@ -80,18 +81,20 @@ class CursorWrapper:
         return executor(sql, params, many, context)
 
     def _execute(self, sql, params, *ignored_wrapper_args):
-        self.db.validate_no_broken_transaction()
-        with self.db.wrap_database_errors:
-            if params is None:
-                # params default might be backend specific.
-                return self.cursor.execute(sql)
-            else:
-                return self.cursor.execute(sql, params)
+        # Wrap in an OpenTelemetry span with standard attributes.
+        with db_span(self.db, sql, params=params):
+            self.db.validate_no_broken_transaction()
+            with self.db.wrap_database_errors:
+                if params is None:
+                    return self.cursor.execute(sql)
+                else:
+                    return self.cursor.execute(sql, params)
 
     def _executemany(self, sql, param_list, *ignored_wrapper_args):
-        self.db.validate_no_broken_transaction()
-        with self.db.wrap_database_errors:
-            return self.cursor.executemany(sql, param_list)
+        with db_span(self.db, sql, many=True, params=param_list):
+            self.db.validate_no_broken_transaction()
+            with self.db.wrap_database_errors:
+                return self.cursor.executemany(sql, param_list)
 
 
 class CursorDebugWrapper(CursorWrapper):

plain/models/otel.py

@@ -0,0 +1,175 @@
+import re
+from contextlib import contextmanager
+from typing import Any
+
+from opentelemetry import context as otel_context
+from opentelemetry import trace
+from opentelemetry.semconv._incubating.attributes.db_attributes import (
+    DB_QUERY_PARAMETER_TEMPLATE,
+    DB_USER,
+)
+from opentelemetry.semconv.attributes.db_attributes import (
+    DB_COLLECTION_NAME,
+    DB_NAMESPACE,
+    DB_OPERATION_NAME,
+    DB_QUERY_SUMMARY,
+    DB_QUERY_TEXT,
+    DB_SYSTEM_NAME,
+)
+from opentelemetry.semconv.attributes.network_attributes import (
+    NETWORK_PEER_ADDRESS,
+    NETWORK_PEER_PORT,
+)
+from opentelemetry.semconv.trace import DbSystemValues
+from opentelemetry.trace import SpanKind
+
+from plain.runtime import settings
+
+_SUPPRESS_KEY = object()
+
+tracer = trace.get_tracer("plain.models")
+
+
+def db_system_for(vendor: str) -> str:  # noqa: D401 – simple helper
+    """Return the canonical ``db.system.name`` value for a backend vendor."""
+
+    return {
+        "postgresql": DbSystemValues.POSTGRESQL.value,
+        "mysql": DbSystemValues.MYSQL.value,
+        "mariadb": DbSystemValues.MARIADB.value,
+        "sqlite": DbSystemValues.SQLITE.value,
+    }.get(vendor, vendor)
+
+
+def extract_operation_and_target(sql: str) -> tuple[str, str | None, str | None]:
+    """Extract operation, table name, and collection from SQL.
+
+    Returns: (operation, summary, collection_name)
+    """
+    sql_upper = sql.upper().strip()
+    operation = sql_upper.split()[0] if sql_upper else "UNKNOWN"
+
+    # Pattern to match quoted and unquoted identifiers
+    # Matches: "quoted", `quoted`, [quoted], unquoted.name
+    identifier_pattern = r'("([^"]+)"|`([^`]+)`|\[([^\]]+)\]|([\w.]+))'
+
+    # Extract table/collection name based on operation
+    collection_name = None
+    summary = operation
+
+    if operation in ("SELECT", "DELETE"):
+        match = re.search(rf"FROM\s+{identifier_pattern}", sql, re.IGNORECASE)
+        if match:
+            collection_name = _clean_identifier(match.group(1))
+            summary = f"{operation} {collection_name}"
+
+    elif operation in ("INSERT", "REPLACE"):
+        match = re.search(rf"INTO\s+{identifier_pattern}", sql, re.IGNORECASE)
+        if match:
+            collection_name = _clean_identifier(match.group(1))
+            summary = f"{operation} {collection_name}"
+
+    elif operation == "UPDATE":
+        match = re.search(rf"UPDATE\s+{identifier_pattern}", sql, re.IGNORECASE)
+        if match:
+            collection_name = _clean_identifier(match.group(1))
+            summary = f"{operation} {collection_name}"
+
+    return operation, summary, collection_name
+
+
+def _clean_identifier(identifier: str) -> str:
+    """Remove quotes from SQL identifiers."""
+    # Remove different types of SQL quotes
+    if identifier.startswith('"') and identifier.endswith('"'):
+        return identifier[1:-1]
+    elif identifier.startswith("`") and identifier.endswith("`"):
+        return identifier[1:-1]
+    elif identifier.startswith("[") and identifier.endswith("]"):
+        return identifier[1:-1]
+    return identifier
+
+
+@contextmanager
+def db_span(db, sql: Any, *, many: bool = False, params=None):
+    """Open an OpenTelemetry CLIENT span for a database query.
+
+    All common attributes (`db.*`, `network.*`, etc.) are set automatically.
+    Follows OpenTelemetry semantic conventions for database instrumentation.
+    """
+
+    # Fast-exit if instrumentation suppression flag set in context.
+    if otel_context.get_value(_SUPPRESS_KEY):
+        yield None
+        return
+
+    sql = str(sql)  # Ensure SQL is a string for span attributes.
+
+    # Extract operation and target information
+    operation, summary, collection_name = extract_operation_and_target(sql)
+
+    if many:
+        summary = f"{summary} many"
+
+    # Span name follows semantic conventions: {target} or {db.operation.name} {target}
+    if summary:
+        span_name = summary[:255]
+    else:
+        span_name = operation
+
+    # Build attribute set following semantic conventions
+    attrs: dict[str, Any] = {
+        DB_SYSTEM_NAME: db_system_for(db.vendor),
+        DB_NAMESPACE: db.settings_dict.get("NAME"),
+        DB_QUERY_TEXT: sql,  # Already parameterized from Django/Plain
+        DB_QUERY_SUMMARY: summary,
+        DB_OPERATION_NAME: operation,
+    }
+
+    # Add collection name if detected
+    if collection_name:
+        attrs[DB_COLLECTION_NAME] = collection_name
+
+    # Add user attribute
+    if user := db.settings_dict.get("USER"):
+        attrs[DB_USER] = user
+
+    # Network attributes
+    if host := db.settings_dict.get("HOST"):
+        attrs[NETWORK_PEER_ADDRESS] = host
+
+    if port := db.settings_dict.get("PORT"):
+        try:
+            attrs[NETWORK_PEER_PORT] = int(port)
+        except (TypeError, ValueError):
+            pass
+
+    # Add query parameters as attributes when DEBUG is True
+    if settings.DEBUG and params is not None:
+        # Convert params to appropriate format based on type
+        if isinstance(params, dict):
+            # Dictionary params (e.g., for named placeholders)
+            for i, (key, value) in enumerate(params.items()):
+                attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.{key}"] = str(value)
+        elif isinstance(params, list | tuple):
+            # Sequential params (e.g., for %s or ? placeholders)
+            for i, value in enumerate(params):
+                attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.{i + 1}"] = str(value)
+        else:
+            # Single param (rare but possible)
+            attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.1"] = str(params)
+
+    with tracer.start_as_current_span(
+        span_name, kind=SpanKind.CLIENT, attributes=attrs
+    ) as span:
+        yield span
+        span.set_status(trace.StatusCode.OK)
+
+
+@contextmanager
+def suppress_db_tracing():
+    token = otel_context.attach(otel_context.set_value(_SUPPRESS_KEY, True))
+    try:
+        yield
+    finally:
+        otel_context.detach(token)

plain/models/test/pytest.py

@@ -2,6 +2,7 @@ import re
 
 import pytest
 
+from plain.models.otel import suppress_db_tracing
 from plain.signals import request_finished, request_started
 
 from .. import transaction
@@ -60,29 +61,32 @@ def setup_db(request):
 def db(setup_db, request):
     if "isolated_db" in request.fixturenames:
         pytest.fail("The 'db' and 'isolated_db' fixtures cannot be used together")
+
     # Set .cursor() back to the original implementation to unblock it
     BaseDatabaseWrapper.cursor = BaseDatabaseWrapper._enabled_cursor
 
     if not db_connection.features.supports_transactions:
         pytest.fail("Database does not support transactions")
 
-    atomic = transaction.atomic()
-    atomic._from_testcase = True  # TODO remove this somehow?
-    atomic.__enter__()
+    with suppress_db_tracing():
+        atomic = transaction.atomic()
+        atomic._from_testcase = True  # TODO remove this somehow?
+        atomic.__enter__()
 
     yield
 
-    if (
-        db_connection.features.can_defer_constraint_checks
-        and not db_connection.needs_rollback
-        and db_connection.is_usable()
-    ):
-        db_connection.check_constraints()
+    with suppress_db_tracing():
+        if (
+            db_connection.features.can_defer_constraint_checks
+            and not db_connection.needs_rollback
+            and db_connection.is_usable()
+        ):
+            db_connection.check_constraints()
 
-    db_connection.set_rollback(True)
-    atomic.__exit__(None, None, None)
+        db_connection.set_rollback(True)
+        atomic.__exit__(None, None, None)
 
-    db_connection.close()
+        db_connection.close()
 
 
 @pytest.fixture

plain/models/test/utils.py

@@ -1,11 +1,14 @@
 from plain.models import db_connection
+from plain.models.otel import suppress_db_tracing
 
 
 def setup_database(*, verbosity, prefix=""):
     old_name = db_connection.settings_dict["NAME"]
-    db_connection.creation.create_test_db(verbosity=verbosity, prefix=prefix)
+    with suppress_db_tracing():
+        db_connection.creation.create_test_db(verbosity=verbosity, prefix=prefix)
     return old_name
 
 
 def teardown_database(old_name, verbosity):
-    db_connection.creation.destroy_test_db(old_name, verbosity)
+    with suppress_db_tracing():
+        db_connection.creation.destroy_test_db(old_name, verbosity)

{plain_models-0.36.0.dist-info → plain_models-0.37.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.models
-Version: 0.36.0
+Version: 0.37.0
 Summary: Database models for Plain.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE

{plain_models-0.36.0.dist-info → plain_models-0.37.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-plain/models/CHANGELOG.md,sha256=eZWX8ouq5qD7hAMQVKAc7yv8EPI3HQJdvZlmwtDzcrA,4561
+plain/models/CHANGELOG.md,sha256=jfmC_PUfV3p29nRVGxSnDztzD46CIRRud69XtAbPF-Q,5162
 plain/models/README.md,sha256=vsZPev3Fna-Irdcs3-wrOcAoII5LOhXdcWLBMT87CS0,1626
 plain/models/__init__.py,sha256=dnU6MOXs3lGoK31nLWjCqbf7zigkaUccomchz9lNDJ8,2950
 plain/models/aggregates.py,sha256=P0mhsMl1VZt2CVHMuCHnNI8SxZ9citjDLEgioN6NOpo,7240
@@ -21,6 +21,7 @@ plain/models/indexes.py,sha256=fazIZPJgCX5_Bhwk7MQy3YbWOxpHvaCe1dDLGGldTuY,11540
 plain/models/lookups.py,sha256=0tbuMBpd4DlTUeO0IdZPtSO2GcjsSgcbRcj5lYfe87M,24776
 plain/models/manager.py,sha256=zc2W-vTTk3zkDXCds5-TCXgLhVmM4PdQb-qtu-njeLQ,5827
 plain/models/options.py,sha256=AxlxzHY_cKIcuWESeIDM02fzknGl4KN0-Bp5XWr3IVk,23829
+plain/models/otel.py,sha256=OCG6ZXbaQmAwvjjAHwH6ISFXJ651W942m2dFu87Pmi8,5893
 plain/models/preflight.py,sha256=PlS1S2YHEpSKZ57KbTP6TbED98dDDXYSBUk6xMIpgsI,8136
 plain/models/query.py,sha256=DEqiSsNPNtPX6_Cycwemq5XH99CoCi_7y42BEtBi5cE,92648
 plain/models/query_utils.py,sha256=EtKxtyAk36Jou0Uz4beADGENEucQymziVtfp7uJjoSQ,14254
@@ -29,7 +30,7 @@ plain/models/transaction.py,sha256=KqkRDT6aqMgbPA_ch7qO8a9NyDvwY_2FaxM7FkBkcgY,9
 plain/models/utils.py,sha256=rD47CAMH4SsznTe-kUnRUdnaZeZHVv1fwLUiU3KOFW0,1630
 plain/models/backends/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/models/backends/ddl_references.py,sha256=rPgGp1mjcZyIo6aA8OjNvPRv42yCBbvVgk9IEHAcAGc,8096
-plain/models/backends/utils.py,sha256=QFmpqe1FATF7KcLc00OhZbQzM_L9dPvtqptXe4hU4FU,9808
+plain/models/backends/utils.py,sha256=VN9b_hnGeLqndVAcCx00X7KhFC6jY2Tn6J3E62HqDEE,10005
 plain/models/backends/base/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/models/backends/base/base.py,sha256=I5040pUAe7-yNTb9wfMNOYjeiFQLZ5dcRI4rtmVKJ04,26457
 plain/models/backends/base/client.py,sha256=90Ffs6zZYCli3tJjwsPH8TItZ8tz1Pp-zhQa-EpsNqc,937
@@ -111,10 +112,10 @@ plain/models/sql/query.py,sha256=jSnzBoM66dTR-4aJpO-T2ksOc5PSeIQ07ToPEzYj58U,108
 plain/models/sql/subqueries.py,sha256=JkVjYuWyEBpSDFNMOH00RmXxe8V4cERjUQ_ypGepqyo,5847
 plain/models/sql/where.py,sha256=ezE9Clt2BmKo-I7ARsgqZ_aVA-1UdayCwr6ULSWZL6c,12635
 plain/models/test/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-plain/models/test/pytest.py,sha256=5mxY1MHqfCFJ7G39W1DuE0vCHfsfehQQmOyE6vI6caw,3323
-plain/models/test/utils.py,sha256=MxBNWoGMtwAtka7LbxWgilgzv7T5qqJL8ystF2SDJrs,345
-plain_models-0.36.0.dist-info/METADATA,sha256=Pm1uJVIOrhVQl1t-vEBk0jHD0NYU3mEhieE1_m9TX-Q,1921
-plain_models-0.36.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-plain_models-0.36.0.dist-info/entry_points.txt,sha256=IYJAW9MpL3PXyXFWmKmALagAGXC_5rzBn2eEGJlcV04,112
-plain_models-0.36.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
-plain_models-0.36.0.dist-info/RECORD,,
+plain/models/test/pytest.py,sha256=KD5-mxonBxOYIhUh9Ql5uJOIiC9R4t-LYfb6sjA0UdE,3486
+plain/models/test/utils.py,sha256=S3d6zf3OFWDxB_kBJr0tDvwn51bjwDVWKPumv37N-p8,467
+plain_models-0.37.0.dist-info/METADATA,sha256=glPHfgeEYKGSRwOGyDgRljuBZz7hw1L_mshPrS931T8,1921
+plain_models-0.37.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain_models-0.37.0.dist-info/entry_points.txt,sha256=IYJAW9MpL3PXyXFWmKmALagAGXC_5rzBn2eEGJlcV04,112
+plain_models-0.37.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
+plain_models-0.37.0.dist-info/RECORD,,