Use connection string as default query session pool name

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: KirillKurdyukov

docs/opentelemetry.rst

@@ -301,10 +301,14 @@ Operation metrics use stable labels only:
 Operation metrics are recorded for ``ExecuteQuery``, ``Commit``, ``Rollback``,
 ``CreateSession``, and ``BeginTransaction``.
 
-Query session metrics use ``ydb.query.session.pool.name``. The pool name is generated
-automatically, or can be set explicitly with ``QuerySessionPool(..., name="main-pool")``
-for both synchronous and asynchronous pools. ``ydb.query.session.count`` also includes
-``ydb.query.session.state`` with values ``"idle"`` or ``"used"``.
+Query session metrics use ``ydb.query.session.pool.name``. When ``name`` is not
+passed to ``QuerySessionPool``, the SDK uses the YDB connection string of the
+driver — ``<endpoint><database>`` (for example ``grpc://localhost:2136/local``) —
+so the pool is identifiable in dashboards out of the box. Set the label
+explicitly with ``QuerySessionPool(..., name="main-pool")`` for both synchronous
+and asynchronous pools when several pools share a connection string.
+``ydb.query.session.count`` also includes ``ydb.query.session.state`` with values
+``"idle"`` or ``"used"``.
 
 Retry metrics are recorded without attributes.
 

tests/opentelemetry/test_metrics.py

@@ -424,19 +424,49 @@ def test_sync_query_session_pool_stop_removes_observable_metrics(metrics_setup):
     assert _points(metrics_setup, QUERY_SESSION_MIN) == []
 
 
-def test_sync_query_session_pool_uses_endpoint_as_default_pool_name(metrics_setup):
+def test_query_session_pool_name_prefers_explicit_name():
+    from ydb.opentelemetry.metrics import query_session_pool_name
+
+    assert query_session_pool_name("my-pool", endpoint="grpc://localhost:2136", database="/local") == "my-pool"
+
+
+def test_query_session_pool_name_uses_connection_string():
+    from ydb.opentelemetry.metrics import query_session_pool_name
+
+    assert (
+        query_session_pool_name(None, endpoint="grpc://localhost:2136", database="/local")
+        == "grpc://localhost:2136/local"
+    )
+
+
+def test_query_session_pool_name_normalizes_database_without_leading_slash():
+    from ydb.opentelemetry.metrics import query_session_pool_name
+
+    assert (
+        query_session_pool_name(None, endpoint="grpc://localhost:2136", database="local")
+        == "grpc://localhost:2136/local"
+    )
+
+
+def test_query_session_pool_name_falls_back_to_counter_when_nothing_known():
+    from ydb.opentelemetry.metrics import query_session_pool_name
+
+    assert query_session_pool_name(None, endpoint=None, database=None).startswith("query-session-pool-")
+
+
+def test_sync_query_session_pool_uses_connection_string_as_default_pool_name(metrics_setup):
     from tests.opentelemetry.conftest import FakeDriverConfig
     from ydb.opentelemetry.metrics import QUERY_SESSION_MAX
     from ydb.query.pool import QuerySessionPool
 
     class FakeDriver:
-        _driver_config = FakeDriverConfig(endpoint="grpc://localhost:2136")
+        _driver_config = FakeDriverConfig(endpoint="grpc://localhost:2136", database="/local")
 
     QuerySessionPool(driver=FakeDriver(), size=42)
 
     assert _single_point(metrics_setup, QUERY_SESSION_MAX).value == 42
     assert _single_point(metrics_setup, QUERY_SESSION_MAX).attributes == {
-        "ydb.query.session.pool.name": "grpc://localhost:2136"
+        "ydb.query.session.pool.name": "grpc://localhost:2136/local"
     }
 
 
@@ -467,19 +497,19 @@ async def test_async_query_session_pool_stop_removes_observable_metrics(metrics_
 
 
 @pytest.mark.asyncio
-async def test_async_query_session_pool_uses_endpoint_as_default_pool_name(metrics_setup):
+async def test_async_query_session_pool_uses_connection_string_as_default_pool_name(metrics_setup):
     from tests.opentelemetry.conftest import FakeDriverConfig
     from ydb.aio.query.pool import QuerySessionPool
     from ydb.opentelemetry.metrics import QUERY_SESSION_MAX
 
     class FakeDriver:
-        _driver_config = FakeDriverConfig(endpoint="grpc://localhost:2136")
+        _driver_config = FakeDriverConfig(endpoint="grpc://localhost:2136", database="/local")
 
     QuerySessionPool(driver=FakeDriver(), size=24)
 
     assert _single_point(metrics_setup, QUERY_SESSION_MAX).value == 24
     assert _single_point(metrics_setup, QUERY_SESSION_MAX).attributes == {
-        "ydb.query.session.pool.name": "grpc://localhost:2136"
+        "ydb.query.session.pool.name": "grpc://localhost:2136/local"
     }
 
 

ydb/aio/query/pool.py

@@ -65,7 +65,11 @@ def __init__(
         self._loop = asyncio.get_running_loop() if loop is None else loop
         self._query_client_settings = query_client_settings
         driver_config = getattr(driver, "_driver_config", None)
-        self._metrics_pool_name = query_session_pool_name(name, getattr(driver_config, "endpoint", None))
+        self._metrics_pool_name = query_session_pool_name(
+            name,
+            endpoint=getattr(driver_config, "endpoint", None),
+            database=getattr(driver_config, "database", None),
+        )
         record_query_session_max(self._size, self._metrics_pool_name)
 
     async def _create_new_session(self):

ydb/opentelemetry/metrics.py

@@ -154,8 +154,30 @@ def next_query_session_pool_name() -> str:
     return "query-session-pool-%d" % next(_pool_name_counter)
 
 
-def query_session_pool_name(name: Optional[str], endpoint: Optional[str]) -> str:
-    return name or endpoint or next_query_session_pool_name()
+def query_session_pool_name(
+    name: Optional[str],
+    endpoint: Optional[str] = None,
+    database: Optional[str] = None,
+) -> str:
+    """Return a stable label for the ``ydb.query.session.pool.name`` metric attribute.
+
+    If the user passed an explicit ``name`` to ``QuerySessionPool``, it wins. Otherwise
+    the SDK builds a YDB connection string in the canonical ``<endpoint><database>``
+    form (e.g. ``grpc://localhost:2136/local``) so that the pool is identifiable in
+    dashboards without leaking driver-internal counters. When neither piece of the
+    connection string is available, a process-unique counter name is used as a last
+    resort.
+    """
+    if name:
+        return name
+    endpoint_part = endpoint or ""
+    database_part = database or ""
+    if database_part and not database_part.startswith("/"):
+        database_part = "/" + database_part
+    connection_string = endpoint_part + database_part
+    if connection_string:
+        return connection_string
+    return next_query_session_pool_name()
 
 
 def _set_metrics_registry(metrics_registry: MetricRegistry) -> None:

ydb/query/pool.py

@@ -75,7 +75,11 @@ def __init__(
         self._lock = threading.RLock()
         self._query_client_settings = query_client_settings
         driver_config = getattr(driver, "_driver_config", None)
-        self._metrics_pool_name = query_session_pool_name(name, getattr(driver_config, "endpoint", None))
+        self._metrics_pool_name = query_session_pool_name(
+            name,
+            endpoint=getattr(driver_config, "endpoint", None),
+            database=getattr(driver_config, "database", None),
+        )
         record_query_session_max(self._size, self._metrics_pool_name)
 
     def _create_new_session(self, timeout: Optional[float]):