Skip to content
Snippets Groups Projects
Commit bcd7b405 authored by Matei Zaharia's avatar Matei Zaharia
Browse files

Merge pull request #200 from andyk/doc 

Updates to docs
parents 840cbcf8 6765d972
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 385 additions and 159 deletions
docs/README.md
+ 8
− 4
View file @ bcd7b405
......@@ -2,19 +2,21 @@ Welcome to the Spark documentation!
This readme will walk you through navigating and building the Spark documentation, which is included here with the Spark source code. You can also find documentation specific to release versions of Spark at http://spark-project.org/documentation.html.
Read on to learn more about viewing documentation in plain text (i.e., markdown) or building the documentation yourself that corresponds to whichever version of Spark you currently have checked out of revision control.
Read on to learn more about viewing documentation in plain text (i.e., markdown) or building the documentation yourself. Why build it yourself? So that you have the docs that corresponds to whichever version of Spark you currently have checked out of revision control.
## Generating the Documentation HTML
We include the Spark documentation as part of the source (as opposed to using a hosted wiki as the definitive documentation) to enable the documentation to evolve along with the source code and be captured by revision control (currently git). This way the code automatically includes the version of the documentation that is relevant regardless of which version or release you have checked out or downloaded.
We include the Spark documentation as part of the source (as opposed to using a hosted wiki, such as the github wiki, as the definitive documentation) to enable the documentation to evolve along with the source code and be captured by revision control (currently git). This way the code automatically includes the version of the documentation that is relevant regardless of which version or release you have checked out or downloaded.
In this directory you will find textfiles formatted using Markdown, with an ".md" suffix. You can read those text files directly if you want. Start with index.md.
To make things quite a bit prettier and make the links easier to follow, generate the html version of the documentation based on the src directory by running `jekyll` in the docs directory (You will need to have Jekyll installed, the easiest way to do this is via a Ruby Gem). This will create a directory called _site which will contain index.html as well as the rest of the compiled files. Read more about Jekyll at https://github.com/mojombo/jekyll/wiki.
To make things quite a bit prettier and make the links easier to follow, generate the html version of the documentation based on the src directory by running `jekyll` in the docs directory. To do so, you will need to have Jekyll installed, the easiest way to do this is via a Ruby Gem, see the [jekyll installation instructions](https://github.com/mojombo/jekyll/wiki/install). This will create a directory called _site containing index.html as well as the rest of the compiled files. Read more about Jekyll at https://github.com/mojombo/jekyll/wiki.
In addition to generating the site as html from the markdown files, jekyll can serve up the site via a webserver. To build and run a webserver use the command `jekyll --server` which (currently) runs the webserver on port 4000, then visit the site at http://localhost:4000.
## Pygments
We also use pygments (http://pygments.org) for syntax highlighting, so you will also need to install that (it requires Python) by running `sudo easy_install Pygments`.
We also use pygments (http://pygments.org) for syntax highlighting in documentation markdown pages, so you will also need to install that (it requires Python) by running `sudo easy_install Pygments`.
To mark a block of code in your markdown to be syntax highlighted by jekyll during the compile phase, use the following sytax:
......@@ -26,3 +28,5 @@ To mark a block of code in your markdown to be syntax highlighted by jekyll duri
## Scaladoc
You can build just the Spark scaladoc by running `sbt/sbt doc` from the SPARK_PROJECT_ROOT directory.
When you run `jekyll` in the docs directory, it will also copy over the scala doc for the various Spark subprojects into the docs directory (and then also into the _site directory). We use a jekyll plugin to run `sbt/sbt doc` before building the site so if you haven't run it (recently) it may take some time as it generates all of the scaladoc.
docs/_layouts/global.html
+ 20
− 27
View file @ bcd7b405
......@@ -8,7 +8,6 @@
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>{{ page.title }}</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width">
<link rel="stylesheet" href="{{HOME_PATH}}css/bootstrap.min.css">
<style>
......@@ -17,6 +16,7 @@
padding-bottom: 40px;
}
</style>
<meta name="viewport" content="width=device-width">
<link rel="stylesheet" href="{{HOME_PATH}}css/bootstrap-responsive.min.css">
<link rel="stylesheet" href="{{HOME_PATH}}css/main.css">
......@@ -33,32 +33,25 @@
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="{{HOME_PATH}}index.html">Spark</a>
<div class="nav-collapse collapse">
<ul class="nav">
<!--TODO(andyk): Add class="active" attribute to li some how.-->
<li><a href="{{HOME_PATH}}index.html">Home</a></li>
<li><a href="{{HOME_PATH}}programming-guide.html">Programming Guide</a></li>
<li><a href="{{HOME_PATH}}api">API (Scaladoc)</a></li>
<!--
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Versions ({{ page.spark-version }})<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="#">Something else here</a></li>
<li class="divider"></li>
<li class="nav-header">Nav header</li>
<li><a href="#">Separated link</a></li>
<li><a href="#">One more separated link</a></li>
</ul>
</li>
-->
</ul>
</div><!--/.nav-collapse -->
<a class="brand" href="{{HOME_PATH}}index.html"></a>
<ul class="nav">
<!--TODO(andyk): Add class="active" attribute to li some how.-->
<li><a href="{{HOME_PATH}}index.html">Home</a></li>
<li><a href="{{HOME_PATH}}programming-guide.html">Programming Guide</a></li>
<li><a href="{{HOME_PATH}}api.html">API (Scaladoc)</a></li>
<!--
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Versions ({{ page.spark-version }})<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="#">Something else here</a></li>
<li class="divider"></li>
<li class="nav-header">Nav header</li>
<li><a href="#">Separated link</a></li>
<li><a href="#">One more separated link</a></li>
</ul>
</li>
-->
</ul>
</div>
</div>
</div>
......
docs/_plugins/copy_api_dirs.rb 0 → 100644
+ 28
− 0
View file @ bcd7b405
require 'fileutils'
include FileUtils
projects = ["core", "examples", "repl", "bagel"]
puts "Moving to project root and building scaladoc."
curr_dir = pwd
cd("..")
puts "Running sbt/sbt doc from " + pwd + "; this may take a few minutes..."
puts `sbt/sbt doc`
puts "moving back into docs dir."
cd("docs")
# Copy over the scaladoc from each project into the docs directory.
# This directory will be copied over to _site when `jekyll` command is run.
projects.each do |project_name|
source = "../" + project_name + "/target/scala-2.9.1/api"
dest = "api/" + project_name
puts "echo making directory " + dest
mkdir_p dest
# From the rubydoc: cp_r('src', 'dest') makes src/dest, but this doesn't.
puts "cp -r " + source + "/. " + dest
cp_r(source + "/.", dest)
end
docs/api.md 0 → 100644
+ 11
− 0
View file @ bcd7b405
---
layout: global
title: Spark API documentation (Scaladoc)
---
Here you can find links to the Scaladoc generated for the Spark sbt subprojects. If the following links don't work, try running `sbt/sbt doc` from the Spark project home directory.
- [Core](api/core/index.html)
- [Examples](api/examples/index.html)
- [Repl](api/repl/index.html)
- [Bagel](api/bagel/index.html)
docs/bagel-programming-guide.md
+ 90
− 73
View file @ bcd7b405
......@@ -27,58 +27,66 @@ We first extend the default `Vertex` class to store a `Double`
representing the current PageRank of the vertex, and similarly extend
the `Message` and `Edge` classes. Note that these need to be marked `@serializable` to allow Spark to transfer them across machines. We also import the Bagel types and implicit conversions.
import spark.bagel._
import spark.bagel.Bagel._
@serializable class PREdge(val targetId: String) extends Edge
@serializable class PRVertex(
val id: String, val rank: Double, val outEdges: Seq[Edge],
val active: Boolean) extends Vertex
@serializable class PRMessage(
val targetId: String, val rankShare: Double) extends Message
{% highlight scala %}
import spark.bagel._
import spark.bagel.Bagel._
@serializable class PREdge(val targetId: String) extends Edge
@serializable class PRVertex(
val id: String, val rank: Double, val outEdges: Seq[Edge],
val active: Boolean) extends Vertex
@serializable class PRMessage(
val targetId: String, val rankShare: Double) extends Message
{% endhighlight %}
Next, we load a sample graph from a text file as a distributed dataset and package it into `PRVertex` objects. We also cache the distributed dataset because Bagel will use it multiple times and we'd like to avoid recomputing it.
val input = sc.textFile("pagerank_data.txt")
{% highlight scala %}
val input = sc.textFile("pagerank_data.txt")
val numVerts = input.count()
val numVerts = input.count()
val verts = input.map(line => {
val fields = line.split('\t')
val (id, linksStr) = (fields(0), fields(1))
val links = linksStr.split(',').map(new PREdge(_))
(id, new PRVertex(id, 1.0 / numVerts, links, true))
}).cache
val verts = input.map(line => {
val fields = line.split('\t')
val (id, linksStr) = (fields(0), fields(1))
val links = linksStr.split(',').map(new PREdge(_))
(id, new PRVertex(id, 1.0 / numVerts, links, true))
}).cache
{% endhighlight %}
We run the Bagel job, passing in `verts`, an empty distributed dataset of messages, and a custom compute function that runs PageRank for 10 iterations.
val emptyMsgs = sc.parallelize(List[(String, PRMessage)]())
def compute(self: PRVertex, msgs: Option[Seq[PRMessage]], superstep: Int)
: (PRVertex, Iterable[PRMessage]) = {
val msgSum = msgs.getOrElse(List()).map(_.rankShare).sum
val newRank =
if (msgSum != 0)
0.15 / numVerts + 0.85 * msgSum
else
self.rank
val halt = superstep >= 10
val msgsOut =
if (!halt)
self.outEdges.map(edge =>
new PRMessage(edge.targetId, newRank / self.outEdges.size))
else
List()
(new PRVertex(self.id, newRank, self.outEdges, !halt), msgsOut)
}
val result = Bagel.run(sc, verts, emptyMsgs)()(compute)
{% highlight scala %}
val emptyMsgs = sc.parallelize(List[(String, PRMessage)]())
def compute(self: PRVertex, msgs: Option[Seq[PRMessage]], superstep: Int)
: (PRVertex, Iterable[PRMessage]) = {
val msgSum = msgs.getOrElse(List()).map(_.rankShare).sum
val newRank =
if (msgSum != 0)
0.15 / numVerts + 0.85 * msgSum
else
self.rank
val halt = superstep >= 10
val msgsOut =
if (!halt)
self.outEdges.map(edge =>
new PRMessage(edge.targetId, newRank / self.outEdges.size))
else
List()
(new PRVertex(self.id, newRank, self.outEdges, !halt), msgsOut)
}
{% endhighlight %}
val result = Bagel.run(sc, verts, emptyMsgs)()(compute)
Finally, we print the results.
println(result.map(v => "%s\t%s\n".format(v.id, v.rank)).collect.mkString)
{% highlight scala %}
println(result.map(v => "%s\t%s\n".format(v.id, v.rank)).collect.mkString)
{% endhighlight %}
### Combiners
......@@ -102,41 +110,50 @@ Here are the actions and types in the Bagel API. See [Bagel.scala](https://githu
#### Actions
# Full form
Bagel.run(sc, vertices, messages, combiner, aggregator, partitioner, numSplits)(compute)
where compute takes (vertex: V, combinedMessages: Option[C], aggregated: Option[A], superstep: Int)
and returns (newVertex: V, outMessages: Array[M])
# Abbreviated forms
Bagel.run(sc, vertices, messages, combiner, partitioner, numSplits)(compute)
where compute takes (vertex: V, combinedMessages: Option[C], superstep: Int)
and returns (newVertex: V, outMessages: Array[M])
Bagel.run(sc, vertices, messages, combiner, numSplits)(compute)
where compute takes (vertex: V, combinedMessages: Option[C], superstep: Int)
and returns (newVertex: V, outMessages: Array[M])
Bagel.run(sc, vertices, messages, numSplits)(compute)
where compute takes (vertex: V, messages: Option[Array[M]], superstep: Int)
and returns (newVertex: V, outMessages: Array[M])
{% highlight scala %}
/*** Full form ***/
Bagel.run(sc, vertices, messages, combiner, aggregator, partitioner, numSplits)(compute)
// where compute takes (vertex: V, combinedMessages: Option[C], aggregated: Option[A], superstep: Int)
// and returns (newVertex: V, outMessages: Array[M])
/*** Abbreviated forms ***/
Bagel.run(sc, vertices, messages, combiner, partitioner, numSplits)(compute)
// where compute takes (vertex: V, combinedMessages: Option[C], superstep: Int)
// and returns (newVertex: V, outMessages: Array[M])
Bagel.run(sc, vertices, messages, combiner, numSplits)(compute)
// where compute takes (vertex: V, combinedMessages: Option[C], superstep: Int)
// and returns (newVertex: V, outMessages: Array[M])
Bagel.run(sc, vertices, messages, numSplits)(compute)
// where compute takes (vertex: V, messages: Option[Array[M]], superstep: Int)
// and returns (newVertex: V, outMessages: Array[M])
{% endhighlight %}
#### Types
trait Combiner[M, C] {
def createCombiner(msg: M): C
def mergeMsg(combiner: C, msg: M): C
def mergeCombiners(a: C, b: C): C
}
trait Aggregator[V, A] {
def createAggregator(vert: V): A
def mergeAggregators(a: A, b: A): A
}
trait Vertex {
def active: Boolean
}
trait Message[K] {
def targetId: K
}
{% highlight scala %}
trait Combiner[M, C] {
def createCombiner(msg: M): C
def mergeMsg(combiner: C, msg: M): C
def mergeCombiners(a: C, b: C): C
}
trait Aggregator[V, A] {
def createAggregator(vert: V): A
def mergeAggregators(a: A, b: A): A
}
trait Vertex {
def active: Boolean
}
trait Message[K] {
def targetId: K
}
{% endhighlight %}
## Where to Go from Here
......
docs/css/main.css
+ 9
− 6
View file @ bcd7b405
---
---
/* ==========================================================================
Author's custom styles
========================================================================== */
/*.brand {
background: url({{HOME_PATH}}img/spark-logo.jpg) no-repeat left center;
.navbar .brand {
background: url(../img/spark-logo-77x40px-hd.png) no-repeat left center;
height: 40px;
width: 100px;
width: 77px;
padding: 0 10px 0 0;
}
.navbar-inner {
padding-top: 5px;
padding-bottom: 5px;
}
*/
body #content {
line-height: 1.6; /* Inspired by Github's wiki style */
......
docs/ec2-scripts.md 0 → 100644
+ 146
− 0
View file @ bcd7b405
---
layout: global
title: Using the Spark EC2 Scripts
---
The `spark-ec2` script located in the Spark's `ec2` directory allows you
to launch, manage and shut down Spark clusters on Amazon EC2. It builds
on the [Mesos EC2 script](https://github.com/mesos/mesos/wiki/EC2-Scripts)
in Apache Mesos.
`spark-ec2` is designed to manage multiple named clusters. You can
launch a new cluster (telling the script its size and giving it a name),
shutdown an existing cluster, or log into a cluster. Each cluster is
identified by placing its machines into EC2 security groups whose names
are derived from the name of the cluster. For example, a cluster named
`test` will contain a master node in a security group called
`test-master`, and a number of slave nodes in a security group called
`test-slaves`. The `spark-ec2` script will create these security groups
for you based on the cluster name you request. You can also use them to
identify machines belonging to each cluster in the EC2 Console or
ElasticFox.
This guide describes how to get set up to run clusters, how to launch
clusters, how to run jobs on them, and how to shut them down.
Before You Start
================
- Create an Amazon EC2 key pair for yourself. This can be done by
logging into your Amazon Web Services account through the [AWS
console](http://aws.amazon.com/console/), clicking Key Pairs on the
left sidebar, and creating and downloading a key. Make sure that you
set the permissions for the private key file to `600` (i.e. only you
can read and write it) so that `ssh` will work.
- Whenever you want to use the `spark-ec2` script, set the environment
variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to your
Amazon EC2 access key ID and secret access key. These can be
obtained from the [AWS homepage](http://aws.amazon.com/) by clicking
Account \> Security Credentials \> Access Credentials.
Launching a Cluster
===================
- Go into the `ec2` directory in the release of Spark you downloaded.
- Run
`./spark-ec2 -k <keypair> -i <key-file> -s <num-slaves> launch <cluster-name>`,
where `<keypair>` is the name of your EC2 key pair (that you gave it
when you created it), `<key-file>` is the private key file for your
key pair, `<num-slaves>` is the number of slave nodes to launch (try
1 at first), and `<cluster-name>` is the name to give to your
cluster.
- After everything launches, check that Mesos is up and sees all the
slaves by going to the Mesos Web UI link printed at the end of the
script (`http://<master-hostname>:8080`).
You can also run `./spark-ec2 --help` to see more usage options. The
following options are worth pointing out:
- `--instance-type=<INSTANCE_TYPE>` can be used to specify an EC2
instance type to use. For now, the script only supports 64-bit instance
types, and the default type is `m1.large` (which has 2 cores and 7.5 GB
RAM). Refer to the Amazon pages about [EC2 instance
types](http://aws.amazon.com/ec2/instance-types) and [EC2
pricing](http://aws.amazon.com/ec2/#pricing) for information about other
instance types.
- `--zone=<EC2_ZONE>` can be used to specify an EC2 availability zone
to launch instances in. Sometimes, you will get an error because there
is not enough capacity in one zone, and you should try to launch in
another. This happens mostly with the `m1.large` instance types;
extra-large (both `m1.xlarge` and `c1.xlarge`) instances tend to be more
available.
- `--ebs-vol-size=GB` will attach an EBS volume with a given amount
of space to each node so that you can have a persistent HDFS cluster
on your nodes across cluster restarts (see below).
- If one of your launches fails due to e.g. not having the right
permissions on your private key file, you can run `launch` with the
`--resume` option to restart the setup process on an existing cluster.
Running Jobs
============
- Go into the `ec2` directory in the release of Spark you downloaded.
- Run `./spark-ec2 -k <keypair> -i <key-file> login <cluster-name>` to
SSH into the cluster, where `<keypair>` and `<key-file>` are as
above. (This is just for convenience; you could also use
the EC2 console.)
- To deploy code or data within your cluster, you can log in and use the
provided script `~/mesos-ec2/copy-dir`, which,
given a directory path, RSYNCs it to the same location on all the slaves.
- If your job needs to access large datasets, the fastest way to do
that is to load them from Amazon S3 or an Amazon EBS device into an
instance of the Hadoop Distributed File System (HDFS) on your nodes.
The `spark-ec2` script already sets up a HDFS instance for you. It's
installed in `/root/ephemeral-hdfs`, and can be accessed using the
`bin/hadoop` script in that directory. Note that the data in this
HDFS goes away when you stop and restart a machine.
- There is also a *persistent HDFS* instance in
`/root/presistent-hdfs` that will keep data across cluster restarts.
Typically each node has relatively little space of persistent data
(about 3 GB), but you can use the `--ebs-vol-size` option to
`spark-ec2` to attach a persistent EBS volume to each node for
storing the persistent HDFS.
- Finally, if you get errors while running your jobs, look at the slave's logs
for that job using the Mesos web UI (`http://<master-hostname>:8080`).
Terminating a Cluster
=====================
***Note that there is no way to recover data on EC2 nodes after shutting
them down! Make sure you have copied everything important off the nodes
before stopping them.***
- Go into the `ec2` directory in the release of Spark you downloaded.
- Run `./spark-ec2 destroy <cluster-name>`.
Pausing and Restarting Clusters
===============================
The `spark-ec2` script also supports pausing a cluster. In this case,
the VMs are stopped but not terminated, so they
***lose all data on ephemeral disks*** but keep the data in their
root partitions and their `persistent-hdfs`. Stopped machines will not
cost you any EC2 cycles, but ***will*** continue to cost money for EBS
storage.
- To stop one of your clusters, go into the `ec2` directory and run
`./spark-ec2 stop <cluster-name>`.
- To restart it later, run
`./spark-ec2 -i <key-file> start <cluster-name>`.
- To ultimately destroy the cluster and stop consuming EBS space, run
`./spark-ec2 destroy <cluster-name>` as described in the previous
section.
Limitations
===========
- `spark-ec2` currently only launches machines in the US-East region of EC2.
It should not be hard to make it launch VMs in other zones, but you will need
to create your own AMIs in them.
- Support for "cluster compute" nodes is limited -- there's no way to specify a
locality group. However, you can launch slave nodes in your
`<clusterName>-slaves` group manually and then use `spark-ec2 launch
--resume` to start a cluster with them.
- Support for spot instances is limited.
If you have a patch or suggestion for one of these limitations, feel free to
[contribute]({{HOME_PATH}}contributing-to-spark.html) it!
docs/img/spark-logo-100x40px.png 0 → 100644
+ 0
− 0
View file @ bcd7b405
docs/img/spark-logo-100x40px.png

3.55 KiB

docs/img/spark-logo-77x40px-hd.png 0 → 100644
+ 0
− 0
View file @ bcd7b405
docs/img/spark-logo-77x40px-hd.png

1.86 KiB

docs/running-on-mesos.md
+ 17
− 6
View file @ bcd7b405
......@@ -21,19 +21,27 @@ To run on a cluster, Spark uses the [Apache Mesos](http://incubator.apache.org/m
* Run `<prefix>/sbin/mesos-start-cluster.sh` on your master to start Mesos. If all goes well, you should see Mesos's web UI on port 8080 of the master machine.
* See Mesos's README file for more information on deploying it.
8. To run a Spark job against the cluster, when you create your `SparkContext`, pass the string `HOST:5050` as the first parameter, where `HOST` is the machine running your Mesos master. In addition, pass the location of Spark on your nodes as the third parameter, and a list of JAR files containing your JAR's code as the fourth (these will automatically get copied to the workers). For example:
<pre>new SparkContext("HOST:5050", "My Job Name", "/home/user/spark", List("my-job.jar"))</pre>
{% highlight scala %}
new SparkContext("HOST:5050", "My Job Name", "/home/user/spark", List("my-job.jar"))
{% endhighlight %}
### For Spark versions before 0.5:
1. Download and build Spark using the instructions [here]({{ HOME_DIR }}Home).
2. Download either revision 1205738 of Mesos if you're using the master branch of Spark, or the pre-protobuf branch of Mesos if you're using Spark 0.3 or earlier (note that for new users, _we recommend the master branch instead of 0.3_). For revision 1205738 of Mesos, use:
<pre>
{% highlight bash %}
svn checkout -r 1205738 http://svn.apache.org/repos/asf/incubator/mesos/trunk mesos
</pre>
{% endhighlight %}
For the pre-protobuf branch (for Spark 0.3 and earlier), use:
<pre>git clone git://github.com/mesos/mesos
{% highlight bash %}
git clone git://github.com/mesos/mesos
cd mesos
git checkout --track origin/pre-protobuf</pre>
git checkout --track origin/pre-protobuf
{% endhighlight %}
3. Configure Mesos using the `configure` script, passing the location of your `JAVA_HOME` using `--with-java-home`. Mesos comes with "template" configure scripts for different platforms, such as `configure.template.macosx`, so you can just run the one on your platform if it exists. See the [Mesos wiki](https://github.com/mesos/mesos/wiki) for other configuration options.
4. Build Mesos using `make`.
5. In Spark's `conf/spark-env.sh` file, add `export MESOS_HOME=<path to Mesos directory>`. If you don't have a `spark-env.sh`, copy `conf/spark-env.sh.template`. You should also set `SCALA_HOME` there if it's not on your system's default path.
......@@ -43,7 +51,10 @@ git checkout --track origin/pre-protobuf</pre>
* Run `MESOS_HOME/deploy/start-mesos` to start it up. If all goes well, you should see Mesos's web UI on port 8080 of the master machine.
* See Mesos's [deploy instructions](https://github.com/mesos/mesos/wiki/Deploy-Scripts) for more information on deploying it.
8. To run a Spark job against the cluster, when you create your `SparkContext`, pass the string `master@HOST:5050` as the first parameter, where `HOST` is the machine running your Mesos master. In addition, pass the location of Spark on your nodes as the third parameter, and a list of JAR files containing your JAR's code as the fourth (these will automatically get copied to the workers). For example:
<pre>new SparkContext("master@HOST:5050", "My Job Name", "/home/user/spark", List("my-job.jar"))</pre>
{% highlight scala %}
new SparkContext("master@HOST:5050", "My Job Name", "/home/user/spark", List("my-job.jar"))
{% endhighlight %}
## Running on Amazon EC2
......
docs/spark-debugger.md
+ 56
− 43
View file @ bcd7b405
......@@ -27,82 +27,95 @@ _A note on nondeterminism:_ For fault recovery, Spark requires RDD transformatio
### Enabling the event log
* To turn on event logging for your program, set `$SPARK_JAVA_OPTS` in `conf/spark-env.sh` as follows:
export SPARK_JAVA_OPTS='-Dspark.arthur.logPath=path/to/event-log'
where `path/to/event-log` is where you want the event log to go relative to `$SPARK_HOME`.
To turn on event logging for your program, set `$SPARK_JAVA_OPTS` in `conf/spark-env.sh` as follows:
**Warning:** If `path/to/event-log` already exists, event logging will be automatically disabled.
{% highlight bash %}
export SPARK_JAVA_OPTS='-Dspark.arthur.logPath=path/to/event-log'
{% endhighlight %}
where `path/to/event-log` is where you want the event log to go relative to `$SPARK_HOME`.
**Warning:** If `path/to/event-log` already exists, event logging will be automatically disabled.
### Loading the event log into the debugger
1. Run a Spark shell with `MASTER=<i>host</i> ./spark-shell`.
2. Use `EventLogReader` to load the event log as follows:
spark> val r = new spark.EventLogReader(sc, Some("path/to/event-log"))
r: spark.EventLogReader = spark.EventLogReader@726b37ad
{% highlight scala %}
spark> val r = new spark.EventLogReader(sc, Some("path/to/event-log"))
r: spark.EventLogReader = spark.EventLogReader@726b37ad
{% endhighlight %}
**Warning:** If the event log doesn't exist or is unreadable, this will silently fail and `r.events` will be empty.
### Exploring intermediate RDDs
* Use `r.rdds` to get a list of intermediate RDDs generated during your program's execution. An RDD with id _x_ is located at <code>r.rdds(<i>x</i>)</code>. For example:
Use `r.rdds` to get a list of intermediate RDDs generated during your program's execution. An RDD with id _x_ is located at <code>r.rdds(<i>x</i>)</code>. For example:
scala> r.rdds
res8: scala.collection.mutable.ArrayBuffer[spark.RDD[_]] = ArrayBuffer(spark.HadoopRDD@fe85adf, spark.MappedRDD@5fa5eea1, spark.MappedRDD@6d5bd16, spark.ShuffledRDD@3a70f2db, spark.FlatMappedValuesRDD@4d5825d6, spark.MappedValuesRDD@561c2c45, spark.CoGroupedRDD@539e922d, spark.MappedValuesRDD@4f8ef33e, spark.FlatMappedRDD@32039440, spark.ShuffledRDD@8fa0f67, spark.MappedValuesRDD@590937cb, spark.CoGroupedRDD@6c2e1e17, spark.MappedValuesRDD@47b9af7d, spark.FlatMappedRDD@6fb05c54, spark.ShuffledRDD@237dc815, spark.MappedValuesRDD@16daece7, spark.CoGroupedRDD@7ef73d69, spark.MappedValuesRDD@19e0f99e, spark.FlatMappedRDD@1240158, spark.ShuffledRDD@62d438fd, spark.MappedValuesRDD@5ae99cbb, spark.FilteredRDD@1f30e79e, spark.MappedRDD@43b64611)
{% highlight scala %}
scala> r.rdds
res8: scala.collection.mutable.ArrayBuffer[spark.RDD[_]] = ArrayBuffer(spark.HadoopRDD@fe85adf, spark.MappedRDD@5fa5eea1, spark.MappedRDD@6d5bd16, spark.ShuffledRDD@3a70f2db, spark.FlatMappedValuesRDD@4d5825d6, spark.MappedValuesRDD@561c2c45, spark.CoGroupedRDD@539e922d, spark.MappedValuesRDD@4f8ef33e, spark.FlatMappedRDD@32039440, spark.ShuffledRDD@8fa0f67, spark.MappedValuesRDD@590937cb, spark.CoGroupedRDD@6c2e1e17, spark.MappedValuesRDD@47b9af7d, spark.FlatMappedRDD@6fb05c54, spark.ShuffledRDD@237dc815, spark.MappedValuesRDD@16daece7, spark.CoGroupedRDD@7ef73d69, spark.MappedValuesRDD@19e0f99e, spark.FlatMappedRDD@1240158, spark.ShuffledRDD@62d438fd, spark.MappedValuesRDD@5ae99cbb, spark.FilteredRDD@1f30e79e, spark.MappedRDD@43b64611)
{% endhighlight %}
* Use `r.printRDDs()` to get a formatted list of intermediate RDDs, along with the source location where they were created. For example:
Use `r.printRDDs()` to get a formatted list of intermediate RDDs, along with the source location where they were created. For example:
scala> r.printRDDs
#00: HadoopRDD spark.bagel.examples.WikipediaPageRankStandalone$.main(WikipediaPageRankStandalone.scala:31)
#01: MappedRDD spark.bagel.examples.WikipediaPageRankStandalone$.main(WikipediaPageRankStandalone.scala:31)
#02: MappedRDD spark.bagel.examples.WikipediaPageRankStandalone$.main(WikipediaPageRankStandalone.scala:35)
#03: ShuffledRDD spark.bagel.examples.WikipediaPageRankStandalone$.main(WikipediaPageRankStandalone.scala:35)
#04: FlatMappedValuesRDD spark.bagel.examples.WikipediaPageRankStandalone$.main(WikipediaPageRankStandalone.scala:35)
#05: MappedValuesRDD spark.bagel.examples.WikipediaPageRankStandalone$.pageRank(WikipediaPageRankStandalone.scala:91)
#06: CoGroupedRDD spark.bagel.examples.WikipediaPageRankStandalone$.pageRank(WikipediaPageRankStandalone.scala:92)
[...]
{% highlight scala %}
scala> r.printRDDs
#00: HadoopRDD spark.bagel.examples.WikipediaPageRankStandalone$.main(WikipediaPageRankStandalone.scala:31)
#01: MappedRDD spark.bagel.examples.WikipediaPageRankStandalone$.main(WikipediaPageRankStandalone.scala:31)
#02: MappedRDD spark.bagel.examples.WikipediaPageRankStandalone$.main(WikipediaPageRankStandalone.scala:35)
#03: ShuffledRDD spark.bagel.examples.WikipediaPageRankStandalone$.main(WikipediaPageRankStandalone.scala:35)
#04: FlatMappedValuesRDD spark.bagel.examples.WikipediaPageRankStandalone$.main(WikipediaPageRankStandalone.scala:35)
#05: MappedValuesRDD spark.bagel.examples.WikipediaPageRankStandalone$.pageRank(WikipediaPageRankStandalone.scala:91)
#06: CoGroupedRDD spark.bagel.examples.WikipediaPageRankStandalone$.pageRank(WikipediaPageRankStandalone.scala:92)
[...]
{% endhighlight %}
* Use `r.visualizeRDDs()` to visualize the RDDs as a dependency graph. For example:
Use `r.visualizeRDDs()` to visualize the RDDs as a dependency graph. For example:
scala> r.visualizeRDDs
/tmp/spark-rdds-3758182885839775712.pdf
{% highlight scala %}
scala> r.visualizeRDDs
/tmp/spark-rdds-3758182885839775712.pdf
{% endhighlight %}
![Example RDD dependency graph](http://www.ankurdave.com/images/rdd-dep-graph.png)
![Example RDD dependency graph](http://www.ankurdave.com/images/rdd-dep-graph.png)
* Iterate over the `RDDCreation` entries in `r.events` (e.g. `for (RDDCreation(rdd, location) <- events)`) to access the RDD creation locations as well as the RDDs themselves.
Iterate over the `RDDCreation` entries in `r.events` (e.g. `for (RDDCreation(rdd, location) <- events)`) to access the RDD creation locations as well as the RDDs themselves.
### Debugging a particular task
1. Find the task you want to debug. If the task threw an exception, the `ExceptionEvent` that was created will have a reference to the task. For example:
spark> val task = r.events.collect { case e: ExceptionEvent => e }.head.task
{% highlight scala %}
spark> val task = r.events.collect { case e: ExceptionEvent => e }.head.task
{% endhighlight %}
Otherwise, look through the list of all tasks in `r.tasks`, or browse tasks by RDD using <code>r.tasksForRDD(<i>rdd</i>)</code>, which returns a list of tasks whose input is the given RDD.
2. Run the task by calling <code>r.debugTask(<i>taskStageId</i>, <i>taskPartition</i>)</code>. The task should contain these two values; you can extract them as follows:
val (taskStageId, taskPartition) = task match {
case rt: ResultTask[_, _] => (rt.stageId, rt.partition)
case smt: ShuffleMapTask => (smt.stageId, smt.partition)
case _ => throw new UnsupportedOperationException
})
The Spark debugger will launch the task in a separate JVM, but you will see the task's stdout and stderr inline with the Spark shell. If you want to pass custom debugging arguments to the task's JVM (for example, to change the debugging port), set the optional `debugOpts` argument to `r.debugTask`. When `debugOpts` is left unset, it defaults to
-Xdebug -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8000
{% highlight scala %}
val (taskStageId, taskPartition) = task match {
case rt: ResultTask[_, _] => (rt.stageId, rt.partition)
case smt: ShuffleMapTask => (smt.stageId, smt.partition)
case _ => throw new UnsupportedOperationException
})
{% endhighlight %}
The Spark debugger will launch the task in a separate JVM, but you will see the task's stdout and stderr inline with the Spark shell. If you want to pass custom debugging arguments to the task's JVM (for example, to change the debugging port), set the optional `debugOpts` argument to `r.debugTask`. When `debugOpts` is left unset, it defaults to:
{% highlight scala %}
-Xdebug -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8000
{% endhighlight %}
3. In another terminal, attach your favorite conventional debugger to the Spark shell. For example, if you want to use jdb, run `jdb -attach 8000`.
4. Debug the task as you would debug a normal program. For example, to break when an exception is thrown:
> catch org.xml.sax.SAXParseException
{% highlight scala %}
> catch org.xml.sax.SAXParseException
{% endhighlight %}
5. When the task ends, its JVM will quit and control will return to the main Spark shell. To stop it prematurely, you can kill it from the debugger, or interrupt it from the terminal with Ctrl-C.
### Detecting nondeterminism in your transformations
When a task gets run more than once, Arthur is able to compare the checksums of the task's output. If they are different, Arthur will insert a `ChecksumEvent` into `r.checksumMismatches` and print a warning like the following:
{% highlight scala %}
12/04/07 11:42:44 WARN spark.EventLogWriter: Nondeterminism detected in shuffle output on RDD 2, partition 3, output split 0
{% endhighlight %}
12/04/07 11:42:44 WARN spark.EventLogWriter: Nondeterminism detected in shuffle output on RDD 2, partition 3, output split 0
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment