Add documentation for NIECZA_* knobs

docs/tracing.pod

@@ -0,0 +1,66 @@
+=head1 Synopsis
+
+Tracing options available in the Niecza (.NET) runtime
+
+=head1 General
+
+Boolean options only care about the presence or absence of the
+named environment variable.
+
+=head1 Kernel.cs
+
+=head2 C<NIECZA_TRACE>
+
+This enables per-operation tracing by instrumenting the trampoline.
+It may be set to C<all> or C<stat>.  If it is set to C<all>, then the
+call tree will be printed in real time; each trampoline bounce displays
+a node and the current call depth.  If it is set to C<stat>, then the
+call stack will be printed every 1 million bounces (by default).
+
+The C<all> mode is useful for debugging the context of crashes,
+especially infinite loops in a single operation.  For Perl 6-level
+infinite loops, C<stat> is more useful; C<stat> can also be used as a
+primitive profiler, though its utility is limited by the fact that it
+does not count real time.
+
+=head2 C<NIECZA_TRACE_PERIOD>
+
+This sets the display interval for C<NIECZA_TRACE=stat>.  Defaults to
+C<1000000>.  Setting it lower is potentially useful in a profiling
+context.
+
+=head1 Cursor.cs
+
+=head2 C<NIECZA_DIE_AT_PCT>
+
+Throw an exception and generate a stack dump at a specific point in the
+parsing process.  Only meaningful in conjunction with
+C<NIECZA_HIGHWATER_TRACE>; for instance, setting this to C<53> will die
+immediately after the generation of the "53%" status report.
+
+=head2 C<NIECZA_HIGHWATER_TRACE>
+
+Generates running status reports for all regex matches against long
+strings (greater than 100 characters).  The status measured is the
+high-water mark, the highest character position yet seen (for speed
+reasons, this is only sampled when backtracking, at the end of rules,
+and on entry to longest-term matching).
+
+=head2 C<NIECZA_LTM_TRACE>
+
+Generates extensive reports on the construction and use of longest-term
+automata.
+
+=head2 C<NIECZA_RX_TRACE>
+
+Traces some regex primitives (currently only C<< <ws> >>, was more
+before newrx was merged).  Each time ws is called, this will be
+reported, along with the position of the attempt and whether it
+succeeded.
+
+=head1 JSYNC.cs
+
+=head2 C<NIECZA_JSYNC_WRITER_FAILSOFT>
+
+Encode unencodable objects as the string C<"UNSERIALIZABLE Type">, to
+make it easier to find them in the data structure.