feat: [SNOW-2330065] collect telemetry about flags from parent contexts (#2651)

* feat: [SNOW-2330065] collect telemetry about flags from parent contexts

* feat: [SNOW-2330065] review fixes

Author: sfc-gh-jwilkowski

src/snowflake/cli/_app/cli_app.py

@@ -14,6 +14,7 @@
 
 from __future__ import annotations
 
+import inspect
 import logging
 import os
 import platform
@@ -47,6 +48,20 @@
 
 log = logging.getLogger(__name__)
 
+INTERNAL_CLI_FLAGS = {
+    "custom_help",
+    "version",
+    "docs",
+    "structure",
+    "info",
+    "configuration_file",
+    "pycharm_debug_library_path",
+    "pycharm_debug_server_host",
+    "pycharm_debug_server_port",
+    "disable_external_command_plugins",
+    "commands_registration",
+}
+
 
 def _do_not_execute_on_completion(callback):
     def enriched_callback(value):
@@ -270,8 +285,36 @@ def default(
                 pycharm_debug_server_port=pycharm_debug_server_port,
             )
 
+        self._validate_internal_flags_excluded_from_telemetry(default)
+
         self._app = app
         return app
 
+    @staticmethod
+    def _validate_internal_flags_excluded_from_telemetry(callback_function):
+        """
+        We have not been interested in collecting telemetry data about root
+        command flags (most of which are internal flags). This method validates
+        that all new flags should be added to INTERNAL_CLI_FLAGS and thus
+        excluded from telemetry as well.
+        """
+        sig = inspect.signature(callback_function)
+        actual_params = {name for name in sig.parameters.keys() if name != "ctx"}
+        if actual_params != INTERNAL_CLI_FLAGS:
+            missing = actual_params - INTERNAL_CLI_FLAGS
+            extra = INTERNAL_CLI_FLAGS - actual_params
+            error_parts = []
+            if missing:
+                error_parts.append(
+                    f"Parameters in default() but not in INTERNAL_CLI_FLAGS: {missing}"
+                )
+            if extra:
+                error_parts.append(
+                    f"Flags in INTERNAL_CLI_FLAGS but not in default(): {extra}"
+                )
+            raise AssertionError(
+                "INTERNAL_CLI_FLAGS mismatch! " + ". ".join(error_parts)
+            )
+
     def get_click_context(self):
         return self._click_context

src/snowflake/cli/_app/telemetry.py

@@ -18,11 +18,12 @@
 import platform
 import sys
 from enum import Enum, unique
-from typing import Any, Dict, Union
+from typing import Any, Dict, Optional, Union
 
 import click
 import typer
 from snowflake.cli import __about__
+from snowflake.cli._app.cli_app import INTERNAL_CLI_FLAGS
 from snowflake.cli._app.constants import PARAM_APPLICATION_NAME
 from snowflake.cli.api.cli_global_context import (
     _CliGlobalContextAccess,
@@ -38,6 +39,7 @@
     TelemetryField,
 )
 from snowflake.connector.time_util import get_time_millis
+from typer import Context
 
 
 @unique
@@ -140,17 +142,30 @@ def _get_command_metrics() -> TelemetryDict:
 def _find_command_info() -> TelemetryDict:
     ctx = click.get_current_context()
     command_path = ctx.command_path.split(" ")[1:]
+
+    command_flags = {}
+    format_value = None
+    current_ctx: Optional[Context] = ctx
+    while current_ctx:
+        for flag, flag_value in current_ctx.params.items():
+            if (
+                flag_value
+                and flag not in command_flags
+                and flag not in INTERNAL_CLI_FLAGS
+            ):
+                command_flags[flag] = current_ctx.get_parameter_source(flag).name  # type: ignore[attr-defined]
+        if format_value is None and "format" in current_ctx.params:
+            format_value = current_ctx.params["format"]
+        current_ctx = current_ctx.parent
+
+    if format_value is None:
+        format_value = OutputFormat.TABLE
+
     return {
         CLITelemetryField.COMMAND: command_path,
         CLITelemetryField.COMMAND_GROUP: command_path[0],
-        CLITelemetryField.COMMAND_FLAGS: {
-            k: ctx.get_parameter_source(k).name  # type: ignore[attr-defined]
-            for k, v in ctx.params.items()
-            if v  # noqa
-        },
-        CLITelemetryField.COMMAND_OUTPUT_TYPE: ctx.params.get(
-            "format", OutputFormat.TABLE
-        ).value,
+        CLITelemetryField.COMMAND_FLAGS: command_flags,
+        CLITelemetryField.COMMAND_OUTPUT_TYPE: format_value.value,
         CLITelemetryField.PROJECT_DEFINITION_VERSION: str(_get_definition_version()),
         CLITelemetryField.MODE: _get_cli_running_mode(),
     }

tests/app/test_telemetry.py

@@ -215,3 +215,28 @@ def test_cli_exception_classification(error: Exception, is_cli: bool):
     from snowflake.cli._app.telemetry import _is_cli_exception
 
     assert _is_cli_exception(error) == is_cli
+
+
+@mock.patch("uuid.uuid4")
+def test_flags_from_parent_contexts_are_captured(mock_uuid4, mock_connect, runner):
+    mock_uuid4.return_value = uuid.UUID("8a2225b3800c4017a4a9eab941db58fa")
+
+    result = runner.invoke(
+        ["dbt", "execute", "--run-async", "pipeline_name", "run", "--debug"]
+    )
+
+    assert result.exit_code == 0, result.output
+
+    usage_command_event = (
+        mock_connect.return_value._telemetry.try_add_log_to_batch.call_args_list[  # noqa: SLF001
+            0
+        ]
+        .args[0]
+        .to_dict()
+    )
+
+    command_flags = usage_command_event["message"]["command_flags"]
+    assert "run_async" in command_flags, (
+        f"run_async flag should be captured in telemetry. "
+        f"Found flags: {command_flags}"
+    )