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

   1 # `self-profile-events`
   2
   3 ---------------------
   4
   5 The `-Zself-profile-events` compiler flag controls what events are recorded by the self-profiler when it is enabled via the `-Zself-profile` flag.
   6
   7 This flag takes a comma delimited list of event types to record.
   8
   9 For example:
  10
  11 ```console
  12 $ rustc -Zself-profile -Zself-profile-events=default,args
  13 ```
  14
  15 ## Event types
  16
  17 - `query-provider`
  18   - Traces each query used internally by the compiler.
  19
  20 - `generic-activity`
  21   - Traces other parts of the compiler not covered by the query system.
  22
  23 - `query-cache-hit`
  24   - 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.
  25   - Disabled by default because this significantly increases the trace file size.
  26
  27 - `query-blocked`
  28   - Tracks time that a query tries to run but is blocked waiting on another thread executing the same query to finish executing.
  29   - Query blocking only occurs when the compiler is built with parallel mode support.
  30
  31 - `incr-cache-load`
  32   - Tracks time that is spent loading and deserializing query results from the incremental compilation on-disk cache.
  33
  34 - `query-keys`
  35   - Adds a serialized representation of each query's query key to the tracing data.
  36   - Disabled by default because this significantly increases the trace file size.
  37
  38 - `function-args`
  39   - Adds additional tracing data to some `generic-activity` events.
  40   - Disabled by default for parity with `query-keys`.
  41
  42 - `llvm`
  43   - Adds tracing information about LLVM passes and codegeneration.
  44   - Disabled by default because this only works when `-Znew-llvm-pass-manager` is enabled.
  45
  46 ## Event synonyms
  47
  48 - `none`
  49   - Disables all events.
  50   Equivalent to the self-profiler being disabled.
  51
  52 - `default`
  53   - The default set of events which stikes a balance between providing detailed tracing data and adding additional overhead to the compilation.
  54
  55 - `args`
  56   - Equivalent to `query-keys` and `function-args`.
  57
  58 - `all`
  59   - Enables all events.
  60
  61 ## Examples
  62
  63 Enable the profiler and capture the default set of events (both invocations are equivalent):
  64
  65 ```console
  66 $ rustc -Zself-profile
  67 $ rustc -Zself-profile -Zself-profile-events=default
  68 ```
  69
  70 Enable the profiler and capture the default events and their arguments:
  71
  72 ```console
  73 $ rustc -Zself-profile -Zself-profile-events=default,args
  74 ```