doc/user/reference/intro-jobs.textile

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Reference: Jobs"
   5 navorder: 323
   6 ---
   7
   8 h1. Reference: 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 <!-- _Need to define MapReduce_ -->
  13
  14 Crunch jobs offer several advantages over running programs on your own local machine:
  15
  16 <!-- _This underplays it a bit, I would say it offers many, significanty
  17 advantages, not just "several"_ -->
  18
  19 * 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).
  20
  21 * 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.
  22
  23 * Ensure that your programs and workflows are repeatable with different versions of your code, OS updates, etc.
  24
  25 * Interrupt and resume long-running jobs consisting of many short tasks.
  26
  27 * Maintain timing statistics automatically, so they're there when you want them.
  28
  29 h3. Structure of a job
  30
  31 A job consists of a number of tasks which can be executed asynchronously.
  32
  33 A single job program, or "crunch script", executes each task of a given job. The logic of a typical crunch script looks like this:
  34
  35 <!-- _This discussion of the structure of a job seems to miss the mark,
  36 it's both too detailed for an introdction but not detailed enough to
  37 be able to make use of the knowledge_ -->
  38
  39 * 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.
  40
  41 * 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.
  42
  43 When all job tasks have completed, the output fragments are assembled into a single output manifest.
  44
  45 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.
  46
  47 h3. Developing and testing crunch scripts
  48
  49 <!-- _This seems like it should go in the tutorial section_ -->
  50
  51 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.
  52
  53 <!-- _I'm confused.  Is this example for running locally or running
  54 remotely on arvados?_ -->
  55
  56 Save your job script (say, @foo@) in @{git-repo}/crunch_scripts/foo@.
  57
  58 Make sure you have @ARVADOS_API_TOKEN@ and @ARVADOS_API_HOST@ set correctly ("more info":api-tokens.html).
  59
  60 Test your function:
  61
  62 <pre>
  63 script_name=foo
  64 repo_path=/path/to/repo
  65
  66 read -rd $'\000' newjob <<EOF; arv-crunch-job --job "$newjob"
  67 {
  68  "script":"$script_name",
  69  "script_version":"$repo_path",
  70  "script_parameters":
  71  {
  72   "input":"..."
  73  }
  74 }
  75 EOF
  76 </pre>
  77
  78 The @--job@ argument to @arv-crunch-job@ is the same as the @--job@ argument to @arv job create@, except:
  79
  80 * @script_version@ can be the full path to a local working tree, instead of a git commit/branch/tag.
  81
  82 * @runtime_constraints@ are ignored.
  83
  84 You will see the progress of the job in your terminal.  Press Control-C to create a checkpoint and stop the job.
  85
  86 h3. Location of temporary files
  87
  88 Crunch job tasks are supplied with @TASK_WORK@ and @JOB_WORK@ environment variables, to be used as scratch space. When running in local development mode, Crunch puts these in a directory called @crunch-job-{USERID}@ in @TMPDIR@ (or @/tmp@ if @TMPDIR@ is not set).
  89
  90 * Set @TMPDIR@ to @/scratch@ to make Crunch use a directory like @/scratch/crunch-job-{USERID}/@ for temporary space.
  91
  92 * Set @CRUNCH_TMP@ to @/scratch/foo@ to make Crunch use @/scratch/foo/@ for temporary space (omitting its customary @crunch-job-{USERID}@ part)
  93
  94 h3. Testing job scripts without SDKs and Keep access
  95
  96 Read and write data to @/tmp/@ instead of Keep. This only works with the Python SDK.
  97
  98 <pre>
  99 export KEEP_LOCAL_STORE=/tmp
 100 </pre>
 101
 102 Use the Perl SDK libraries directly from the arvados source tree.
 103
 104 <pre>
 105 export PERLLIB=/path/to/arvados/sdk/perl/lib
 106 </pre>