Add infrastructure for emitting timing sections

2 files changed, 28 insertions, 0 deletions

diff --git a/src/doc/rustc/src/command-line-arguments.md b/src/doc/rustc/src/command-line-arguments.md
index b704cee705b..d45ad1be27b 100644
--- a/src/doc/rustc/src/command-line-arguments.md
+++ b/src/doc/rustc/src/command-line-arguments.md
@@ -471,6 +471,9 @@ to customize the output:
 - `future-incompat` - includes a JSON message that contains a report if the
   crate contains any code that may fail to compile in the future.
 
+- `timings` - output a JSON message when a certain compilation "section"
+  (such as frontend analysis, code generation, linking) begins or ends.
+
 Note that it is invalid to combine the `--json` argument with the
 [`--color`](#option-color) argument, and it is required to combine `--json`
 with `--error-format=json`.
diff --git a/src/doc/rustc/src/json.md b/src/doc/rustc/src/json.md
index c853f34ee03..8839a1a78c3 100644
--- a/src/doc/rustc/src/json.md
+++ b/src/doc/rustc/src/json.md
@@ -298,6 +298,31 @@ appropriately. (This is needed by Cargo which shares the same dependencies
 across multiple build targets, so it should only report an unused dependency if
 its not used by any of the targets.)
 
+## Timings
+
+**This setting is currently unstable and requires usage of `-Zunstable-options`.**
+
+The `--timings` option will tell `rustc` to emit messages when a certain compilation
+section (such as code generation or linking) begins or ends. The messages will have
+the following format:
+
+```json
+{
+    "$message_type": "section_timing", /* Type of this message */
+    "event": "start", /* Marks the "start" or "end" of the compilation section */
+    "name": "link",  /* The name of the compilation section */
+    "time": 12345    /* Opaque timestamp when the message was emitted, in microseconds */
+}
+```
+
+Compilation sections can be nested; for example, if you encounter the start of "foo",
+then the start of "bar", then the end of "bar" and then the end of "bar", it means that the
+"bar" section happened as a part of the "foo" section.
+
+The timestamp should only be used for computing the duration of each section.
+
+We currently do not guarantee any specific section names to be emitted.
+
 [option-emit]: command-line-arguments.md#option-emit
 [option-error-format]: command-line-arguments.md#option-error-format
 [option-json]: command-line-arguments.md#option-json