doc/user/tutorial-job-debug.textile

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Tutorial 3: Debug a crunch script"
   5 navorder: 13
   6 ---
   7
   8 h1. Tutorial 3: 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 crunch_scripts_
  32
  33 {% include notebox-begin.html %}
  34
  35 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.
  36
  37 {% include notebox-end.html %}
  38
  39
  40 Create a new crunch script called @hello-world@ (say, @edit crunch_scripts/hello-world@).
  41
  42 <pre>
  43 #!/usr/bin/env python
  44
  45 import arvados
  46
  47 print "hello world"
  48 </pre>
  49
  50 Save it.
  51
  52 h3. Run the job in your VM.
  53
  54 Instead of a git commit hash, we provide the path to the working copy in the _script_version_ parameter.
  55
  56 <pre>
  57 read -rd $'\000' the_job <<'EOF'; arv-crunch-job --job "$the_job"
  58 {
  59  "script":"bug-factory",
  60  "script_version":"/home/yourname/yourrepo"
  61 }
  62 EOF
  63 </pre>
  64
  65 You should see:
  66
  67 <pre>
  68 No script_parameters specified at arv-crunch-job line 156
  69 </pre>
  70
  71 Let's try again.
  72
  73 <pre>
  74 read -rd $'\000' the_job <<'EOF'; arv-crunch-job --job "$the_job"
  75 {
  76  "script":"hello-world",
  77  "script_version":"/home/yourname/yourrepo",
  78  "script_parameters":{}
  79 }
  80 EOF
  81 </pre>
  82
  83 You should see several attempts to run your script, each ending in tragedy:
  84
  85 <pre>
  86 2013-09-24_23:14:38 qr1hi-8i9sb-s1ngps1dznzrn8j 12311 0 stderr bash: /home/yourname/yourrepo/crunch_scripts/hello-world: Permission denied
  87 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
  88 2013-09-24_23:14:38 qr1hi-8i9sb-s1ngps1dznzrn8j 12311 0 child 12323 on localhost.1 exit 32256 success=false
  89 2013-09-24_23:14:38 qr1hi-8i9sb-s1ngps1dznzrn8j 12311 0 failure in 1 seconds
  90 </pre>
  91
  92 Indeed, @hello-world@ is not executable. Fix it:
  93
  94 <pre>
  95 chmod +x crunch_scripts/hello-world
  96 </pre>
  97
  98 Try again.
  99
 100 This time, the job will still fail, but "hello world" will appear in the log.
 101
 102 <pre>
 103 2013-09-26_02:15:35 qr1hi-8i9sb-fbpcg2conrhnlxv 16179 0 job_task qr1hi-ot0gb-c3x9vcztahzdcol
 104 2013-09-26_02:15:35 qr1hi-8i9sb-fbpcg2conrhnlxv 16179 0 child 16249 started on localhost.1
 105 2013-09-26_02:15:36 qr1hi-8i9sb-fbpcg2conrhnlxv 16179  status: 0 done, 1 running, 0 todo
 106 2013-09-26_02:15:36 qr1hi-8i9sb-fbpcg2conrhnlxv 16179 0 stderr hello world
 107 2013-09-26_02:15:37 qr1hi-8i9sb-fbpcg2conrhnlxv 16179 0 child 16249 on localhost.1 exit 0 success=false
 108 2013-09-26_02:15:37 qr1hi-8i9sb-fbpcg2conrhnlxv 16179 0 failure in 1 seconds
 109 </pre>
 110
 111 There are two problems here:
 112
 113 1. The string "hello world" should be stored as the job's output instead of noted in the job log as "stderr".
 114 2. The task exited 0, but was recorded as a failure.
 115
 116 The job should work properly after we fix these two problems.
 117
 118 h3. Store output as a collection
 119
 120 Replace the @print "hello world"@ line with the following code.
 121
 122 <pre>
 123 out = arvados.CollectionWriter()
 124 out.set_current_file_name('hello.txt')
 125 out.write('hello world')
 126 out_collection = out.finish()
 127 </pre>
 128
 129 _Explain better_
 130
 131 The return value of @out.finish()@ is the content address (hash) of a collection stored in Keep.
 132
 133 h3. Record successful completion
 134
 135 Append the following line.
 136
 137 <pre>
 138 arvados.current_task().set_output(out_collection)
 139 </pre>
 140
 141 The @set_output()@ method tells Arvados that
 142 * The hash specified by the @out_collection@ parameter is the output of this task, and
 143 * This task completed successfully.
 144
 145 _Putting this in a separate section from the code blob above is confusing!_
 146
 147 h3. Run the working script.
 148
 149 <pre>
 150 read -rd $'\000' the_job <<'EOF'; arv-crunch-job --job "$the_job"
 151 {
 152  "script":"hello-world",
 153  "script_version":"/home/yourname/yourrepo",
 154  "script_parameters":{}
 155 }
 156 EOF
 157 </pre>
 158
 159 If everything worked correctly, the end of the log in your terminal should look like this.
 160
 161 <pre>
 162 2013-09-26_02:27:07 qr1hi-8i9sb-xsgms0qsf4ztm3l 17149  output dd202dc7b1297aa221c9160455ba43ac+61+K@qr1hi
 163 2013-09-26_02:27:08 qr1hi-8i9sb-xsgms0qsf4ztm3l 17149  finish
 164 2013-09-26_02:27:09 qr1hi-8i9sb-xsgms0qsf4ztm3l 17149  meta key is c186e6555b51ac6974d951cd2f387722+1764+K@qr1hi
 165 </pre>
 166