From eb4e579a713adf50a43238658b403b5b737e8f7f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C4=93teris=20Caune?= <cuu508@gmail.com>
Date: Tue, 25 Dec 2018 17:39:40 +0200
Subject: [PATCH] Update docs with the "/start" endpoint.

---
 hc/front/management/commands/pygmentize.py    |  1 +
 templates/front/details.html                  |  8 ++++
 templates/front/docs.html                     | 40 +++++++++++++++++--
 .../front/snippets/python_requests_start.html | 21 ++++++++++
 .../front/snippets/python_requests_start.txt  | 20 ++++++++++
 5 files changed, 86 insertions(+), 4 deletions(-)
 create mode 100644 templates/front/snippets/python_requests_start.html
 create mode 100644 templates/front/snippets/python_requests_start.txt

diff --git a/hc/front/management/commands/pygmentize.py b/hc/front/management/commands/pygmentize.py
index 5af2eb8e..350c62f3 100644
--- a/hc/front/management/commands/pygmentize.py
+++ b/hc/front/management/commands/pygmentize.py
@@ -36,6 +36,7 @@ class Command(BaseCommand):
         _process("python_urllib2", lexers.PythonLexer())
         _process("python_requests", lexers.PythonLexer())
         _process("python_requests_fail", lexers.PythonLexer())
+        _process("python_requests_start", lexers.PythonLexer())
         _process("python_requests_payload", lexers.PythonLexer())
         _process("php", lexers.PhpLexer())
         _process("powershell", lexers.shell.PowerShellLexer())
diff --git a/templates/front/details.html b/templates/front/details.html
index ecbfe18a..27999658 100644
--- a/templates/front/details.html
+++ b/templates/front/details.html
@@ -35,6 +35,14 @@
                 <code>{{ check.url }}</code>
                 <p>Or by sending emails to this address:</p>
                 <code>{{ check.email }}</code>
+
+                <p>You can also explictly
+                    <a href="{% url 'hc-docs' %}#fail-event">
+                        signal a failure</a>
+                    and
+                    <a href="{% url 'hc-docs' %}#start-event">
+                        measure job execution time</a>.
+                </p>
             </div>
             <div class="text-right">
                 <button
diff --git a/templates/front/docs.html b/templates/front/docs.html
index bf90b936..48918bf8 100644
--- a/templates/front/docs.html
+++ b/templates/front/docs.html
@@ -29,7 +29,7 @@ if still no ping, sends you an alert.</p>
 alerts. As soon as it fails to check in on time, you get notified.
 It is a simple idea.</p>
 
-<h2 class="rule">Executing a Ping</h2>
+<h2 class="rule">Signalling a Success</h2>
 
 <p>
     At the end of your batch job, add a bit of code to request
@@ -51,6 +51,7 @@ It is a simple idea.</p>
 <p>The response will have status code "200 OK" and response body will be a
 short and simple string "OK".</p>
 
+<a name="fail-event"></a>
 <h2 class="rule">Signalling a Failure</h2>
 <p>
     Append <code>/fail</code> to a ping URL and use it to actively signal a
@@ -63,6 +64,25 @@ work function returns an unexpected value or throws an exception:</p>
 
 {% include "front/snippets/python_requests_fail.html" %}
 
+<a name="start-event"></a>
+<h2 class="rule">Measuring Job Execution Time</h2>
+<p>
+    Append <code>/start</code> to a ping URL and use it to signal
+    when a job starts. After receiving a start signal, {% site_name %}
+    will show the check as "Started". It will store the "start" events and
+    display the job execution times. The job execution times are calculated as the time
+    gaps between adjacent "start" and "complete" events.
+</p>
+<p>
+    Signalling a start kicks off a separate timer: the job
+    now <strong>must</strong> signal a success within its configured
+    "Grace Time", or it will get marked as "down".
+</p>
+
+<p>Below is a code example in Python:</p>
+
+{% include "front/snippets/python_requests_start.html" %}
+
 <h2 class="rule">Examples</h2>
 
 <p>
@@ -292,6 +312,15 @@ using the "-command" argument:</p>
             You can resume monitoring of a paused check by pinging it.
         </td>
     </tr>
+    <tr>
+        <td>
+            <span class="status icon-started"></span>
+        </td>
+        <td>
+            <strong>Started.</strong>
+            The check has received a "start" signal, and is currently running.
+        </td>
+    </tr>
     <tr>
         <td>
             <span class="status icon-up"></span>
@@ -316,10 +345,13 @@ using the "-command" argument:</p>
             <span class="status icon-down"></span>
         </td>
         <td>
-            <strong>Down.</strong>
-            Time since last ping has exceeded <strong>Period</strong> + <strong>Grace</strong>.
-            When check goes from "Late" to "Down", {% site_name %}
+            <p><strong>Down.</strong> The check has not received a "success"
+                ping in time, or it has received an explicit "fail" signal.
+            </p>
+            <p>
+            When a check goes into the "Down" state, {% site_name %}
             sends you an alert.
+            </p>
         </td>
     </tr>
 </table>
diff --git a/templates/front/snippets/python_requests_start.html b/templates/front/snippets/python_requests_start.html
new file mode 100644
index 00000000..0447ee3f
--- /dev/null
+++ b/templates/front/snippets/python_requests_start.html
@@ -0,0 +1,21 @@
+<div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">requests</span>
+<span class="n">URL</span> <span class="o">=</span> <span class="s2">&quot;{{ ping_url }}&quot;</span>
+
+
+<span class="c1"># &quot;/start&quot; kicks off a timer: if the job takes longer than</span>
+<span class="c1"># the configured grace time, the check will be marked as &quot;down&quot;</span>
+<span class="k">try</span><span class="p">:</span>
+    <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">URL</span> <span class="o">+</span> <span class="s2">&quot;/start&quot;</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
+<span class="k">except</span> <span class="n">requests</span><span class="o">.</span><span class="n">exceptions</span><span class="o">.</span><span class="n">RequestException</span><span class="p">:</span>
+    <span class="c1"># If the network request fails for any reason, we don&#39;t want</span>
+    <span class="c1"># it to prevent the main job from running</span>
+    <span class="k">pass</span>
+
+
+<span class="c1"># TODO: run the job here</span>
+<span class="n">fib</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">n</span><span class="p">:</span> <span class="n">n</span> <span class="k">if</span> <span class="n">n</span> <span class="o">&lt;</span> <span class="mi">2</span> <span class="k">else</span> <span class="n">fib</span><span class="p">(</span><span class="n">n</span> <span class="o">-</span> <span class="mi">1</span><span class="p">)</span> <span class="o">+</span> <span class="n">fib</span><span class="p">(</span><span class="n">n</span> <span class="o">-</span> <span class="mi">2</span><span class="p">)</span>
+<span class="k">print</span><span class="p">(</span><span class="s2">&quot;F(42) = </span><span class="si">%d</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="n">fib</span><span class="p">(</span><span class="mi">42</span><span class="p">))</span>
+
+<span class="c1"># Signal success:</span>
+<span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">URL</span><span class="p">)</span>
+</pre></div>
diff --git a/templates/front/snippets/python_requests_start.txt b/templates/front/snippets/python_requests_start.txt
new file mode 100644
index 00000000..203f8efa
--- /dev/null
+++ b/templates/front/snippets/python_requests_start.txt
@@ -0,0 +1,20 @@
+import requests
+URL = "PING_URL"
+
+
+# "/start" kicks off a timer: if the job takes longer than
+# the configured grace time, the check will be marked as "down"
+try:
+    requests.get(URL + "/start", timeout=5)
+except requests.exceptions.RequestException:
+    # If the network request fails for any reason, we don't want
+    # it to prevent the main job from running
+    pass
+
+
+# TODO: run the job here
+fib = lambda n: n if n < 2 else fib(n - 1) + fib(n - 2)
+print("F(42) = %d" % fib(42))
+
+# Signal success:
+requests.get(URL)