cli: add --trace-uncaught flag

Add a flag that makes Node.js print the stack trace at the
time of *throwing* uncaught exceptions, rather than at the
creation of the `Error` object, if there is any.

This is disabled by default because it affects GC behavior.

PR-URL: #30025
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Richard Lau <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Gireesh Punathil <[email protected]>

Author: addaleax

doc/api/cli.md

@@ -785,6 +785,18 @@ added: v12.2.0
 Prints TLS packet trace information to `stderr`. This can be used to debug TLS
 connection problems.
 
+### `--trace-uncaught`
+<!-- YAML
+added: REPLACEME
+-->
+
+Print stack traces for uncaught exceptions; usually, the stack trace associated
+with the creation of an `Error` is printed, whereas this makes Node.js also
+print the stack trace associated with throwing the value (which does not need
+to be an `Error` instance).
+
+Enabling this option may affect garbage collection behavior negatively.
+
 ### `--trace-warnings`
 <!-- YAML
 added: v6.0.0
@@ -1100,6 +1112,7 @@ Node.js options that are allowed are:
 * `--trace-events-enabled`
 * `--trace-sync-io`
 * `--trace-tls`
+* `--trace-uncaught`
 * `--trace-warnings`
 * `--track-heap-objects`
 * `--unhandled-rejections`

doc/node.1

@@ -352,6 +352,18 @@ Print a stack trace whenever synchronous I/O is detected after the first turn of
 .It Fl -trace-tls
 Prints TLS packet trace information to stderr.
 .
+.It Fl -trace-uncaught
+Print stack traces for uncaught exceptions; usually, the stack trace associated
+with the creation of an
+.Sy Error
+is printed, whereas this makes Node.js also
+print the stack trace associated with throwing the value (which does not need
+to be an
+.Sy Error
+instance).
+.Pp
+Enabling this option may affect garbage collection behavior negatively.
+.
 .It Fl -trace-warnings
 Print stack traces for process warnings (including deprecations).
 .

src/node.cc

@@ -232,6 +232,8 @@ int Environment::InitializeInspector(
 void Environment::InitializeDiagnostics() {
   isolate_->GetHeapProfiler()->AddBuildEmbedderGraphCallback(
       Environment::BuildEmbedderGraph, this);
+  if (options_->trace_uncaught)
+    isolate_->SetCaptureStackTraceForUncaughtExceptions(true);
 
 #if defined HAVE_DTRACE || defined HAVE_ETW
   InitDTrace(this);

src/node_errors.cc

@@ -380,6 +380,19 @@ static void ReportFatalException(Environment* env,
             "%s\n%s: %s\n", *arrow_string, *name_string, *message_string);
       }
     }
+
+    if (!env->options()->trace_uncaught) {
+      PrintErrorString("(Use `node --trace-uncaught ...` to show "
+                       "where the exception was thrown)\n");
+    }
+  }
+
+  if (env->options()->trace_uncaught) {
+    Local<StackTrace> trace = message->GetStackTrace();
+    if (!trace.IsEmpty()) {
+      PrintErrorString("Thrown at:\n");
+      PrintStackTrace(env->isolate(), trace);
+    }
   }
 
   fflush(stderr);

src/node_options.cc

@@ -498,6 +498,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "prints TLS packet trace information to stderr",
             &EnvironmentOptions::trace_tls,
             kAllowedInEnvironment);
+  AddOption("--trace-uncaught",
+            "show stack traces for the `throw` behind uncaught exceptions",
+            &EnvironmentOptions::trace_uncaught,
+            kAllowedInEnvironment);
   AddOption("--trace-warnings",
             "show stack traces on process warnings",
             &EnvironmentOptions::trace_warnings,

src/node_options.h

@@ -142,6 +142,7 @@ class EnvironmentOptions : public Options {
   bool trace_deprecation = false;
   bool trace_sync_io = false;
   bool trace_tls = false;
+  bool trace_uncaught = false;
   bool trace_warnings = false;
   std::string unhandled_rejections;
   std::string userland_loader;

test/message/eval_messages.out

@@ -55,9 +55,11 @@ ReferenceError: y is not defined
 var ______________________________________________; throw 10
                                                     ^
 10
+(Use `node --trace-uncaught ...` to show where the exception was thrown)
 
 [eval]:1
 var ______________________________________________; throw 10
                                                     ^
 10
+(Use `node --trace-uncaught ...` to show where the exception was thrown)
 done

test/message/stdin_messages.out

@@ -67,9 +67,11 @@ ReferenceError: y is not defined
 let ______________________________________________; throw 10
                                                     ^
 10
+(Use `node --trace-uncaught ...` to show where the exception was thrown)
 
 [stdin]:1
 let ______________________________________________; throw 10
                                                     ^
 10
+(Use `node --trace-uncaught ...` to show where the exception was thrown)
 done

test/message/throw_error_with_getter_throw.out

@@ -3,3 +3,4 @@
 throw {  // eslint-disable-line no-throw-literal
 ^
 [object Object]
+(Use `node --trace-uncaught ...` to show where the exception was thrown)

test/message/throw_error_with_getter_throw_traced.js

@@ -0,0 +1,11 @@
+// Flags: --trace-uncaught
+'use strict';
+require('../common');
+throw {  // eslint-disable-line no-throw-literal
+  get stack() {
+    throw new Error('weird throw but ok');
+  },
+  get name() {
+    throw new Error('weird throw but ok');
+  },
+};

test/message/throw_error_with_getter_throw_traced.out

@@ -0,0 +1,12 @@
+
+*:4
+throw {  // eslint-disable-line no-throw-literal
+^
+[object Object]
+Thrown at:
+    at *throw_error_with_getter_throw_traced.js:*:*
+    at Module._compile (internal/modules/cjs/loader.js:*:*)
+    at Module._extensions..js (internal/modules/cjs/loader.js:*:*)
+    at Module.load (internal/modules/cjs/loader.js:*:*)
+    at Module._load (internal/modules/cjs/loader.js:*:*)
+    at Module.runMain (internal/modules/cjs/loader.js:*:*)

test/message/throw_null.out

@@ -3,3 +3,4 @@
 throw null;
 ^
 null
+(Use `node --trace-uncaught ...` to show where the exception was thrown)

test/message/throw_null_traced.js

@@ -0,0 +1,6 @@
+// Flags: --trace-uncaught
+'use strict';
+require('../common');
+
+// eslint-disable-next-line no-throw-literal
+throw null;

test/message/throw_null_traced.out

@@ -0,0 +1,12 @@
+
+*test*message*throw_null_traced.js:*
+throw null;
+^
+null
+Thrown at:
+    at *throw_null_traced.js:*:*
+    at Module._compile (internal/modules/cjs/loader.js:*:*)
+    at Module._extensions..js (internal/modules/cjs/loader.js:*:*)
+    at Module.load (internal/modules/cjs/loader.js:*:*)
+    at Module._load (internal/modules/cjs/loader.js:*:*)
+    at Module.runMain (internal/modules/cjs/loader.js:*:*)

test/message/throw_undefined.out

@@ -3,3 +3,4 @@
 throw undefined;
 ^
 undefined
+(Use `node --trace-uncaught ...` to show where the exception was thrown)

test/message/throw_undefined_traced.js

@@ -0,0 +1,6 @@
+// Flags: --trace-uncaught
+'use strict';
+require('../common');
+
+// eslint-disable-next-line no-throw-literal
+throw undefined;

test/message/throw_undefined_traced.out

@@ -0,0 +1,12 @@
+
+*test*message*throw_undefined_traced.js:*
+throw undefined;
+^
+undefined
+Thrown at:
+    at *throw_undefined_traced.js:*:*
+    at Module._compile (internal/modules/cjs/loader.js:*:*)
+    at Module._extensions..js (internal/modules/cjs/loader.js:*:*)
+    at Module.load (internal/modules/cjs/loader.js:*:*)
+    at Module._load (internal/modules/cjs/loader.js:*:*)
+    at Module.runMain (internal/modules/cjs/loader.js:*:*)