From 680b659729fa21c91fc8fabffb1296076209f447 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Wed, 20 Dec 2017 07:50:47 -0800
Subject: [PATCH] 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.
---
 doc/api/util.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/api/util.md b/doc/api/util.md
index 8f9e6ef020a07d..a2d3c71bb633a8 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -250,6 +250,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.inherits(constructor, superConstructor)
 <!-- YAML
 added: v0.3.0
@@ -462,6 +467,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 -->