<p><i>Rumen</i> is a data extraction and analysis tool built for <i>Apache Hadoop</i>. <i>Rumen</i> mines <i>JobHistory</i> logs to extract meaningful data and stores it in an easily-parsed, condensed format or <i>digest</i>. The raw trace data from MapReduce logs are often insufficient for simulation, emulation, and benchmarking, as these tools often attempt to measure conditions that did not occur in the source data. For example, if a task ran locally in the raw trace data but a simulation of the scheduler elects to run that task on a remote rack, the simulator requires a runtime its input cannot provide. To fill in these gaps, Rumen performs a statistical analysis of the digest to estimate the variables the trace doesn’t supply. Rumen traces drive both Gridmix (a benchmark of Hadoop MapReduce clusters) and SLS (a simulator for the resource manager scheduler).</p><section>
<h3><aname="Motivation"></a>Motivation</h3>
<ul>
<li>
<p>Extracting meaningful data from <i>JobHistory</i> logs is a common task for any tool built to work on <i>MapReduce</i>. It is tedious to write a custom tool which is so tightly coupled with the <i>MapReduce</i> framework. Hence there is a need for a built-in tool for performing framework level task of log parsing and analysis. Such a tool would insulate external systems depending on job history against the changes made to the job history format.</p>
</li>
<li>
<p>Performing statistical analysis of various attributes of a <i>MapReduce Job</i> such as <i>task runtimes, task failures etc</i> is another common task that the benchmarking and simulation tools might need. <i>Rumen</i> generates <aclass="externalLink"href="http://en.wikipedia.org/wiki/Cumulative_distribution_function"><i>Cumulative Distribution Functions (CDF)</i></a> for the Map/Reduce task runtimes. Runtime CDF can be used for extrapolating the task runtime of incomplete, missing and synthetic tasks. Similarly CDF is also computed for the total number of successful tasks for every attempt.</p>
</li>
</ul></section><section>
<h3><aname="Components"></a>Components</h3>
<p><i>Rumen</i> consists of 2 components</p>
<ul>
<li>
<p><i>Trace Builder</i> : Converts <i>JobHistory</i> logs into an easily-parsed format. Currently <code>TraceBuilder</code> outputs the trace in <aclass="externalLink"href="http://www.json.org/"><i>JSON</i></a> format.</p>
</li>
<li>
<p>*Folder *: A utility to scale the input trace. A trace obtained from <i>TraceBuilder</i> simply summarizes the jobs in the input folders and files. The time-span within which all the jobs in a given trace finish can be considered as the trace runtime. <i>Folder</i> can be used to scale the runtime of a trace. Decreasing the trace runtime might involve dropping some jobs from the input trace and scaling down the runtime of remaining jobs. Increasing the trace runtime might involve adding some dummy jobs to the resulting trace and scaling up the runtime of individual jobs.</p>
</li>
</ul></section></section><section>
<h2><aname="How_to_use_Rumen.3F"></a>How to use Rumen?</h2>
<p>Converting <i>JobHistory</i> logs into a desired job-trace consists of 2 steps</p>
<olstyle="list-style-type: decimal">
<li>
<p>Extracting information into an intermediate format</p>
</li>
<li>
<p>Adjusting the job-trace obtained from the intermediate trace to have the desired properties.</p>
</li>
</ol>
<blockquote>
<p>Extracting information from <i>JobHistory</i> logs is a one time operation. This so called <i>Gold Trace</i> can be reused to generate traces with desired values of properties such as <code>output-duration</code>, <code>concentration</code> etc.</p>
</blockquote>
<p><i>Rumen</i> provides 2 basic commands</p>
<ul>
<li><code>TraceBuilder</code></li>
<li><code>Folder</code></li>
</ul>
<p>Firstly, we need to generate the <i>Gold Trace</i>. Hence the first step is to run <code>TraceBuilder</code> on a job-history folder. The output of the <code>TraceBuilder</code> is a job-trace file (and an optional cluster-topology file). In case we want to scale the output, we can use the <code>Folder</code> utility to fold the current trace to the desired length. The remaining part of this section explains these utilities in detail.</p><section>
<p>This command invokes the <code>TraceBuilder</code> utility of <i>Rumen</i>.</p>
<p>TraceBuilder converts the JobHistory files into a series of JSON objects and writes them into the <code><jobtrace-output></code> file. It also extracts the cluster layout (topology) and writes it in the<code><topology-output></code> file. <code><inputs></code> represents a space-separated list of JobHistory files and folders.</p>
<blockquote>
<p>1) Input and output to <code>TraceBuilder</code> is expected to be a fully qualified FileSystem path. So use <aclass="externalLink"href="file://">file://</a> to specify files on the <code>local</code> FileSystem and <aclass="externalLink"href="hdfs://">hdfs://</a> to specify files on HDFS. Since input files or folder are FileSystem paths, it means that they can be globbed. This can be useful while specifying multiple file paths using regular expressions.</p>
<p>2) By default, TraceBuilder does not recursively scan the input folder for job history files. Only the files that are directly placed under the input folder will be considered for generating the trace. To add all the files under the input directory by recursively scanning the input directory, use ‘-recursive’ option.</p>
</blockquote>
<p>Cluster topology is used as follows :</p>
<ul>
<li>
<p>To reconstruct the splits and make sure that the distances/latencies seen in the actual run are modeled correctly.</p>
</li>
<li>
<p>To extrapolate splits information for tasks with missing splits details or synthetically generated tasks.</p>
</li>
</ul></section><section>
<h4><aname="Options"></a>Options</h4>
<tableborder="0"class="bodyTable">
<trclass="a">
<th> Parameter</th>
<th> Description</th>
<th> Notes </th>
</tr>
<trclass="b">
<td><code>-demuxer</code></td>
<td>Used to read the jobhistory files. The default is
<code>DefaultInputDemuxer</code>.</td>
<td>Demuxer decides how the input file maps to jobhistory file(s).
Job history logs and job configuration files are typically small
files, and can be more effectively stored when embedded in some
container file format like SequenceFile or TFile. To support such
usage cases, one can specify a customized Demuxer class that can
extract individual job history logs and job configuration files
from the source files.
</td>
</tr>
<trclass="a">
<td><code>-recursive</code></td>
<td>Recursively traverse input paths for job history logs.</td>
<td>This option should be used to inform the TraceBuilder to
recursively scan the input paths and process all the files under it.
Note that, by default, only the history logs that are directly under
the input folder are considered for generating the trace.
<p>This will analyze all the jobs in <code>/tmp/hadoop-yarn/staging/history/done_intermediate/testuser</code> stored on the <code>HDFS</code> FileSystem and output the jobtraces in <code>/tmp/job-trace.json</code> along with topology information in <code>/tmp/job-topology.json</code> stored on the <code>local</code> FileSystem.</p></section></section><section>
<p>This command invokes the <code>Folder</code> utility of <i>Rumen</i>. Folding essentially means that the output duration of the resulting trace is fixed and job timelines are adjusted to respect the final output duration.</p>
<blockquote>
<p>Input and output to <code>Folder</code> is expected to be a fully qualified FileSystem path. So use <code>file://</code> to specify files on the <code>local</code> FileSystem and <code>hdfs://</code> to specify files on HDFS.</p>
</blockquote></section><section>
<h4><aname="Options"></a>Options</h4>
<tableborder="0"class="bodyTable">
<trclass="a">
<th> Parameter</th>
<th> Description</th>
<th> Notes </th>
</tr>
<trclass="b">
<td><code>-input-cycle</code></td>
<td>Defines the basic unit of time for the folding operation. There is
no default value for <code>input-cycle</code>.
<b>Input cycle must be provided</b>.
</td>
<td>'<code>-input-cycle 10m</code>'
implies that the whole trace run will be now sliced at a 10min
interval. Basic operations will be done on the 10m chunks. Note
that *Rumen* understands various time units like
<i>m(min), h(hour), d(days) etc</i>.
</td>
</tr>
<trclass="a">
<td><code>-output-duration</code></td>
<td>This parameter defines the final runtime of the trace.
Default value if <b>1 hour</b>.
</td>
<td>'<code>-output-duration 30m</code>'
implies that the resulting trace will have a max runtime of
30mins. All the jobs in the input trace file will be folded and
scaled to fit this window.
</td>
</tr>
<trclass="b">
<td><code>-concentration</code></td>
<td>Set the concentration of the resulting trace. Default value is
<b>1</b>.
</td>
<td>If the total runtime of the resulting trace is less than the total
runtime of the input trace, then the resulting trace would contain
lesser number of jobs as compared to the input trace. This
essentially means that the output is diluted. To increase the
density of jobs, set the concentration to a higher value.</td>
</tr>
<trclass="a">
<td><code>-debug</code></td>
<td>Run the Folder in debug mode. By default it is set to
<b>false</b>.</td>
<td>In debug mode, the Folder will print additional statements for
debugging. Also the intermediate files generated in the scratch
directory will not be cleaned up.
</td>
</tr>
<trclass="b">
<td><code>-seed</code></td>
<td>Initial seed to the Random Number Generator. By default, a Random
Number Generator is used to generate a seed and the seed value is
reported back to the user for future use.
</td>
<td>If an initial seed is passed, then the <code>Random Number
Generator</code> will generate the random numbers in the same
sequence i.e the sequence of random numbers remains same if the
same seed is used. Folder uses Random Number Generator to decide
whether or not to emit the job.
</td>
</tr>
<trclass="a">
<td><code>-temp-directory</code></td>
<td>Temporary directory for the Folder. By default the <b>output
folder's parent directory</b> is used as the scratch space.
</td>
<td>This is the scratch space used by Folder. All the
temporary files are cleaned up in the end unless the Folder is run
in <code>debug</code> mode.</td>
</tr>
<trclass="b">
<td><code>-skew-buffer-length</code></td>
<td>Enables <i>Folder</i> to tolerate skewed jobs.
The default buffer length is <b>0</b>.</td>
<td>'<code>-skew-buffer-length 100</code>'
indicates that if the jobs appear out of order within a window
size of 100, then they will be emitted in-order by the folder.
If a job appears out-of-order outside this window, then the Folder
will bail out provided <code>-allow-missorting</code> is not set.
<i>Folder</i> reports the maximum skew size seen in the
input trace for future use.
</td>
</tr>
<trclass="a">
<td><code>-allow-missorting</code></td>
<td>Enables <i>Folder</i> to tolerate out-of-order jobs. By default
mis-sorting is not allowed.
</td>
<td>If mis-sorting is allowed, then the <i>Folder</i> will ignore
out-of-order jobs that cannot be deskewed using a skew buffer of
size specified using <code>-skew-buffer-length</code>. If
mis-sorting is not allowed, then the Folder will bail out if the
skew buffer is incapable of tolerating the skew.
</td>
</tr>
</table>
</section><section>
<h4><aname="Examples"></a>Examples</h4><section>
<h5><aname="Folding_an_input_trace_with_10_hours_of_total_runtime_to_generate_an_output_trace_with_1_hour_of_total_runtime"></a>Folding an input trace with 10 hours of total runtime to generate an output trace with 1 hour of total runtime</h5>
<divclass="source">
<divclass="source">
<pre>hadoop rumenfolder \
-output-duration 1h \
-input-cycle 20m \
file:///tmp/job-trace.json \
file:///tmp/job-trace-1hr.json
</pre></div></div>
<p>If the folded jobs are out of order then the command will bail out.</p></section><section>
<h5><aname="Folding_an_input_trace_with_10_hours_of_total_runtime_to_generate_an_output_trace_with_1_hour_of_total_runtime_and_tolerate_some_skewness"></a>Folding an input trace with 10 hours of total runtime to generate an output trace with 1 hour of total runtime and tolerate some skewness</h5>
<divclass="source">
<divclass="source">
<pre>hadoop rumenfolder \
-output-duration 1h \
-input-cycle 20m \
-allow-missorting \
-skew-buffer-length 100 \
file:///tmp/job-trace.json \
file:///tmp/job-trace-1hr.json
</pre></div></div>
<p>If the folded jobs are out of order, then atmost 100 jobs will be de-skewed. If the 101<sup>st</sup> job is <i>out-of-order</i>, then the command will bail out.</p></section><section>
<h5><aname="Folding_an_input_trace_with_10_hours_of_total_runtime_to_generate_an_output_trace_with_1_hour_of_total_runtime_in_debug_mode"></a>Folding an input trace with 10 hours of total runtime to generate an output trace with 1 hour of total runtime in debug mode</h5>
<divclass="source">
<divclass="source">
<pre>hadoop rumenfolder \
-output-duration 1h \
-input-cycle 20m \
-debug -temp-directory file:///tmp/debug \
file:///tmp/job-trace.json \
file:///tmp/job-trace-1hr.json
</pre></div></div>
<p>This will fold the 10hr job-trace file <code>file:///tmp/job-trace.json</code> to finish within 1hr and use <code>file:///tmp/debug</code> as the temporary directory. The intermediate files in the temporary directory will not be cleaned up.</p></section><section>
<h5><aname="Folding_an_input_trace_with_10_hours_of_total_runtime_to_generate_an_output_trace_with_1_hour_of_total_runtime_with_custom_concentration."></a>Folding an input trace with 10 hours of total runtime to generate an output trace with 1 hour of total runtime with custom concentration.</h5>
<divclass="source">
<divclass="source">
<pre>hadoop rumenfolder \
-output-duration 1h \
-input-cycle 20m \
-concentration 2 \
file:///tmp/job-trace.json \
file:///tmp/job-trace-1hr.json
</pre></div></div>
<p>This will fold the 10hr job-trace file <code>file:///tmp/job-trace.json</code> to finish within 1hr with concentration of 2. If the 10h job-trace is folded to 1h, it retains 10% of the jobs by default. With <i>concentration</i> as 2, 20% of the total input jobs will be retained.</p></section></section></section></section><section>
<h2><aname="Appendix"></a>Appendix</h2><section>
<h3><aname="Resources"></a>Resources</h3>
<p><aclass="externalLink"href="https://issues.apache.org/jira/browse/MAPREDUCE-751">MAPREDUCE-751</a> is the main JIRA that introduced <i>Rumen</i> to <i>MapReduce</i>. Look at the MapReduce <aclass="externalLink"href="https://issues.apache.org/jira/browse/MAPREDUCE/component/12313617">rumen-component</a> for further details.</p></section></section>
