doc/user/tutorial-job-debug.textile

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