Basic usage

barttenbrinke edited this page Sep 4, 2010 · 23 revisions

If you want to analyze a Rails production log file, use the following syntax:

$ request-log-analyzer production.log

This will generate a report, similar to our Sample output. If you want analyze multiple files (because of logrotate or multiple mongrel log files), you can provide multiple filenames or use wildcards. The files will be process in the order that they are given on the command line.

$ request-log-analyzer mongrel.2008-11.log mongrel.2008-12.log mongrel.2009-01.log 
$ request-log-analyzer production.*.log

Parsing from the standard input

Request-log-analyzer can also parse the standard input by using - or STDIN as filename. This is great in combination with the UNIX tail -f command to parse information live, as it is written to the log file.

$ tail -f production.log | request-log-analyzer -

Request-log-analyzer will then parse any information that is written to the log file until it is stopped by pressing CTRL+C, after which it will present the performance report for all data that has been collected up to that point.

Input options

Request-log-analyzer supports many command line options that alter the behavior of the application. The following options determine how input is handled.

Command line option Explanation and default value
Specifies the specified log file format. This can be one of the predefined formats(currently: rails, merb), or can be a filename of a format definition class. Defaults to rails.
--after <date> Only consider requests from <date> or later. Accepts any date that DateTime#parse understands.
--before <date> Only consider requests before <date>. Accepts any date that DateTime#parse understands.
--select <field> <value> Only consider requests for which <field> is equal to <value>. Note that the comparison is case-sensitive and field names are usually in lowercase. You can include --select multiple times and combine it with --reject.
--reject <field> <value> The opposite of --select: only consider requests for which <field> is not equal to <value>.
--parse-strategy <strategy> The parse strategy determines how r-l-a handles request parsing problems. Valid strategies are assume-correct (default), which tries to retain all parsed information and cautious, which discards requests when parsing problems are encountered to improve data validity. See Configure logging for more details on this topic.


To analyze a Merb log file:
$ request-log-analyzer -f merb log/production.log

To analyze a file with a custom file format definition (more info):
$ request-log-analyzer -f my_log_format.rb log/production.log

Only analyze requests from January:
$ request-log-analyzer log/production.log --after 2009-01-01 --before 2009-02-01

Only analyze the show action of the ProjectsController:
$ request-log-analyzer log/production.log
          --select controller ProjectsController --select action show

Output options

The following options determine the output of request-log-analyzer.

Command line option Explanation and default value
--output <format>
-o <format>
Use the given format to format the report. Supported are FixedWidth (default) and HTML
--file <filename> Writes the report to the specified filename. No colors will be used (--boring will be set implicitely).
--mail <emailaddress> Send the result to this email address.
--mailhost <server> The host to send the email to. Defaults to localhost.
--dump <filename> Export results as YAML.
Only ASCII characters without coloring will be used in the output if this flag is set. Set this flag if your terminal application does not support Bash style colors.
--debug Debug information will be printed during parsing if this flag is set. This can be used to detect problems.
--database <filename>
-d <filename>
Create an SQLite 3 database <filename> with all parsed information. See Creating a request database for more information on this topic and how to run queries on the resulting database file.


Write an HTML report to report.html:
$ request-log-analyzer log/production.log --file report.html --output HTML

Only use uncolored ASCII characters in the report:
$ request-log-analyzer log/production.log --boring

Create a database named requests.db with all parsed request information
$ request-log-analyzer log/production.log --database requests.db