Automatically send telemetry for failed subprocesses

Author: ofek

CHANGELOG.md

@@ -8,6 +8,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## Unreleased
 
+***Changed:***
+
+- The `app.subprocess.run` method now uses a pseudo-terminal in order to capture output from subprocesses while displaying it. A new `app.subprocess.attach` method is available which retains the original behavior and should be preferred when subprocesses require user interaction.
+- The `app.subprocess.run` method now returns an integer representing the exit code of the completed subprocess call
+
+***Added:***
+
+- Automatically send telemetry for failed subprocesses
+
 ***Fixed:***
 
 - Properly apply Python path modifications when loading dynamic commands

docs/reference/api/app.md

@@ -12,6 +12,7 @@
       - http
       - tools
       - telemetry
+      - last_error
       - display
       - display_critical
       - display_error

docs/reference/api/process.md

@@ -9,6 +9,7 @@
       - capture
       - wait
       - exit_with
+      - attach
       - spawn_daemon
 
 ::: dda.utils.process.EnvVars

docs/reference/api/telemetry.md

@@ -5,6 +5,7 @@
 ::: dda.telemetry.manager.TelemetryManager
     options:
       members:
+      - enabled
       - log
       - trace
 

pyproject.toml

@@ -37,6 +37,7 @@ dependencies = [
   "packaging",
   "platformdirs~=4.2",
   "psutil~=7.0",
+  "pywinpty~=2.0.15; sys_platform == 'win32'",
   "rich~=14.0",
   "rich-click~=1.8",
   "tomlkit~=0.13",

src/dda/cli/application.py

@@ -56,17 +56,36 @@ def __init__(self, *, terminator: Callable[[int], NoReturn], config_file: Config
     def abort(self, text: str = "", code: int = 1) -> NoReturn:
         """
         Gracefully terminate the application with an optional
-        [error message][dda.cli.application.Application.display_critical].
+        [error message][dda.cli.application.Application.display_critical]. The message is
+        appended to the [last error message][dda.cli.application.Application.last_error].
 
         Parameters:
             text: The error message to display.
             code: The exit code to use.
         """
         if text:
+            self.last_error += text
             self.display_critical(text)
 
         self.__terminator(code)
 
+    @cached_property
+    def last_error(self) -> str:
+        """
+        The last recorded error message which will be collected as telemetry. This can be overwritten like so:
+
+        ```python
+        app.last_error = "An error occurred"
+        ```
+
+        Alternatively, you can append to it:
+
+        ```python
+        app.last_error += "\\nExtra information or context"
+        ```
+        """
+        return ""
+
     @cached_property
     def config_file(self) -> ConfigFile:
         return self.__config_file

src/dda/cli/base.py

@@ -111,32 +111,47 @@ def __exit__(
         if (
             # The application may not be set if an error occurred very early
             app is not None
+            and app.telemetry.enabled
             # The proper exit code only manifests when the top level context exits
             and command_depth == 1
             and self._depth == 1
         ):
-            # https://github.com/pallets/click/blob/8.1.8/src/click/exceptions.py#L296
             if isinstance(exc_value, Exit):
+                # https://github.com/pallets/click/blob/8.1.8/src/click/exceptions.py#L296
                 exit_code = exc_value.exit_code
-            # https://github.com/pallets/click/blob/8.1.8/src/click/exceptions.py#L64
             elif isinstance(exc_value, UsageError):
+                # https://github.com/pallets/click/blob/8.1.8/src/click/exceptions.py#L64
                 exit_code = 2
-            # https://github.com/pallets/click/blob/8.1.8/src/click/exceptions.py#L29
+            elif isinstance(exc_value, KeyboardInterrupt):
+                # Use the non-Windows default value for consistency
+                # https://www.redhat.com/en/blog/exit-codes-demystified
+                # https://github.com/python/cpython/blob/3.13/Modules/main.c#L731-L754
+                exit_code = 130
             else:
+                import traceback
+
+                # https://github.com/pallets/click/blob/8.1.8/src/click/exceptions.py#L29
                 exit_code = 1
+                app.last_error = traceback.format_exc()
 
             from dda.cli import START_TIME, START_TIMESTAMP
             from dda.utils.platform import join_command_args
 
+            metadata = {
+                "cli.command": join_command_args(sys.argv[1:]),
+                "cli.exit_code": str(exit_code),
+            }
+            if last_error := app.last_error.strip():
+                # Payload limit is 5MB so we truncate the error message to a little bit less than that
+                message_max_length = int(1024 * 1024 * 4.5)
+                metadata["error.message"] = last_error[-message_max_length:]
+
             app.telemetry.trace.span({
                 "resource": " ".join(root_ctx.deepest_command_path.split()[1:]) or " ",
                 "start": START_TIMESTAMP,
                 "duration": perf_counter_ns() - START_TIME,
                 "error": 0 if exit_code == 0 else 1,
-                "meta": {
-                    "cli.command": join_command_args(sys.argv[1:]),
-                    "cli.exit_code": str(exit_code),
-                },
+                "meta": metadata,
             })
 
         super().__exit__(exc_type, exc_value, tb)

src/dda/telemetry/manager.py

@@ -24,6 +24,13 @@ def __init__(self, app: Application) -> None:
 
         self.__started = False
 
+    @property
+    def enabled(self) -> bool:
+        """
+        Whether the user has consented to telemetry.
+        """
+        return self.__enabled
+
     @cached_property
     def log(self) -> LogTelemetryWriter:
         from dda.telemetry.writers.log import LogTelemetryWriter

src/dda/tools/base.py

@@ -49,7 +49,7 @@ def env_vars(self) -> dict[str, str]:  # noqa: PLR6301
         """
         return {}
 
-    def run(self, command: list[str], *args: Any, **kwargs: Any) -> CompletedProcess:
+    def run(self, command: list[str], **kwargs: Any) -> int:
         """
         Equivalent to [`SubprocessRunner.run`][dda.utils.process.SubprocessRunner.run] with the `command` formatted
         by the tool's [`format_command`][dda.tools.base.Tool.format_command] method and the environment variables set
@@ -59,14 +59,13 @@ def run(self, command: list[str], *args: Any, **kwargs: Any) -> CompletedProcess
             command: The command to execute.
 
         Other parameters:
-            *args: Additional arguments to pass to [`SubprocessRunner.run`][dda.utils.process.SubprocessRunner.run].
             **kwargs: Additional keyword arguments to pass to
                 [`SubprocessRunner.run`][dda.utils.process.SubprocessRunner.run].
         """
         self.__populate_env_vars(kwargs)
-        return self.app.subprocess.run(self.format_command(command), *args, **kwargs)
+        return self.app.subprocess.run(self.format_command(command), **kwargs)
 
-    def capture(self, command: list[str], *args: Any, **kwargs: Any) -> str:
+    def capture(self, command: list[str], **kwargs: Any) -> str:
         """
         Equivalent to [`SubprocessRunner.capture`][dda.utils.process.SubprocessRunner.capture] with the `command`
         formatted by the tool's [`format_command`][dda.tools.base.Tool.format_command] method and the environment
@@ -76,15 +75,13 @@ def capture(self, command: list[str], *args: Any, **kwargs: Any) -> str:
             command: The command to execute.
 
         Other parameters:
-            *args: Additional arguments to pass to
-                [`SubprocessRunner.capture`][dda.utils.process.SubprocessRunner.capture].
             **kwargs: Additional keyword arguments to pass to
                 [`SubprocessRunner.capture`][dda.utils.process.SubprocessRunner.capture].
         """
         self.__populate_env_vars(kwargs)
-        return self.app.subprocess.capture(self.format_command(command), *args, **kwargs)
+        return self.app.subprocess.capture(self.format_command(command), **kwargs)
 
-    def wait(self, command: list[str], *args: Any, **kwargs: Any) -> None:
+    def wait(self, command: list[str], **kwargs: Any) -> None:
         """
         Equivalent to [`SubprocessRunner.wait`][dda.utils.process.SubprocessRunner.wait] with the `command` formatted
         by the tool's [`format_command`][dda.tools.base.Tool.format_command] method and the environment variables set
@@ -94,14 +91,13 @@ def wait(self, command: list[str], *args: Any, **kwargs: Any) -> None:
             command: The command to execute.
 
         Other parameters:
-            *args: Additional arguments to pass to [`SubprocessRunner.wait`][dda.utils.process.SubprocessRunner.wait].
             **kwargs: Additional keyword arguments to pass to
                 [`SubprocessRunner.wait`][dda.utils.process.SubprocessRunner.wait].
         """
         self.__populate_env_vars(kwargs)
-        self.app.subprocess.wait(self.format_command(command), *args, **kwargs)
+        self.app.subprocess.wait(self.format_command(command), **kwargs)
 
-    def exit_with(self, command: list[str], *args: Any, **kwargs: Any) -> NoReturn:
+    def exit_with(self, command: list[str], **kwargs: Any) -> NoReturn:
         """
         Equivalent to [`SubprocessRunner.exit_with`][dda.utils.process.SubprocessRunner.exit_with]
         with the `command` formatted by the tool's [`format_command`][dda.tools.base.Tool.format_command] method and
@@ -111,13 +107,27 @@ def exit_with(self, command: list[str], *args: Any, **kwargs: Any) -> NoReturn:
             command: The command to execute.
 
         Other parameters:
-            *args: Additional arguments to pass to
-                [`SubprocessRunner.exit_with`][dda.utils.process.SubprocessRunner.exit_with].
             **kwargs: Additional keyword arguments to pass to
                 [`SubprocessRunner.exit_with`][dda.utils.process.SubprocessRunner.exit_with].
         """
         self.__populate_env_vars(kwargs)
-        self.app.subprocess.exit_with(self.format_command(command), *args, **kwargs)
+        self.app.subprocess.exit_with(self.format_command(command), **kwargs)
+
+    def attach(self, command: list[str], **kwargs: Any) -> CompletedProcess:
+        """
+        Equivalent to [`SubprocessRunner.attach`][dda.utils.process.SubprocessRunner.attach] with the `command` formatted
+        by the tool's [`format_command`][dda.tools.base.Tool.format_command] method and the environment variables set
+        by the tool's [`env_vars`][dda.tools.base.Tool.env_vars] method (if any).
+
+        Parameters:
+            command: The command to execute.
+
+        Other parameters:
+            **kwargs: Additional keyword arguments to pass to
+                [`SubprocessRunner.attach`][dda.utils.process.SubprocessRunner.attach].
+        """
+        self.__populate_env_vars(kwargs)
+        return self.app.subprocess.attach(self.format_command(command), **kwargs)
 
     def __populate_env_vars(self, kwargs: dict[str, Any]) -> None:
         env_vars = self.env_vars()

src/dda/utils/platform/_pty/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025-present Datadog, Inc. <[email protected]>
+#
+# SPDX-License-Identifier: MIT