Add documentation to logging

Krovatkin · facebook-github-bot · commit 27b5a6c577d9 · 2019-09-13T12:13:16.000-07:00
Summary: Pull Request resolved: #26175 Differential Revision: D17371085 Pulled By: Krovatkin fbshipit-source-id: ea06f4e16fc320940a299e8e1d4f4d7c76f5950a
diff --git a/torch/csrc/jit/docs/OVERVIEW.md b/torch/csrc/jit/docs/OVERVIEW.md
@@ -1026,6 +1026,32 @@ with prim::DifferentiableGraph_0 = graph(%13 : Float(*, *),
   return (%hy, %cy)
 ```
 
+## JIT Logging ##
+
+Logging is a very useful debugging technique, especially in the context of compilers. Compilers perform a series of passes and analyses and logging can help to trace issues such as wrong results or segmentation faults
+all the way back to the original erroneous transformation.
+
+`TorchScript` offers a simple logging facility that can enabled by setting an environment variable `PYTORCH_JIT_LOG_LEVEL`.
+
+Logging is enabled on a per file basis. To enable logging in `dead_code_elimination.cpp`, `PYTORCH_JIT_LOG_LEVEL` should be
+set to `dead_code_elimination.cpp` or, simply, to `dead_code_elimination` (i.e. `PYTORCH_JIT_LOG_LEVEL=dead_code_elimination`).
+
+Multiple files can be logged by separating each file name with a colon `:` as in the following example, `PYTORCH_JIT_LOG_LEVEL=dead_code_elimination:guard_elimination`
+
+There are 3 logging levels available for your use ordered by the detail level from lowest to highest.
+
+* `GRAPH_DUMP` should be used for printing entire graphs after optimization passes
+* `GRAPH_UPDATE` should be used for reporting graph transformations (i.e. node deletion, constant folding, etc)
+* `GRAPH_DEBUG` should be used for providing information useful for debugging
+  the internals of a particular optimization pass or analysis
+
+The current logging level is `GRAPH_UPDATE` meaning that both `GRAPH_DUMP` and `GRAPH_UPDATE` will be enabled when
+one specifies a file(s) in `PYTORCH_JIT_LOG_LEVEL`.
+
+`GRAPH_DEBUG` can be enabled by prefixing a file name with an `>` as in `>alias_analysis`.
+`>>` and `>>>` are also valid and **currently** are equivalent to `GRAPH_DEBUG` as there is no logging level that is
+higher than `GRAPH_DEBUG`. 
+
 ## DifferentiableGraphOp ##
 
 [graph_executor.cpp](../graph_executor.cpp)
diff --git a/torch/csrc/jit/jit_log.h b/torch/csrc/jit/jit_log.h
@@ -3,15 +3,38 @@
 #include <string>
 #include <torch/csrc/WindowsTorchApiMacro.h>
 
-// To enable logging please set(export) PYTORCH_JIT_LOG_LEVEL to
-// the ordinal value of one of the following logging levels: 1 for GRAPH_DUMP,
-// 2 for GRAPH_UPDATE, 3 for GRAPH_DEBUG.
-// * Use GRAPH_DUMP for dumping graphs after optimization passes
-// * Use GRAPH_UPDATE for reporting graph transformations (i.e. node deletion,
-//   constant folding, CSE)
-// * Use GRAPH_DEBUG to provide information useful for debugging
+// `TorchScript` offers a simple logging facility that can enabled by setting an
+// environment variable `PYTORCH_JIT_LOG_LEVEL`.
+
+// Logging is enabled on a per file basis. To enable logging in
+// `dead_code_elimination.cpp`, `PYTORCH_JIT_LOG_LEVEL` should be
+// set to `dead_code_elimination.cpp` or, simply, to `dead_code_elimination`
+// (i.e. `PYTORCH_JIT_LOG_LEVEL=dead_code_elimination`).
+
+// Multiple files can be logged by separating each file name with a colon `:` as
+// in the following example,
+// `PYTORCH_JIT_LOG_LEVEL=dead_code_elimination:guard_elimination`
+
+// There are 3 logging levels available for your use ordered by the detail level
+// from lowest to highest.
+
+// * `GRAPH_DUMP` should be used for printing entire graphs after optimization
+// passes
+// * `GRAPH_UPDATE` should be used for reporting graph transformations (i.e.
+// node deletion, constant folding, etc)
+// * `GRAPH_DEBUG` should be used for providing information useful for debugging
 //   the internals of a particular optimization pass or analysis
 
+// The current logging level is `GRAPH_UPDATE` meaning that both `GRAPH_DUMP`
+// and `GRAPH_UPDATE` will be enabled when
+// one specifies a file(s) in `PYTORCH_JIT_LOG_LEVEL`.
+
+// `GRAPH_DEBUG` can be enabled by prefixing a file name with an `>` as in
+// `>alias_analysis`.
+// `>>` and `>>>` are also valid and **currently** are equivalent to
+// `GRAPH_DEBUG` as there is no logging level that is
+// higher than `GRAPH_DEBUG`.
+
 namespace torch {
 namespace jit {
 
