SNOW-3351450: emit client_connection_identifier_shape in-band telemetry (#2877)

## Summary

Capture the shape of connection-identifier inputs (which of `account` /
`region` / `host` the caller supplied, and whether the raw account
string carries dot/dash markers) at the earliest parse point in
`SnowflakeConnection.__config`, then emit a single in-band
`client_connection_identifier_shape` telemetry record per successful
login alongside the existing `_log_minicore_import` /
`_log_nanoarrow_import` hooks. Mirrors the gosnowflake reference
implementation in
[snowflakedb/gosnowflake#1797](snowflakedb/gosnowflake#1797).

Time-boxed data collection ahead of the Northstar migration. The
emission honors the post-login `CLIENT_TELEMETRY_ENABLED` parameter
(automatic via ``self.telemetry_enabled`` inside ``_log_telemetry``) and
a local `SF_TELEMETRY_DISABLE_CONNECTION_SHAPE=true` env-var kill switch
(case-insensitive). No hostname or account value is included in the
payload — only five stringified booleans describing intent.

Removal is tracked in SNOW-3548350 (target: 2026-11-30); all new code is
marked with a `TODO(SNOW-3548350)` so future grep finds it.

## Changes

- **New** `src/snowflake/connector/connection_identifier_shape.py`:
``ConnectionIdentifierShape`` dataclass + pure
``record_input_shape(kwargs)`` helper. Captures the dash signal only
from the *account portion* of the raw account string (the part before
any first dot), so region-tail dashes (the `-east-` in
`"myacct.us-east-1"`) aren't miscounted as `account_org_provided`.
- **Capture site** at the very top of ``SnowflakeConnection.__config``,
idempotent so a re-config with normalized values cannot overwrite the
original user intent. Runs before the ``setattr`` loop, before
``construct_hostname`` for host inference, and before ``parse_account``
strips the ``.global`` suffix.
- **Emission site** mirrors ``_log_minicore_import`` exactly:
``_log_connection_identifier_shape()`` is invoked from ``__init__``
right after the existing minicore/nanoarrow hooks (sync path) and from
``aio._connection.SnowflakeConnection.connect`` right after
``_log_telemetry_imported_packages()`` (async path). The async class has
its own ``async def _log_connection_identifier_shape`` override because
``_log_telemetry`` is overridden as an awaitable there; calling the sync
emit from the async path would return an unawaited coroutine.
- **TelemetryField** picks up one new event type
(``CONNECTION_IDENTIFIER_SHAPE = "client_connection_identifier_shape"``)
and five payload keys (``KEY_ACCOUNT_PROVIDED`` etc.) so the wire format
matches the Go reference byte-for-byte.
- **DESCRIPTION.md** entry under ``Upcoming Release`` mirroring the
gosnowflake CHANGELOG voice.

## Test plan

- New `test/unit/test_connection_identifier_shape.py` — 13 table-driven
cases exercising ``record_input_shape`` over the truth table (locator,
dotted account, org-prefixed account, region-dash isolation, host-only,
all-three, empty/None/non-string defensive paths, irrelevant-kwargs
isolation).
- New `test/unit/test_connection_identifier_shape_telemetry.py` — 16
cases exercising the emission method: payload field check, skip when
shape unset / attribute missing, env-switch kill (case-insensitive
``true`` only), env-switch off-by-default for every other value
including former truthy aliases (``1`` / ``yes``) so the new contract is
unambiguous.
- 643 existing unit tests still pass locally; the 3 failures + 27 errors
observed are pre-existing arrow-stream-extension / wiremock requirements
unrelated to this change.

Author: sfc-gh-boler

DESCRIPTION.md

@@ -9,6 +9,7 @@ Source code is also available at: https://github.com/snowflakedb/snowflake-conne
 # Release Notes
 - Upcoming Release
   - Fixed sdist to only install the minicore binary matching the current platform (SNOW-3526469). Previous 4.x releases copied every platform's minicore `.so`/`.dylib`/`.dll` into the install prefix, breaking downstream packagers (e.g. Homebrew) whose audits reject foreign-arch binaries.
+  - Added one in-band telemetry record per successful login describing which connection-identifier fields the user supplied (`account_provided`, `account_with_region`, `account_org_provided`, `region_provided`, `host_provided`). No hostname or account value is included. This is gated by the existing server-side `CLIENT_TELEMETRY_ENABLED` parameter and can additionally be disabled locally by setting `SF_TELEMETRY_DISABLE_CONNECTION_SHAPE=true`. The telemetry collection is time-boxed and will be removed in a future release.
 
 - v4.5.0(May 12,2026)
   - Fixed `write_pandas` temp stage name collisions (SNOW-3481510). The old PRNG could produce identical name sequences in forked processes (e.g. Notebook kernels), causing `CREATE TEMPORARY STAGE` to fail with "Object already exists".

src/snowflake/connector/_connection_identifier_shape.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python
+"""Capture user-supplied connection-identifier provenance for in-band telemetry.
+
+The shape captured here is consumed by ``SnowflakeConnection._log_connection_identifier_shape``
+and emitted as a single ``client_connection_identifier_shape`` telemetry event
+per successful login. The capture function inspects the raw kwargs passed to
+``SnowflakeConnection.__config`` before any normalization (host inference,
+account stripping of ``.global``, region extraction from dotted account) runs,
+so the shape reflects user intent rather than the final post-normalization
+state of the connection.
+
+Removal of this module and the emission it backs is tracked in SNOW-3548350
+(target: 2026-11-30).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from .telemetry import TelemetryField
+
+
+@dataclass(frozen=True)
+class ConnectionIdentifierShape:
+    """Provenance of connection-identifier fields the user supplied.
+
+    All fields describe what the user supplied at the moment of input — they
+    reflect intent, not the final post-normalization state of the connection.
+
+    - ``account_provided``: the user explicitly set the ``account`` parameter
+      (via ``connect(account=...)``, kwargs, or ``connections.toml`` merged
+      into kwargs before ``__config`` runs).
+    - ``account_with_region``: the raw account string the user typed contained
+      a dot (e.g. ``"myacct.us-east-1"``), signaling the deprecated
+      ``account.region`` embedded form. Set only on the raw input.
+    - ``account_org_provided``: the raw account string carried a dash in its
+      account portion (e.g. ``"myorg-myacct"``), signaling the org-prefixed
+      form. Region-portion dashes (e.g. the ``-east-`` in
+      ``"myacct.us-east-1"``) are intentionally not counted; only the portion
+      before the first ``.`` is examined.
+    - ``region_provided``: the user explicitly set the ``region`` parameter as
+      a distinct kwarg. A region embedded inside a dotted account string is
+      NOT ``region_provided``; that's ``account_with_region``.
+    - ``host_provided``: the user explicitly set the ``host`` parameter.
+    """
+
+    account_provided: bool = False
+    account_with_region: bool = False
+    account_org_provided: bool = False
+    region_provided: bool = False
+    host_provided: bool = False
+
+
+def _is_user_supplied_string(value: Any) -> bool:
+    """A kwarg counts as user-supplied iff it's a non-empty string. Non-string
+    truthy values (e.g. an accidentally-passed ``True`` / ``int``) are not
+    treated as provided here — the regular ``__config`` validation will warn
+    or error on them later, and shape capture is best kept conservative."""
+    return isinstance(value, str) and value != ""
+
+
+def record_input_shape(kwargs: Mapping[str, Any]) -> ConnectionIdentifierShape:
+    """Capture the connection-identifier shape from the raw kwargs that
+    ``SnowflakeConnection.__config`` receives.
+
+    Must be invoked before any normalization (the ``setattr`` loop in
+    ``__config``, the ``construct_hostname`` call for host inference, or any
+    ``parse_account`` stripping) — otherwise inferred values are
+    indistinguishable from user-supplied ones and ``host_provided`` /
+    ``account_provided`` are no longer trustworthy.
+    """
+    account = kwargs.get("account")
+    region = kwargs.get("region")
+    host = kwargs.get("host")
+
+    account_provided = _is_user_supplied_string(account)
+    account_with_region = False
+    account_org_provided = False
+    if account_provided:
+        # Only a dot at position > 0 splits the string into account / region;
+        # a leading dot (pathological input like ``.us-east-1``) leaves the
+        # whole string as the account portion. Mirrors gosnowflake's
+        # ``recordAccountShape`` (internal/config/dsn.go), which gates on
+        # ``i > 0`` so the dash search runs against the full raw value when
+        # there is no real account/region split.
+        dot_index = account.find(".")
+        if dot_index > 0:
+            account_with_region = True
+            account_portion = account[:dot_index]
+        else:
+            account_portion = account
+        # ``Contains(accountPortion, "-")`` in Go — any dash anywhere in the
+        # account portion (including position 0) flips the flag. The
+        # region-tail dashes are excluded by virtue of being outside
+        # ``account_portion``, not by a position check.
+        account_org_provided = "-" in account_portion
+
+    return ConnectionIdentifierShape(
+        account_provided=account_provided,
+        account_with_region=account_with_region,
+        account_org_provided=account_org_provided,
+        region_provided=_is_user_supplied_string(region),
+        host_provided=_is_user_supplied_string(host),
+    )
+
+
+def build_shape_telemetry_message(shape: ConnectionIdentifierShape) -> dict[str, str]:
+    """Build the wire-format payload for the ``client_connection_identifier_shape``
+    in-band telemetry event from a captured ``ConnectionIdentifierShape``.
+
+    Hoisted out of the sync / async ``_log_connection_identifier_shape``
+    emitters so both branches stay in lockstep — the five payload keys
+    (``account_provided``, ``account_with_region``, ``account_org_provided``,
+    ``region_provided``, ``host_provided``) and their stringified-lowercase
+    boolean values are byte-identical across sibling drivers and must remain
+    so. Changing this builder is the only place that affects the wire format.
+
+    Booleans are stringified as lowercase ``"true"`` / ``"false"`` (matching
+    JSON-style boolean text) for cross-driver parity with gosnowflake's
+    ``strconv.FormatBool`` and the JDBC / Node.js siblings.
+
+    TODO(SNOW-3548350): remove with the telemetry emission
+    (target: 2026-11-30).
+    """
+    return {
+        TelemetryField.KEY_TYPE.value: TelemetryField.CONNECTION_IDENTIFIER_SHAPE.value,
+        TelemetryField.KEY_ACCOUNT_PROVIDED.value: str(shape.account_provided).lower(),
+        TelemetryField.KEY_ACCOUNT_WITH_REGION.value: str(
+            shape.account_with_region
+        ).lower(),
+        TelemetryField.KEY_ACCOUNT_ORG_PROVIDED.value: str(
+            shape.account_org_provided
+        ).lower(),
+        TelemetryField.KEY_REGION_PROVIDED.value: str(shape.region_provided).lower(),
+        TelemetryField.KEY_HOST_PROVIDED.value: str(shape.host_provided).lower(),
+    }

src/snowflake/connector/aio/_connection.py

@@ -24,9 +24,14 @@
     ProgrammingError,
 )
 
+from .._connection_identifier_shape import (
+    ConnectionIdentifierShape,
+    build_shape_telemetry_message,
+)
 from .._query_context_cache import QueryContextCache
 from ..compat import IS_LINUX, quote, urlencode
 from ..config_manager import CONFIG_MANAGER, _get_default_connection_params
+from ..connection import _DISABLE_CONNECTION_SHAPE_ENV
 from ..connection import DEFAULT_CONFIGURATION as DEFAULT_CONFIGURATION_SYNC
 from ..connection import SnowflakeConnection as SnowflakeConnectionSync
 from ..connection import _get_private_bytes_from_file
@@ -783,6 +788,42 @@ async def _log_telemetry_imported_packages(self) -> None:
                 )
             )
 
+    async def _log_connection_identifier_shape(self) -> None:
+        """Async counterpart to ``SnowflakeConnectionSync._log_connection_identifier_shape``.
+
+        The sync implementation reaches for ``self._log_telemetry`` directly,
+        which is overridden as an awaitable on the async class — so the sync
+        method's call to ``self._log_telemetry(...)`` would return an
+        unawaited coroutine here. This override mirrors the sync logic and
+        awaits the emission instead.
+
+        TODO(SNOW-3548350): remove with the telemetry emission
+        (target: 2026-11-30).
+        """
+        # See sync sibling for the strict (no ``strip``) semantics.
+        if os.environ.get(_DISABLE_CONNECTION_SHAPE_ENV, "").lower() == "true":
+            logger.debug(
+                "connection-identifier-shape telemetry disabled via %s",
+                _DISABLE_CONNECTION_SHAPE_ENV,
+            )
+            return
+        shape: ConnectionIdentifierShape | None = getattr(
+            self, "_connection_identifier_shape", None
+        )
+        if shape is None:
+            logger.debug(
+                "connection-identifier-shape telemetry skipped: shape not captured"
+            )
+            return
+        ts = get_time_millis()
+        await self._log_telemetry(
+            TelemetryData.from_telemetry_data_dict(
+                from_dict=build_shape_telemetry_message(shape),
+                timestamp=ts,
+                connection=self,
+            )
+        )
+
     async def _next_sequence_counter(self) -> int:
         """Gets next sequence counter. Used internally."""
         async with self._lock_sequence_counter:
@@ -1099,6 +1140,7 @@ async def connect(self, **kwargs) -> None:
             await self.__open_connection()
         self._telemetry = TelemetryClient(self._rest)
         await self._log_telemetry_imported_packages()
+        await self._log_connection_identifier_shape()
 
     def cursor(self, cursor_class: type[CursorCls] = SnowflakeCursor) -> CursorCls:
         logger.debug("cursor")

src/snowflake/connector/connection.py

@@ -38,6 +38,11 @@
 from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
 
 from . import errors
+from ._connection_identifier_shape import (
+    ConnectionIdentifierShape,
+    build_shape_telemetry_message,
+    record_input_shape,
+)
 from ._query_context_cache import QueryContextCache
 from ._utils import (
     _DEFAULT_VALUE_SERVER_DOP_CAP_FOR_FILE_TRANSFER,
@@ -161,6 +166,13 @@
 MAX_CLIENT_FETCH_THREADS = 1024
 DEFAULT_BACKOFF_POLICY = exponential_backoff()
 
+# Local kill switch for the client_connection_identifier_shape in-band
+# telemetry event (case-insensitive "true" disables emission). Sibling
+# drivers use the same env-var name for the same purpose.
+# TODO(SNOW-3548350): remove together with the telemetry emission
+# (target: 2026-11-30).
+_DISABLE_CONNECTION_SHAPE_ENV = "SF_TELEMETRY_DISABLE_CONNECTION_SHAPE"
+
 
 def DefaultConverterClass() -> type:
     if IS_WINDOWS:
@@ -699,6 +711,7 @@ def __init__(
         self._log_telemetry_imported_packages()
         self._log_nanoarrow_import()
         self._log_minicore_import()
+        self._log_connection_identifier_shape()
         # check SNOW-1218851 for long term improvement plan to refactor ocsp code
         atexit.register(self._close_at_exit)
 
@@ -1655,6 +1668,18 @@ def __open_connection(self):
     def __config(self, **kwargs):
         """Sets up parameters in the connection object."""
         logger.debug("__config")
+        # Capture connection-identifier shape from the raw user-supplied kwargs
+        # before any normalization (the setattr loop below, construct_hostname
+        # at "account" handling, or parse_account further down) runs.
+        # Idempotent: only set on the first __config call so the original
+        # user intent isn't overwritten by a later reconfigure with derived
+        # values. Consumed by _log_connection_identifier_shape.
+        # TODO(SNOW-3548350): remove with the telemetry emission
+        # (target: 2026-11-30).
+        if getattr(self, "_connection_identifier_shape", None) is None:
+            self._connection_identifier_shape: ConnectionIdentifierShape = (
+                record_input_shape(kwargs)
+            )
         # Handle special cases first
         if "sequence_counter" in kwargs:
             self.sequence_counter = kwargs["sequence_counter"]
@@ -2588,6 +2613,47 @@ def _log_nanoarrow_import(self):
             )
         )
 
+    def _log_connection_identifier_shape(self):
+        """Emit a single client_connection_identifier_shape in-band telemetry
+        record describing which connection-identifier fields the user supplied.
+
+        Honors a local environment kill switch
+        ``SF_TELEMETRY_DISABLE_CONNECTION_SHAPE`` (case-insensitive ``"true"``)
+        and the post-login ``CLIENT_TELEMETRY_ENABLED`` server parameter (via
+        ``self.telemetry_enabled`` consulted inside ``_log_telemetry``).
+
+        TODO(SNOW-3548350): remove together with the supporting
+        ``ConnectionIdentifierShape`` capture (target: 2026-11-30).
+        """
+        # Mirrors gosnowflake's ``strings.EqualFold(os.Getenv(...), "true")``:
+        # case-insensitive ``"true"`` only, with NO surrounding-whitespace
+        # tolerance. Keeping the comparison strict here means a shell
+        # accidentally exporting ``" true "`` (with stray whitespace) leaves
+        # the emission enabled instead of silently disabling it, matching the
+        # Go / Node.js / JDBC siblings byte-for-byte.
+        if os.environ.get(_DISABLE_CONNECTION_SHAPE_ENV, "").lower() == "true":
+            logger.debug(
+                "connection-identifier-shape telemetry disabled via %s",
+                _DISABLE_CONNECTION_SHAPE_ENV,
+            )
+            return
+        shape: ConnectionIdentifierShape | None = getattr(
+            self, "_connection_identifier_shape", None
+        )
+        if shape is None:
+            logger.debug(
+                "connection-identifier-shape telemetry skipped: shape not captured"
+            )
+            return
+        ts = get_time_millis()
+        self._log_telemetry(
+            TelemetryData.from_telemetry_data_dict(
+                from_dict=build_shape_telemetry_message(shape),
+                timestamp=ts,
+                connection=self,
+            )
+        )
+
     def _log_telemetry_imported_packages(self) -> None:
         if self._log_imported_packages_in_telemetry:
             # filter out duplicates caused by submodules

src/snowflake/connector/telemetry.py

@@ -44,6 +44,11 @@ class TelemetryField(Enum):
     NANOARROW_IMPORT = "nanoarrow_import"
     # multi-statement usage
     MULTI_STATEMENT = "client_multi_statement_query"
+    # Connection-identifier shape (see connection_identifier_shape.py).
+    # TODO(SNOW-3548350): remove this event type and the five KEY_*_PROVIDED /
+    # KEY_ACCOUNT_WITH_REGION keys below together with the emission
+    # (target: 2026-11-30).
+    CONNECTION_IDENTIFIER_SHAPE = "client_connection_identifier_shape"
     # Keys for telemetry data sent through either in-band or out-of-band telemetry
     KEY_TYPE = "type"
     KEY_SOURCE = "source"
@@ -54,6 +59,17 @@ class TelemetryField(Enum):
     KEY_REASON = "reason"
     KEY_VALUE = "value"
     KEY_EXCEPTION = "exception"
+    # Payload keys for the client_connection_identifier_shape event. Values
+    # are stringified booleans ("true" / "false") to match the existing
+    # in-band telemetry style used by sibling drivers (Go / JDBC). See the
+    # docstring on ConnectionIdentifierShape for the semantic meaning.
+    # TODO(SNOW-3548350): remove together with CONNECTION_IDENTIFIER_SHAPE
+    # above (target: 2026-11-30).
+    KEY_ACCOUNT_PROVIDED = "account_provided"
+    KEY_ACCOUNT_WITH_REGION = "account_with_region"
+    KEY_ACCOUNT_ORG_PROVIDED = "account_org_provided"
+    KEY_REGION_PROVIDED = "region_provided"
+    KEY_HOST_PROVIDED = "host_provided"
     # Reserved UpperCamelName keys
     KEY_ERROR_NUMBER = "ErrorNumber"
     KEY_ERROR_MESSAGE = "ErrorMessage"

test/integ/aio_it/test_connection_async.py

@@ -1646,9 +1646,9 @@ async def test_disable_telemetry(conn_cnx, caplog):
         async with conn_cnx() as conn:
             async with conn.cursor() as cur:
                 await (await cur.execute("select 1")).fetchall()
-            assert (
-                len(conn._telemetry._log_batch) == 3
-            )  # 3 events are `import package`, `fetch first`, `fetch last`
+            assert len(conn._telemetry._log_batch) == 4  # 4 events: import package,
+            # client_connection_identifier_shape (SNOW-3548350; remove with
+            # the emission, target 2026-11-30), fetch first, fetch last
 
     assert "POST /telemetry/send" in caplog.text
     caplog.clear()
@@ -1672,7 +1672,10 @@ async def test_disable_telemetry(conn_cnx, caplog):
     # test disable telemetry in the client
     with caplog.at_level(logging.DEBUG):
         async with conn_cnx() as conn:
-            assert conn.telemetry_enabled and len(conn._telemetry._log_batch) == 1
+            # Bumped from 1 to 2 by SNOW-3351450 (one extra event:
+            # client_connection_identifier_shape). Revert to 1 with the
+            # emission removal (SNOW-3548350, target 2026-11-30).
+            assert conn.telemetry_enabled and len(conn._telemetry._log_batch) == 2
             conn.telemetry_enabled = False
             async with conn.cursor() as cur:
                 await (await cur.execute("select 1")).fetchall()

test/integ/test_connection.py

@@ -1869,8 +1869,10 @@ def test_disable_telemetry(conn_cnx, caplog):
             with conn.cursor() as cur:
                 cur.execute("select 1").fetchall()
             assert (
-                len(conn._telemetry._log_batch) == 5
-            )  # 4 events are import package, minicore import, fetch first, fetch last
+                len(conn._telemetry._log_batch) == 6
+            )  # 6 events: import package, nanoarrow import, minicore import,
+            # client_connection_identifier_shape (SNOW-3548350; remove with
+            # the emission, target 2026-11-30), fetch first, fetch last
     assert "POST /telemetry/send" in caplog.text
     caplog.clear()
 
@@ -1893,7 +1895,10 @@ def test_disable_telemetry(conn_cnx, caplog):
     # test disable telemetry in the client
     with caplog.at_level(logging.DEBUG):
         with conn_cnx() as conn:
-            assert conn.telemetry_enabled and len(conn._telemetry._log_batch) == 3
+            # Bumped from 3 to 4 by SNOW-3351450 (one extra event:
+            # client_connection_identifier_shape). Revert to 3 with the
+            # emission removal (SNOW-3548350, target 2026-11-30).
+            assert conn.telemetry_enabled and len(conn._telemetry._log_batch) == 4
             conn.telemetry_enabled = False
             with conn.cursor() as cur:
                 cur.execute("select 1").fetchall()