Advertise ydb-sdk-tracing token in x-ydb-sdk-build-info when tracing is on

While a tracing provider is installed the SDK appends ydb-sdk-tracing/0.1.0 to
the x-ydb-sdk-build-info header (native SDK, then SDK-owned feature tokens, then
custom driver headers). The token list is aggregated by
ydb.observability.sdk_build_info_tokens so future features (e.g. metrics) plug in
with a single line.

Author: vgvoleg

CHANGELOG.md

@@ -1,4 +1,5 @@
 * Introduce `ydb.observability` — vendor-neutral tracing entrypoint with a `TracingProvider` interface; `enable_tracing(provider)` accepts any implementation (custom or OpenTelemetry) and replaces the previously installed one. The SDK core no longer imports `opentelemetry`, so tracing can be enabled without the OpenTelemetry packages by supplying a custom provider
+* When tracing is enabled the SDK appends a `ydb-sdk-tracing/0.1.0` token to the `x-ydb-sdk-build-info` header, so the server can distinguish requests from tracing-enabled clients
 
 ## 3.30.0 ##
 * Query session attach stream handles `NodeShutdown` and `SessionShutdown` session hints: on `NodeShutdown` the session's node connection is pessimized and the session is retired, on `SessionShutdown` the session is retired without touching the node

tests/tracing/test_observability_enable.py

@@ -36,6 +36,8 @@
     span_finish_callback,
 )
 
+from ydb.ydb_version import VERSION
+
 from .conftest import FakeDriverConfig
 
 
@@ -301,6 +303,60 @@ def get_trace_metadata(self):
         assert provider.calls == 1
 
 
+class _BuildInfoCfg:
+    database = None
+    credentials = None
+
+
+class TestSdkBuildInfoHeader:
+    """Enabling tracing advertises a ``ydb-sdk-tracing`` token in x-ydb-sdk-build-info."""
+
+    def test_tokens_reflect_active_provider(self):
+        from ydb.observability import sdk_build_info_tokens
+
+        assert sdk_build_info_tokens() == []
+        enable_tracing(RecordingProvider())
+        assert sdk_build_info_tokens() == ["ydb-sdk-tracing/0.1.0"]
+        disable_tracing()
+        assert sdk_build_info_tokens() == []
+
+    def test_header_gains_tracing_token_when_enabled(self):
+        from ydb.connection import _construct_metadata
+
+        def build_info():
+            return dict(_construct_metadata(_BuildInfoCfg(), None))["x-ydb-sdk-build-info"]
+
+        assert "ydb-sdk-tracing" not in build_info()
+
+        enable_tracing(RecordingProvider())
+        header = build_info()
+        disable_tracing()
+
+        assert header == f"ydb-python-sdk/{VERSION};ydb-sdk-tracing/0.1.0"
+
+    def test_tracing_token_precedes_driver_additional_headers(self):
+        from ydb.connection import _construct_metadata
+
+        class _Cfg(_BuildInfoCfg):
+            _additional_sdk_headers = ("lib1/1.0",)
+
+        enable_tracing(RecordingProvider())
+        header = dict(_construct_metadata(_Cfg(), None))["x-ydb-sdk-build-info"]
+        disable_tracing()
+
+        # native SDK, then SDK-owned tracing token, then custom driver headers
+        assert header == f"ydb-python-sdk/{VERSION};ydb-sdk-tracing/0.1.0;lib1/1.0"
+
+    async def test_header_async_parity(self):
+        from ydb.aio.connection import _construct_metadata
+
+        enable_tracing(RecordingProvider())
+        header = dict(await _construct_metadata(_BuildInfoCfg(), None))["x-ydb-sdk-build-info"]
+        disable_tracing()
+
+        assert header == f"ydb-python-sdk/{VERSION};ydb-sdk-tracing/0.1.0"
+
+
 class TestSplitEndpoint:
     """Cover every branch of the endpoint parser."""
 

ydb/aio/connection.py

@@ -26,6 +26,7 @@
 from ydb.driver import DriverConfig
 from ydb.settings import BaseRequestSettings
 from ydb import issues
+from ydb.observability import sdk_build_info_tokens
 from ydb.observability.tracing import get_trace_metadata
 
 # Workaround for good IDE and universal for runtime
@@ -71,7 +72,8 @@ async def _construct_metadata(
         if settings.request_type is not None:
             metadata.append((YDB_REQUEST_TYPE_HEADER, settings.request_type))
 
-    metadata.append(_utilities.x_ydb_sdk_build_info_header(getattr(driver_config, "_additional_sdk_headers", ())))
+    additional_sdk_headers = (*sdk_build_info_tokens(), *getattr(driver_config, "_additional_sdk_headers", ()))
+    metadata.append(_utilities.x_ydb_sdk_build_info_header(additional_sdk_headers))
 
     metadata.extend(get_trace_metadata())
 

ydb/connection.py

@@ -24,6 +24,7 @@
 import grpc
 from . import issues, _apis, _utilities
 from . import default_pem
+from .observability import sdk_build_info_tokens
 from .observability.tracing import get_trace_metadata
 
 _stubs_list = (
@@ -179,7 +180,8 @@ def _construct_metadata(driver_config, settings):
             metadata.append((YDB_REQUEST_TYPE_HEADER, settings.request_type))
         metadata.extend(getattr(settings, "headers", []))
 
-    metadata.append(_utilities.x_ydb_sdk_build_info_header(getattr(driver_config, "_additional_sdk_headers", ())))
+    additional_sdk_headers = (*sdk_build_info_tokens(), *getattr(driver_config, "_additional_sdk_headers", ()))
+    metadata.append(_utilities.x_ydb_sdk_build_info_header(additional_sdk_headers))
 
     metadata.extend(get_trace_metadata())
 

ydb/observability/__init__.py

@@ -13,7 +13,7 @@
 every span is a :class:`~ydb.observability.tracing.NoopSpan`.
 """
 
-from typing import Optional
+from typing import List, Optional
 
 from ydb.observability.tracing import (
     NoopSpan,
@@ -22,6 +22,7 @@
     SpanName,
     TracingProvider,
     _registry,
+    _tracing_build_info_tokens,
 )
 
 
@@ -48,6 +49,19 @@ def get_active_provider() -> Optional[TracingProvider]:
     return _registry.get_provider() if _registry.is_active() else None
 
 
+def sdk_build_info_tokens() -> List[str]:
+    """All ``x-ydb-sdk-build-info`` feature tokens contributed by observability.
+
+    Aggregated across observability features so the SDK build-info header advertises
+    every capability the client has turned on. Tracing contributes
+    ``ydb-sdk-tracing/<v>`` while active; future features (e.g. metrics via
+    ``enable_metrics``) append their own tokens here.
+    """
+    tokens: List[str] = []
+    tokens.extend(_tracing_build_info_tokens())
+    return tokens
+
+
 __all__ = [
     "NoopSpan",
     "NoopTracingProvider",

ydb/observability/tracing.py

@@ -146,6 +146,19 @@ def get_trace_metadata() -> List[Tuple[str, str]]:
     return list(_registry.get_trace_metadata())
 
 
+TRACING_SDK_BUILD_INFO = "ydb-sdk-tracing/0.1.0"
+
+
+def _tracing_build_info_tokens() -> List[str]:
+    """Tracing's contribution to the ``x-ydb-sdk-build-info`` header.
+
+    Returns ``["ydb-sdk-tracing/0.1.0"]`` once a provider is installed, otherwise an
+    empty list. Aggregated with other features by
+    :func:`ydb.observability.sdk_build_info_tokens`.
+    """
+    return [TRACING_SDK_BUILD_INFO] if _registry.is_active() else []
+
+
 def _split_endpoint(endpoint: Optional[str]) -> Tuple[str, int]:
     ep = endpoint or ""
     if ep.startswith("grpcs://"):