postgres: fix ERROR-level log spam from explain_parameterized_queries on type mismatch

UndefinedFunction and DatatypeMismatch raised during EXPLAIN EXECUTE (when
_explain_prepared_statement runs with untyped NULL params against non-text columns)
previously escaped the function body to @tracked_method, which logged at ERROR
with no rate limiting and no _explain_errors_cache write — causing hundreds of
thousands of ERROR logs per day on ORM-generated queries.

Catch these errors before they reach the decorator: log at DEBUG, return None as
a sentinel. explain_statement maps None -> DBExplainError.undefined_function so
the failure stays observable in collection_errors telemetry, consistent with how
the PREPARE phase handles the same error class (PRs #19969/#19998).

The April 2025 PREPARE-phase fixes left the EXECUTE phase unpatched; this closes
that gap. Confirmed unfixed through current master (HEAD 22faef8).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: pierreln-dd

postgres/datadog_checks/postgres/explain_parameterized_queries.py

@@ -97,7 +97,9 @@ def explain_statement(self, dbname, statement, obfuscated_statement, query_signa
 
             try:
                 result = self._explain_prepared_statement(conn, statement, obfuscated_statement, query_signature)
-                if result:
+                if result is None:
+                    return None, DBExplainError.undefined_function, None
+                elif result:
                     plan = result[0][0][0]
                     return plan, DBExplainError.explained_with_prepared_statement, None
                 else:
@@ -160,6 +162,17 @@ def _explain_prepared_statement(self, conn, statement, obfuscated_statement, que
                 EXPLAIN_QUERY.format(explain_function=self._explain_function),
                 (prepared_statement_query,),
             )
+        except (psycopg.errors.UndefinedFunction, psycopg.errors.DatatypeMismatch) as e:
+            logged_statement = obfuscated_statement
+            if self._config.log_unobfuscated_plans:
+                logged_statement = statement
+            logger.debug(
+                'Failed to explain parameterized statement(%s)=[%s] due to type mismatch | err=[%s]',
+                query_signature,
+                logged_statement,
+                e,
+            )
+            return None
         except Exception as e:
             logged_statement = obfuscated_statement
             if self._config.log_unobfuscated_plans:

postgres/tests/test_explain_parameterized_queries.py

@@ -247,6 +247,45 @@ def test_create_prepared_statement_exception(integration_check, dbm_instance):
             )
 
 
+@pytest.mark.unit
+@requires_over_12
+@pytest.mark.parametrize(
+    "exception_class",
+    [
+        psycopg.errors.UndefinedFunction,
+        psycopg.errors.DatatypeMismatch,
+    ],
+)
+def test_explain_prepared_statement_type_mismatch_no_error_log(integration_check, dbm_instance, exception_class):
+    """Type mismatch errors from EXPLAIN EXECUTE must be handled at DEBUG, not ERROR.
+
+    When _explain_prepared_statement encounters UndefinedFunction or DatatypeMismatch (caused by
+    untyped NULL parameters against non-text columns), it must return None (sentinel) rather than
+    raise. If it raises, @tracked_method logs at ERROR level for every explain attempt on every
+    affected query signature with no rate limiting. explain_statement maps None -> undefined_function
+    so the failure is still observable in collection_errors telemetry.
+    """
+    check = integration_check(dbm_instance)
+    epq = check.statement_samples._explain_parameterized_queries
+
+    with mock.patch.object(epq, '_generate_prepared_statement_query', return_value="EXECUTE dd_test(null)"):
+        with mock.patch.object(
+            epq,
+            '_execute_query_and_fetch_rows',
+            side_effect=exception_class("operator does not exist: bigint = text"),
+        ):
+            with mock.patch.object(check.log, 'exception') as mock_exception:
+                result = epq._explain_prepared_statement(
+                    None,
+                    "SELECT id FROM t WHERE id = $1",
+                    "SELECT id FROM t WHERE id = $1",
+                    "test_sig",
+                )
+
+    assert result is None
+    mock_exception.assert_not_called()
+
+
 @pytest.mark.unit
 @pytest.mark.parametrize(
     "query,statement_is_parameterized_query",