Add documentation for the -Zself-profile flag

src/doc/unstable-book/src/compiler-flags/self-profile-events.md

@@ -0,0 +1,74 @@
+# `self-profile-events`
+
+---------------------
+
+The `-Zself-profile-events` compiler flag controls what events are recorded by the self-profiler when it is enabled via the `-Zself-profile` flag.
+
+This flag takes a comma delimited list of event types to record.
+
+For example:
+
+```console
+$ rustc -Zself-profile -Zself-profile-events=default,args
+```
+
+## Event types
+
+- `query-provider`
+  - Traces each query used internally by the compiler.
+
+- `generic-activity`
+  - Traces other parts of the compiler not covered by the query system.
+
+- `query-cache-hit`
+  - Adds tracing information that records when the in-memory query cache is "hit" and does not need to re-execute a query which has been cached.
+  - Disabled by default because this significantly increases the trace file size.
+
+- `query-blocked`
+  - Tracks time that a query tries to run but is blocked waiting on another thread executing the same query to finish executing.
+  - Query blocking only occurs when the compiler is built with parallel mode support.
+
+- `incr-cache-load`
+  - Tracks time that is spent loading and deserializing query results from the incremental compilation on-disk cache.
+
+- `query-keys`
+  - Adds a serialized representation of each query's query key to the tracing data.
+  - Disabled by default because this significantly increases the trace file size.
+
+- `function-args`
+  - Adds additional tracing data to some `generic-activity` events.
+  - Disabled by default for parity with `query-keys`.
+
+- `llvm`
+  - Adds tracing information about LLVM passes and codegeneration.
+  - Disabled by default because this only works when `-Znew-llvm-pass-manager` is enabled.
+
+## Event synonyms
+
+- `none`
+  - Disables all events.
+  Equivalent to the self-profiler being disabled.
+
+- `default`
+  - The default set of events which stikes a balance between providing detailed tracing data and adding additional overhead to the compilation.
+
+- `args`
+  - Equivalent to `query-keys` and `function-args`.
+
+- `all`
+  - Enables all events.
+
+## Examples
+
+Enable the profiler and capture the default set of events (both invocations are equivalent):
+
+```console
+$ rustc -Zself-profile
+$ rustc -Zself-profile -Zself-profile-events=default
+```
+
+Enable the profiler and capture the default events and their arguments:
+
+```console
+$ rustc -Zself-profile -Zself-profile-events=default,args
+```

src/doc/unstable-book/src/compiler-flags/self-profile.md

@@ -0,0 +1,47 @@
+# `self-profile`
+
+--------------------
+
+The `-Zself-profile` compiler flag enables rustc's internal profiler.
+When enabled, the compiler will output three binary files in the specified directory (or the current working directory if no directory is specified).
+These files can be analyzed by using the tools in the [`measureme`] repository.
+
+To control the data recorded in the trace files, use the `-Zself-profile-events` flag.
+
+For example:
+
+First, run a compilation session and provide the `-Zself-profile` flag:
+
+```console
+$ rustc --crate-name foo -Zself-profile`
+```
+
+This will generate three files in the working directory such as:
+
+- `foo-1234.events`
+- `foo-1234.string_data`
+- `foo-1234.string_index`
+
+Where `foo` is the name of the crate and `1234` is the process id of the rustc process.
+
+To get a summary of where the compiler is spending its time:
+
+```console
+$ ../measureme/target/release/summarize summarize foo-1234
+```
+
+To generate a flamegraph of the same data:
+
+```console
+$ ../measureme/target/release/inferno foo-1234
+```
+
+To dump the event data in a Chromium-profiler compatible format:
+
+```console
+$ ../measureme/target/release/crox foo-1234
+```
+
+For more information, consult the [`measureme`] documentation.
+
+[`measureme`]: https://github.com/rust-lang/measureme.git