Optimizer Trace for Developers
This article describes guidelines for what/how to write to Optimizer Trace when doing server development.
Basic considerations
The trace is a "structured log" of what was done by the optimizer. Prefer to do tracing as soon as a rewrite/decision is made (instead of having a separate trace_something() function).
Generally, a function should expect to find the trace in a state where we're writing an array. The rationale is that array elements are ordered, (while object members are not). We're writing a log, so in order for stuff written so far to be viewed as before what you're about to write, we need to write an array.
(TODO other considerations)
Making sure the trace is valid
Json_writer_object
and Json_writer_array
classes use RAII idiom and ensure that JSON objects and arrays are "closed" in the reverse order they were started.
However, they do not ensure these constraints:
- JSON objects must have named members.
- JSON arrays must have unnamed members.
Tracing code has runtime checks for these. Attempt to write invalid JSON will cause assertion failure.
Test coverage
It is possible to run mysql-test-run
with this argument
--mysqld=--optimizer_trace=enabled=on
This will run all tests with tracing on. As mentioned earlier, debug build will perform checks that we are not producing invalid trace.
The BuildBot instance at http://buildbot.askmonty.org/ also runs tests with this argument, see mtr_opttrace
pass in kvm-fulltest and kvm-fulltest2.
Debugging
See optimizer-debugging-with-gdb/#printing-the-optimizer-trace for commands to print the trace for the current statement.