Web Polygraph includes a set of tools for automated report generation. These tools, collectively called Report Generator, use binary logs and other sources of information to generate reports that can be viewed with your favorite browser. The reports include ``executive summary'' section for the boss, and more detailed analysis for the rest of us. Some common performance and configuration problems can also be automatically detected.

Automated report generation was introduced in Poly 2.2.8. This page has been synchronized with Poly 2.2.8.

Report generation takes at least two simple steps listed below.

1. Label your results using the label_results tool.
2. Make a report using the make_report tool.
3. Optionally, you can plot custom traces using plot_traces.

Important configuration caveats and real life examples can be found in the corresponding section of the User Manual. Please browse the manual before you start using the Generator. The rest of this document describes individual Report Generator tools.

usage: ./label_results [options] <label> <log> ...
options and their defaults:
    --log_extractor                  lx
    --log_extractor_opts             [no default]
    --log_trace_extractor            ltrace
    --log_trace_extractor_opts       --time_unit 1sec --win_len 1min
    --use_cache                      no
note: defaults are overwritten by configuration file

Label_results ``names'' a group of logs. Or, to be precise, the script assigns a label to information extracted from one or more log files. That label can be then used to generate reports and plot graphs.

By default, label_results extracts

• aggregate statistics using lx with no options and
• traces using ltrace with one minute averaging

Note that command line options are useful to extract aggregate statistics based on only one phase of the experiment. For example,

	example> ./label_results --log_extractor_opts "--phases top2" \
		last_minute_optimization \
		/tmp/logs/lmo-19991131*log

By default, label_results places extracted information into /tmp/polyrep/label/ directory, where label is the actual label you specified as a command line parameter.

If you want label_results not to update information that was extracted after the log files were modified, then you can enable the --use_cache option. Using cache can be handy if you call label_results from some other scripts and do not want to extract the same information over and over again. As with any cache, be careful not to use stale data; label_results only compares file timestamps (and timestamps could lie too!) and does not know of any other external changes that may have affected the results.

usage: ./make_report [options] <label> ...
options and their defaults:
    --trace_plotter                  plot_traces
    --trace_plotter_opts             --plotter_terminal "png color"
note: defaults are overwritten by configuration file

Make_report produces a report for the results previously labeled with label_results. A report is an HTML file plus a few images with graphs. At the time of writing, a report includes

1. ``Executive summary'' section with a high level overview of the results,
2. ``Engineer summary'' section with low level aggregate statistics for detailed analysis,
3. ``Potential problems'' section that tries to explain why some numbers on the report are marked with red color (this section appears only if there were some potential problems detected),
4. ``Traces'' section with graphs response time, hit ratio, and other important measurements that often change during the duration of a test, making aggregate statistics less useful.

By default, the ``head'' of the report will be called /tmp/polyrep/label/index.html. We then usually copy the entire /tmp/polyrep/label directory to the Web server for others to see. Note that if you have console access to the machine where the report is being generated, you can use file:/tmp/polyrep/label/ URL to preview the report with your favorite browser.

usage: ./plot_traces [options] <label:object[,object...]> ...
options and their defaults:
    --out_name                       [no default]
    --plot_title                     [no default]
    --plotter                        gnuplot
    --plotter_opts                   -persist
    --plotter_terminal               [no default]
note: defaults are overwritten by configuration file

Plot_traces is used internally by make_report and can also be used as a stand-alone script. As make_report, it can only work with data previously labeled with label_results.

Perhaps one of the most convenient features of plot_traces is the ability to compare two or more measurements from one or more experiments. Each experiment must be labeled (say, exp1, exp2) first, of course. After the labels are assigned, one can compare measurements in the following fashion:

    example> ./plot_traces exp1:req.rate exp1:rep.rate
    example> ./plot_traces exp1:hit.rptm.mean exp2:hit.rptm.mean \
		exp1:req.rate exp2:req.rate
    example> ./plot_traces exp1:hit.ratio.obj,rep.rate \
		exp2:hit.ratio.obj,rep.rate

The above example will display graphs on your screen, assuming that your default ``terminal'' type in gnuplot installation is x11 and that you are running X-Windows. If not, you probably want to use --out_name option to save the resulting graphs into a file.

You have to know the names for the lx objects you want to plot. For the list of all trace-able names that label_results knows about, see the @ObjsToTrace variable in the label_results file.