doc/user/tutorial-job1.textile

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Tutorial: Your first job"
   5 navorder: 20
   6 ---
   7
   8 h1. Tutorial: Your first job
   9
  10 Here you will use the "arv" command line tool to run a simple Crunch script on some sample data.
  11
  12 h3. Prerequisites
  13
  14 _Needs a mention of going to Access->VMs on the workbench_
  15
  16 * Log in to a VM "using SSH":ssh-access.html
  17 * Put an "API token":api-tokens.html in your @ARVADOS_API_TOKEN@ environment variable
  18 * Put the API host name in your @ARVADOS_API_HOST@ environment variable
  19
  20 If everything is set up correctly, the command @arv -h user current@ will display your account information.
  21
  22
  23 _If you are logged in to a fully provisioned VM, presumably the gems
  24 are already installed.  This discussion should go somewhere else._
  25
  26 Arv depends on a few gems. It will tell you which ones to install, if they are not present yet. If you need to install the dependencies and are doing so as a non-root user, make sure you set GEM_HOME before you run gem install:
  27
  28 <pre>
  29     export GEM_HOME=~/.gem
  30 </pre>
  31
  32 h3. Submit a job
  33
  34 We will run the "hash" program, which computes the MD5 hash of each file in a collection.
  35
  36 Pick a data collection. We'll use @33a9f3842b01ea3fdf27cc582f5ea2af@ here.
  37
  38 _How do I know if I have this data?  Does it come as example data with
  39 the arvados distribution?  Is there something notable about it, like
  40 it is very large and spans multiple keep blocks?_
  41
  42 <pre>
  43 the_collection=33a9f3842b01ea3fdf27cc582f5ea2af
  44 </pre>
  45
  46 Pick a code version. We'll use @5565778cf15ae9af22ad392053430213e9016631@ here.
  47
  48 _How do I know if I have this code version?  What does this refer to?
  49 A git revision?  Or a keep id?  In what repository?_
  50
  51 <pre>
  52 the_version=5565778cf15ae9af22ad392053430213e9016631
  53 </pre>
  54
  55 Make a JSON object describing the job.
  56
  57 <pre>
  58 read -rd $'\000' the_job <<EOF
  59 {
  60  "script":"hash",
  61  "script_version":"$the_version",
  62  "script_parameters":
  63  {
  64   "input":"$the_collection"
  65  }
  66 }
  67 EOF
  68 </pre>
  69
  70 _Need to explain what the json fields mean, it is explained later but
  71 there should be some mention up here._
  72
  73 (The @read -rd $'\000'@ part uses a bash feature to help us get a
  74 multi-line string with lots of double quotation marks into a shell
  75 variable.)
  76
  77 Submit the job.
  78
  79 <pre>
  80 arv -h job create --job "$the_job"
  81 </pre>
  82
  83 &darr;
  84
  85 <pre>
  86 {
  87  "kind":"arvados#job",
  88  "etag":"dwbrasqcozpjsqtfshzdjfiii",
  89  "uuid":"qr1hi-8i9sb-3i0yi357k0mauwz",
  90 ...
  91  "script":"hash",
  92  "script_parameters":{
  93   "input":"33a9f3842b01ea3fdf27cc582f5ea2af"
  94  },
  95  "script_version":"5565778cf15ae9af22ad392053430213e9016631",
  96 ...
  97 }
  98 </pre>
  99
 100 _What is this?  An example of what "arv" returns?  What do the fields mean?_
 101
 102 h3. Monitor job progress
 103
 104 _And then the magic happens.  There should be some more discussion of what
 105 is going on in the background once the job is submitted from the
 106 user's perspective.  It is queued, running, etc?._
 107
 108 Go to Workbench, drop down the Compute menu, and click Jobs. The job you submitted should appear at the top of the list.
 109
 110 Hit "Refresh" until it finishes.  _We should really make the page
 111 autorefresh or use a streamed-update framework_
 112
 113 You can also watch the log messages while the job runs:
 114
 115 <pre>
 116 curl -s -H "Authorization: OAuth2 $ARVADOS_API_TOKEN" \
 117   "https://$ARVADOS_API_HOST/arvados/v1/jobs/JOB_UUID_HERE/log_tail_follow"
 118 </pre>
 119
 120 This will run until the job finishes or you hit control-C.
 121
 122 If you're running more than one job today, you can watch log messages from all of them in one stream:
 123
 124 <pre>
 125 my_user_uuid=`arv user current`
 126 curl -s -H "Authorization: OAuth2 $ARVADOS_API_TOKEN" \
 127   "https://$ARVADOS_API_HOST/arvados/v1/users/$my_user_uuid/event_stream"
 128 </pre>
 129
 130 This will run until you hit control-C.
 131
 132 h3. Inspect the job output
 133
 134 Find the output of the job by looking at the Jobs page (in the Compute menu) in Workbench, or by using the API:
 135
 136 <pre>
 137 arv -h job get --uuid JOB_UUID_HERE
 138 </pre>
 139
 140 The output locator will look like <code>5894dfae5d6d8edf135f0ea3dba849c2+62+K@qr1hi</code>.
 141
 142 List the files in the collection:
 143
 144 <pre>
 145 arv keep ls 5894dfae5d6d8edf135f0ea3dba849c2+62+K@qr1hi
 146 </pre>
 147
 148 &darr;
 149
 150 <pre>
 151 md5sum.txt
 152 </pre>
 153
 154 Show the contents of the md5sum.txt file:
 155
 156 <pre>
 157 arv keep less 5894dfae5d6d8edf135f0ea3dba849c2+62+K@qr1hi/md5sum.txt
 158 </pre>
 159
 160 h3. Inspect the code
 161
 162 The @script@ and @script_version@ attributes of a Job allow you to confirm the code that was used to run the job. Specifically, @script@ refers to a file in the @/crunch_scripts@ directory in the tree indicated by the commit hash @script_version@.
 163
 164 Example:
 165
 166 <pre>
 167 cd
 168 git clone git://github.com/clinicalfuture/arvados.git
 169 cd arvados
 170 git checkout $the_version
 171 less crunch_scripts/hash
 172 </pre>
 173
 174 _If we're going to direct the user to open up the code, some
 175 discussion of the python API is probably in order.  If the hash
 176 job is going to be the canonical first crunch map reduce program
 177 for everybody, than we should break down the program line-by-line and
 178 explain every step in detail._