docs/frontends/download-status.rst

   1 .. -*- coding: utf-8-with-signature -*-
   2
   3 ===============
   4 Download status
   5 ===============
   6
   7
   8 Introduction
   9 ============
  10
  11 The WUI will display the "status" of uploads and downloads.
  12
  13 The Welcome Page has a link entitled "Recent Uploads and Downloads"
  14 which goes to this URL:
  15
  16 http://$GATEWAY/status
  17
  18 Each entry in the list of recent operations has a "status" link which
  19 will take you to a page describing that operation.
  20
  21 For immutable downloads, the page has a lot of information, and this
  22 document is to explain what it all means. It was written by Brian
  23 Warner, who wrote the v1.8.0 downloader code and the code which
  24 generates this status report about the v1.8.0 downloader's
  25 behavior. Brian posted it to the trac:
  26 https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1169#comment:1
  27
  28 Then Zooko lightly edited it while copying it into the docs/
  29 directory.
  30
  31 What's involved in a download?
  32 ==============================
  33
  34 Downloads are triggered by read() calls, each with a starting offset (defaults
  35 to 0) and a length (defaults to the whole file). A regular web-API GET request
  36 will result in a whole-file read() call.
  37
  38 Each read() call turns into an ordered sequence of get_segment() calls. A
  39 whole-file read will fetch all segments, in order, but partial reads or
  40 multiple simultaneous reads will result in random-access of segments. Segment
  41 reads always return ciphertext: the layer above that (in read()) is responsible
  42 for decryption.
  43
  44 Before we can satisfy any segment reads, we need to find some shares. ("DYHB"
  45 is an abbreviation for "Do You Have Block", and is the message we send to
  46 storage servers to ask them if they have any shares for us. The name is
  47 historical, from Mojo Nation/Mnet/Mountain View, but nicely distinctive.
  48 Tahoe-LAFS's actual message name is remote_get_buckets().). Responses come
  49 back eventually, or don't.
  50
  51 Once we get enough positive DYHB responses, we have enough shares to start
  52 downloading. We send "block requests" for various pieces of the share.
  53 Responses come back eventually, or don't.
  54
  55 When we get enough block-request responses for a given segment, we can decode
  56 the data and satisfy the segment read.
  57
  58 When the segment read completes, some or all of the segment data is used to
  59 satisfy the read() call (if the read call started or ended in the middle of a
  60 segment, we'll only use part of the data, otherwise we'll use all of it).
  61
  62 Data on the download-status page
  63 ================================
  64
  65 DYHB Requests
  66 -------------
  67
  68 This shows every Do-You-Have-Block query sent to storage servers and their
  69 results. Each line shows the following:
  70
  71 * the serverid to which the request was sent
  72 * the time at which the request was sent. Note that all timestamps are
  73   relative to the start of the first read() call and indicated with a "+" sign
  74 * the time at which the response was received (if ever)
  75 * the share numbers that the server has, if any
  76 * the elapsed time taken by the request
  77
  78 Also, each line is colored according to the serverid. This color is also used
  79 in the "Requests" section below.
  80
  81 Read Events
  82 -----------
  83
  84 This shows all the FileNode read() calls and their overall results. Each line
  85 shows:
  86
  87 * the range of the file that was requested (as [OFFSET:+LENGTH]). A whole-file
  88   GET will start at 0 and read the entire file.
  89 * the time at which the read() was made
  90 * the time at which the request finished, either because the last byte of data
  91   was returned to the read() caller, or because they cancelled the read by
  92   calling stopProducing (i.e. closing the HTTP connection)
  93 * the number of bytes returned to the caller so far
  94 * the time spent on the read, so far
  95 * the total time spent in AES decryption
  96 * total time spend paused by the client (pauseProducing), generally because the
  97   HTTP connection filled up, which most streaming media players will do to
  98   limit how much data they have to buffer
  99 * effective speed of the read(), not including paused time
 100
 101 Segment Events
 102 --------------
 103
 104 This shows each get_segment() call and its resolution. This table is not well
 105 organized, and my post-1.8.0 work will clean it up a lot. In its present form,
 106 it records "request" and "delivery" events separately, indicated by the "type"
 107 column.
 108
 109 Each request shows the segment number being requested and the time at which the
 110 get_segment() call was made.
 111
 112 Each delivery shows:
 113
 114 * segment number
 115 * range of file data (as [OFFSET:+SIZE]) delivered
 116 * elapsed time spent doing ZFEC decoding
 117 * overall elapsed time fetching the segment
 118 * effective speed of the segment fetch
 119
 120 Requests
 121 --------
 122
 123 This shows every block-request sent to the storage servers. Each line shows:
 124
 125 * the server to which the request was sent
 126 * which share number it is referencing
 127 * the portion of the share data being requested (as [OFFSET:+SIZE])
 128 * the time the request was sent
 129 * the time the response was received (if ever)
 130 * the amount of data that was received (which might be less than SIZE if we
 131   tried to read off the end of the share)
 132 * the elapsed time for the request (RTT=Round-Trip-Time)
 133
 134 Also note that each Request line is colored according to the serverid it was
 135 sent to. And all timestamps are shown relative to the start of the first
 136 read() call: for example the first DYHB message was sent at +0.001393s about
 137 1.4 milliseconds after the read() call started everything off.