doc/user/intro-jobs.textile

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Intro: Jobs"
   5 navorder: 8
   6 ---
   7
   8 h1. Intro: Jobs
   9
  10 You can run MapReduce jobs by storing a job script in a git repository and creating a "job":../api/Jobs.html.
  11
  12 Crunch jobs offer several advantages over running programs on your own local machine:
  13
  14 * Increase concurrency by running tasks asynchronously, using many CPUs and network interfaces at once (especially beneficial for CPU-bound and I/O-bound tasks respectively).
  15
  16 * Track inputs, outputs, and settings so you can verify that the inputs, settings, and sequence of programs you used to arrive at an output is really what you think it was.
  17
  18 * Ensure that your programs and workflows are repeatable with different versions of your code, OS updates, etc.
  19
  20 * Interrupt and resume long-running jobs consisting of many short tasks.
  21
  22 * Maintain timing statistics automatically, so they're there when you want them.
  23
  24 h3. Structure of a job
  25
  26 A job consists of a number of tasks which can be executed asynchronously.
  27
  28 A single job program, or "crunch script", executes each task of a given job. The logic of a typical crunch script looks like this:
  29
  30 * If this is the first task: examine the input, divide it into a number of asynchronous tasks, instruct Arvados to queue these tasks, output nothing, and indicate successful completion.
  31
  32 * Otherwise, fetch a portion of the input from the cloud storage system, do some computation, store some output in the cloud, output a fragment of the output manifest, and indicate successful completion.
  33
  34 When all job tasks have completed, the output fragments are assembled into a single output manifest.
  35
  36 If a job task fails, it is automatically re-attempted.  If a task fails repeatedly and running it on a different compute node doesn't help, any tasks still running are allowed to complete, and the job is abandoned.
  37
  38 h3. Developing and testing crunch scripts
  39
  40 Usually, it makes sense to test your script locally on small data sets.  When you are satisfied that it works, commit it to the git repository and run it in Arvados.
  41
  42 Save your job script (say, @foo@) in @{git-repo}/crunch_scripts/foo@.
  43
  44 Make sure you have @ARVADOS_API_TOKEN@ and @ARVADOS_API_HOST@ set correctly ("more info":api-tokens.html).
  45
  46 Test your function:
  47
  48 <pre>
  49 arvados=/path/to/arvados
  50 script_name=foo
  51 repo_path=/path/to/repo
  52
  53 read -rd $'\000' newjob <<EOF; $arvados/services/crunch/crunch-job --job "$newjob"
  54 {
  55  "script":"$script_name",
  56  "script_version":"$repo_path",
  57  "script_parameters":
  58  {
  59   "input":"..."
  60  }
  61 }
  62 EOF
  63 </pre>
  64
  65 The @--job@ argument to @crunch-job@ is the same as the @--job@ argument to @arv job create@, except:
  66
  67 <notextile><!--
  68 * @script_version@ can use "/" to indicate the working copy of a repository instead of a git commit or tag.
  69 --></notextile>
  70
  71 * node resource constraints are ignored.
  72
  73 You will see the progress of the job in your terminal.  Press Control-C to create a checkpoint and stop the job.
  74
  75 h3. Testing job scripts without SDKs and Keep access
  76
  77 Read and write data to @/tmp/@ instead of Keep. This only works with the Python SDK.
  78
  79 <pre>
  80 export KEEP_LOCAL_STORE=/tmp
  81 </pre>
  82
  83 Use the Perl SDK libraries directly from the arvados source tree.
  84
  85 <pre>
  86 export PERLLIB=/path/to/arvados/sdk/perl/lib
  87 </pre>