doc/user/tutorial-job-debug.textile

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Tutorial: Debug a crunch script"
   5 navorder: 13
   6 ---
   7
   8 h1. Tutorial: Debug a crunch script
   9
  10 The commit-push-submit cycle is too slow for developing and debugging crunch scripts.
  11
  12 Get quicker turnaround times by running jobs in your VM (rather than submitting to the job queue) using your working git tree (rather than committing and pushing every little change).
  13
  14 h3. Prerequisites
  15
  16 * Log in to a VM (see "Setting up SSH access":ssh-access.html)
  17 * Check out your git tree (see "Intro: git":intro-git.html)
  18 * Set up your API token environment variables (see "Getting an API token":api-tokens.html)
  19
  20 If everything is set up correctly, the command @arv -h user current@ will display your account information.
  21
  22 h3. Create a script
  23
  24 Change to your git repository working tree and make sure the @crunch_scripts@ directory exists.
  25
  26 <pre>
  27 yourname@shell:~$ cd yourrepo
  28 yourname@shell:~/yourrepo$ mkdir -p crunch_scripts
  29 </pre>
  30
  31 <!-- _Should mention somewhere that it *must* be in a directory called
  32 crunch_scripts_ -->
  33
  34 {% include notebox-begin.html %}
  35
  36 The process described here should work regardless of whether @yourrepo@ contains a git repository. But normally you would only ever edit code in a git tree -- especially crunch scripts, which can't be used to run regular Arvados jobs until they're committed and pushed.
  37
  38 {% include notebox-end.html %}
  39
  40
  41 Create a new crunch script called @hello-world@ (say, @edit crunch_scripts/hello-world@).
  42
  43 <pre>
  44 #!/usr/bin/env python
  45
  46 import arvados
  47
  48 print "hello world"
  49 </pre>
  50
  51 Save it.
  52
  53 h3. Run the job in your VM.
  54
  55 Instead of a git commit hash, we provide the path to the working copy in the _script_version_ parameter.
  56
  57 <pre>
  58 read -rd $'\000' the_job <<'EOF'; arv-crunch-job --job "$the_job"
  59 {
  60  "script":"bug-factory",
  61  "script_version":"/home/yourname/yourrepo"
  62 }
  63 EOF
  64 </pre>
  65
  66 You should see:
  67
  68 <pre>
  69 No script_parameters specified at arv-crunch-job line 156
  70 </pre>
  71
  72 Let's try again.
  73
  74 <pre>
  75 read -rd $'\000' the_job <<'EOF'; arv-crunch-job --job "$the_job"
  76 {
  77  "script":"hello-world",
  78  "script_version":"/home/yourname/yourrepo",
  79  "script_parameters":{}
  80 }
  81 EOF
  82 </pre>
  83
  84 You should see several attempts to run your script, each ending in tragedy:
  85
  86 <pre>
  87 2013-09-24_23:14:38 qr1hi-8i9sb-s1ngps1dznzrn8j 12311 0 stderr bash: /home/yourname/yourrepo/crunch_scripts/hello-world: Permission denied
  88 2013-09-24_23:14:38 qr1hi-8i9sb-s1ngps1dznzrn8j 12311 0 stderr bash: line 0: exec: /home/yourname/yourrepo/crunch_scripts/hello-world: cannot execute: Permission denied
  89 2013-09-24_23:14:38 qr1hi-8i9sb-s1ngps1dznzrn8j 12311 0 child 12323 on localhost.1 exit 32256 success=false
  90 2013-09-24_23:14:38 qr1hi-8i9sb-s1ngps1dznzrn8j 12311 0 failure in 1 seconds
  91 </pre>
  92
  93 Indeed, @hello-world@ is not executable. Fix it:
  94
  95 <pre>
  96 chmod +x crunch_scripts/hello-world
  97 </pre>
  98
  99 Try again.
 100
 101 This time, the job will still fail, but "hello world" will appear in the log.
 102
 103 <pre>
 104 2013-09-26_02:15:35 qr1hi-8i9sb-fbpcg2conrhnlxv 16179 0 job_task qr1hi-ot0gb-c3x9vcztahzdcol
 105 2013-09-26_02:15:35 qr1hi-8i9sb-fbpcg2conrhnlxv 16179 0 child 16249 started on localhost.1
 106 2013-09-26_02:15:36 qr1hi-8i9sb-fbpcg2conrhnlxv 16179  status: 0 done, 1 running, 0 todo
 107 2013-09-26_02:15:36 qr1hi-8i9sb-fbpcg2conrhnlxv 16179 0 stderr hello world
 108 2013-09-26_02:15:37 qr1hi-8i9sb-fbpcg2conrhnlxv 16179 0 child 16249 on localhost.1 exit 0 success=false
 109 2013-09-26_02:15:37 qr1hi-8i9sb-fbpcg2conrhnlxv 16179 0 failure in 1 seconds
 110 </pre>
 111
 112 There are two problems here:
 113
 114 1. The string "hello world" should be stored as the job's output instead of noted in the job log as "stderr".
 115 2. The task exited 0, but was recorded as a failure.
 116
 117 The job should work properly after we fix these two problems.
 118
 119 h3. Store output as a collection
 120
 121 Replace the @print "hello world"@ line with the following code.
 122
 123 <pre>
 124 out = arvados.CollectionWriter()
 125 out.set_current_file_name('hello.txt')
 126 out.write('hello world')
 127 out_collection = out.finish()
 128 </pre>
 129
 130 <!-- _Explain better_ -->
 131
 132 The return value of @out.finish()@ is the content address (hash) of a collection stored in Keep.
 133
 134 h3. Record successful completion
 135
 136 Append the following line.
 137
 138 <pre>
 139 arvados.current_task().set_output(out_collection)
 140 </pre>
 141
 142 The @set_output()@ method tells Arvados that
 143 * The hash specified by the @out_collection@ parameter is the output of this task, and
 144 * This task completed successfully.
 145
 146 <!-- _Putting this in a separate section from the code blob above is
 147 confusing!_ -->
 148
 149 h3. Run the working script.
 150
 151 <pre>
 152 read -rd $'\000' the_job <<'EOF'; arv-crunch-job --job "$the_job"
 153 {
 154  "script":"hello-world",
 155  "script_version":"/home/yourname/yourrepo",
 156  "script_parameters":{}
 157 }
 158 EOF
 159 </pre>
 160
 161 If everything worked correctly, the end of the log in your terminal should look like this.
 162
 163 <pre>
 164 2013-09-26_02:27:07 qr1hi-8i9sb-xsgms0qsf4ztm3l 17149  output dd202dc7b1297aa221c9160455ba43ac+61+K@qr1hi
 165 2013-09-26_02:27:08 qr1hi-8i9sb-xsgms0qsf4ztm3l 17149  finish
 166 2013-09-26_02:27:09 qr1hi-8i9sb-xsgms0qsf4ztm3l 17149  meta key is c186e6555b51ac6974d951cd2f387722+1764+K@qr1hi
 167 </pre>
 168