gh-138704: Add PermissionError messages to profiling.sampling

Author: pablogsal

Lib/profiling/sampling/sample.py

@@ -14,9 +14,44 @@
 from .pstats_collector import PstatsCollector
 from .stack_collector import CollapsedStackCollector
 
+
+MACOS_PERMISSION_ERROR = """\
+🔒 Tachyon was unable to access process memory due to insufficient permissions on Mac OS.
+To profile processes, you may need to run Tachyon with sudo. Note that System Integrity Protection (SIP) can block access to Python binaries in protected locations.
+Using a virtual environment or installing Python outside protected directories may help.
+"""
+
+LINUX_PERMISSION_ERROR = """
+🔒 Tachyon was unable to acess process memory. This could be because tachyon 
+has insufficient privileges (the required capability is CAP_SYS_PTRACE).
+Unprivileged processes cannot trace processes that they cannot send signals
+to or those running set-user-ID/set-group-ID programs, for security reasons.
+
+If your uid matches the uid of the target process you want to analyze, you
+can do one of the following to get 'ptrace' scope permissions:
+
+* If you are running inside a Docker container, you need to make sure you
+  start the container using the '--cap-add=SYS_PTRACE' or '--privileged'
+  command line arguments. Notice that this may not be enough if you are not
+  running as 'root' inside the Docker container as you may need to disable
+  hardening (see next points).
+
+* Try running again with elevated permissions by running 'sudo -E !!'.
+
+* You can disable kernel hardening for the current session temporarily (until
+  a reboot happens) by running 'echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope'.
+"""
+
+WINDOWS_PERMISSION_ERROR = """
+🔒 Tachyon requires administrator rights to access process memory on Windows.
+Please run your command prompt as Administrator and try again.
+"""
+
+GENERIC_PERMISSION_ERROR = """
+🔒 Tachyon was unable to access the target process due to operating system restrictions or missing privileges.
+"""
+
 _FREE_THREADED_BUILD = sysconfig.get_config_var("Py_GIL_DISABLED") is not None
-_MAX_STARTUP_ATTEMPTS = 5
-_STARTUP_RETRY_DELAY_SECONDS = 0.1
 _HELP_DESCRIPTION = """Sample a process's stack frames and generate profiling data.
 Supports the following target modes:
   - -p PID: Profile an existing process by PID
@@ -826,39 +861,47 @@ def main():
     elif target_count > 1:
         parser.error("only one target type can be specified: -p/--pid, -m/--module, or script")
 
-    if args.pid:
-        sample(
-            args.pid,
-            sample_interval_usec=args.interval,
-            duration_sec=args.duration,
-            filename=args.outfile,
-            all_threads=args.all_threads,
-            limit=args.limit,
-            sort=sort_value,
-            show_summary=not args.no_summary,
-            output_format=args.format,
-            realtime_stats=args.realtime_stats,
-        )
-    elif args.module or args.args:
-        if args.module:
-            cmd = (sys.executable, "-m", args.module, *args.args)
-        else:
-            cmd = (sys.executable, *args.args)
-
-        # Use synchronized process startup
-        process = _run_with_sync(cmd)
+    try:
+        if args.pid:
+            sample(
+                args.pid,
+                sample_interval_usec=args.interval,
+                duration_sec=args.duration,
+                filename=args.outfile,
+                all_threads=args.all_threads,
+                limit=args.limit,
+                sort=sort_value,
+                show_summary=not args.no_summary,
+                output_format=args.format,
+                realtime_stats=args.realtime_stats,
+            )
+        elif args.module or args.args:
+            if args.module:
+                cmd = (sys.executable, "-m", args.module, *args.args)
+            else:
+                cmd = (sys.executable, *args.args)
 
-        # Process has already signaled readiness, start sampling immediately
-        try:
-            wait_for_process_and_sample(process.pid, sort_value, args)
-        finally:
-            if process.poll() is None:
-                process.terminate()
-                try:
-                    process.wait(timeout=2)
-                except subprocess.TimeoutExpired:
-                    process.kill()
-                    process.wait()
+            # Use synchronized process startup
+            process = _run_with_sync(cmd)
 
-if __name__ == "__main__":
-    main()
+            # Process has already signaled readiness, start sampling immediately
+            try:
+                wait_for_process_and_sample(process.pid, sort_value, args)
+            finally:
+                if process.poll() is None:
+                    process.terminate()
+                    try:
+                        process.wait(timeout=2)
+                    except subprocess.TimeoutExpired:
+                        process.kill()
+                        process.wait()
+    except PermissionError:
+        if sys.platform == "darwin":
+            print(MACOS_PERMISSION_ERROR, file=sys.stderr)
+        elif sys.platform.startswith("linux"):
+            print(LINUX_PERMISSION_ERROR, file=sys.stderr)
+        elif sys.platform.startswith("win"):
+            print(WINDOWS_PERMISSION_ERROR, file=sys.stderr)
+        else:
+            print(GENERIC_PERMISSION_ERROR, file=sys.stderr)
+        sys.exit(1)