doc: warn about using util.inspect/util.format

Because of the potential performance bottlenecks that may be introduced by `util.inspect()` and `util.format()` in production hot path code. Based on real user feedback, it is not obvious that these are intended to be debugging tools. PR-URL: #17791 Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Matteo Collina <[email protected]>
nodejs · Mar 24, 2018 · 742b304 · 742b304
1 parent 5f1a01d
commit 742b304
Showing 1 changed file with 10 additions and 0 deletions.
diff --git a/doc/api/util.md b/doc/api/util.md
@@ -225,6 +225,11 @@ without any formatting.
 util.format('%% %s'); // '%% %s'
 ```
 
+Please note that `util.format()` is a synchronous method that is mainly
+intended as a debugging tool. Some input values can have a significant
+performance overhead that can block the event loop. Use this function
+with care and never in a hot code path.
+
 ## util.getSystemErrorName(err)
 <!-- YAML
 added: v9.7.0
@@ -437,6 +442,11 @@ console.log(util.inspect(o, { compact: false, depth: 5, breakLength: 80 }));
 // chunks.
 ```
 
+Please note that `util.inspect()` is a synchronous method that is mainly
+intended as a debugging tool. Some input values can have a significant
+performance overhead that can block the event loop. Use this function
+with care and never in a hot code path.
+
 ### Customizing `util.inspect` colors
 
 <!-- type=misc -->