From 2dd40eb4e4b865b3769dae8eef6d0fe0a3feac68 Mon Sep 17 00:00:00 2001
From: Stuart McLean <stuart.mclean@liquidm.com>
Date: Mon, 14 May 2018 20:50:08 +0200
Subject: [PATCH 1/3] improve alerting api docs sample responses

---
 docs/sources/http_api/alerting.md | 53 +++++++++++++++++++++----------
 1 file changed, 36 insertions(+), 17 deletions(-)

diff --git a/docs/sources/http_api/alerting.md b/docs/sources/http_api/alerting.md
index 3860ae490b1..305bfccebe8 100644
--- a/docs/sources/http_api/alerting.md
+++ b/docs/sources/http_api/alerting.md
@@ -50,19 +50,16 @@ Content-Type: application/json
     "id": 1,
     "dashboardId": 1,
     "panelId": 1,
+    "panelUId": "ABcdEFghij"
+    "dashboardSlug": "sensors",
     "name": "fire place sensor",
     "message": "Someone is trying to break in through the fire place",
     "state": "alerting",
+    "newStateDate": "2018-05-14T05:55:20+02:00",
     "evalDate": "0001-01-01T00:00:00Z",
-    "evalData": [
-      {
-        "metric": "fire",
-        "tags": null,
-        "value": 5.349999999999999
-      }
-    "newStateDate": "2016-12-25",
+    "evalData": null,
     "executionError": "",
-    "url": "http://grafana.com/dashboard/db/sensors"
+    "dashboardUri": "http://grafana.com/dashboard/db/sensors"
   }
 ]
 ```
@@ -86,15 +83,37 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 HTTP/1.1 200
 Content-Type: application/json
 {
-  "id": 1,
-  "dashboardId": 1,
-  "panelId": 1,
-  "name": "fire place sensor",
-  "message": "Someone is trying to break in through the fire place",
-  "state": "alerting",
-  "newStateDate": "2016-12-25",
-  "executionError": "",
-  "url": "http://grafana.com/dashboard/db/sensors"
+  "Id": 1,
+  "Version": 0,
+  "OrgId": 1,
+  "DashboardId": 55,
+  "PanelId": 2,
+  "Name": "my mem alert",
+  "Message": "",
+  "Severity": "",
+  "State": "alerting",
+  "Handler": 1,
+  "Silenced": false,
+  "ExecutionError": " ",
+  "Frequency": 60,
+  "EvalData": {
+    "evalMatches": [
+      {
+        "metric": "mem_usage",
+        "tags": {
+          "name": "server.grafana.com"
+        },
+        "value": 98.765
+      }
+    ]
+  },
+  "NewStateDate": "2018-05-14T17:12:45+02:00",
+  "StateChanges": 3,
+  "Created": "2018-05-14T17:01:25+02:00",
+  "Updated": "2018-05-14T17:11:18+02:00",
+  "Settings": {
+    ...
+  }
 }
 ```
 

From 295169b94f79af4d8316b9cc3a193fce0706a772 Mon Sep 17 00:00:00 2001
From: Stuart McLean <stuart.mclean@liquidm.com>
Date: Mon, 14 May 2018 20:50:44 +0200
Subject: [PATCH 2/3] add useful note to alerting api docs

---
 docs/sources/http_api/alerting.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/sources/http_api/alerting.md b/docs/sources/http_api/alerting.md
index 305bfccebe8..3b9eceddd5e 100644
--- a/docs/sources/http_api/alerting.md
+++ b/docs/sources/http_api/alerting.md
@@ -117,6 +117,13 @@ Content-Type: application/json
 }
 ```
 
+**Important Note**:
+"evalMatches" data is cached in the db when and only when the state of the alert changes
+(e.g. transitioning from "ok" to "alerting" state).
+
+If data from one server triggers the alert first and, before that server is seen leaving alerting state,
+a second server also enters a state that would trigger the alert, the second server will not be visible in "evalMatches" data.
+
 ## Pause alert
 
 `POST /api/alerts/:id/pause`

From c09c00a1f5eacf6d06e57d1c4d4fe001861e182e Mon Sep 17 00:00:00 2001
From: Stuart McLean <stuart.mclean@liquidm.com>
Date: Tue, 15 May 2018 10:06:26 +0200
Subject: [PATCH 3/3] fixes following first code review

---
 docs/sources/http_api/alerting.md | 60 +++++++++++++------------------
 1 file changed, 25 insertions(+), 35 deletions(-)

diff --git a/docs/sources/http_api/alerting.md b/docs/sources/http_api/alerting.md
index 3b9eceddd5e..4d52105cf3c 100644
--- a/docs/sources/http_api/alerting.md
+++ b/docs/sources/http_api/alerting.md
@@ -49,17 +49,17 @@ Content-Type: application/json
   {
     "id": 1,
     "dashboardId": 1,
-    "panelId": 1,
-    "panelUId": "ABcdEFghij"
+    "dashboardUId": "ABcdEFghij"
     "dashboardSlug": "sensors",
+    "panelId": 1,
     "name": "fire place sensor",
-    "message": "Someone is trying to break in through the fire place",
     "state": "alerting",
+    "message": "Someone is trying to break in through the fire place",
     "newStateDate": "2018-05-14T05:55:20+02:00",
     "evalDate": "0001-01-01T00:00:00Z",
     "evalData": null,
     "executionError": "",
-    "dashboardUri": "http://grafana.com/dashboard/db/sensors"
+    "url": "http://grafana.com/dashboard/db/sensors"
   }
 ]
 ```
@@ -83,37 +83,27 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 HTTP/1.1 200
 Content-Type: application/json
 {
-  "Id": 1,
-  "Version": 0,
-  "OrgId": 1,
-  "DashboardId": 55,
-  "PanelId": 2,
-  "Name": "my mem alert",
-  "Message": "",
-  "Severity": "",
-  "State": "alerting",
-  "Handler": 1,
-  "Silenced": false,
-  "ExecutionError": " ",
-  "Frequency": 60,
-  "EvalData": {
-    "evalMatches": [
-      {
-        "metric": "mem_usage",
-        "tags": {
-          "name": "server.grafana.com"
-        },
-        "value": 98.765
-      }
-    ]
-  },
-  "NewStateDate": "2018-05-14T17:12:45+02:00",
-  "StateChanges": 3,
-  "Created": "2018-05-14T17:01:25+02:00",
-  "Updated": "2018-05-14T17:11:18+02:00",
-  "Settings": {
-    ...
-  }
+  "id": 1,
+  "dashboardId": 1,
+  "dashboardUId": "ABcdEFghij"
+  "dashboardSlug": "sensors",
+  "panelId": 1,
+  "name": "fire place sensor",
+  "state": "alerting",
+  "message": "Someone is trying to break in through the fire place",
+  "newStateDate": "2018-05-14T05:55:20+02:00",
+  "evalDate": "0001-01-01T00:00:00Z",
+  "evalData": "evalMatches": [
+    {
+      "metric": "movement",
+      "tags": {
+        "name": "fireplace_chimney"
+      },
+      "value": 98.765
+    }
+  ],
+  "executionError": "",
+  "url": "http://grafana.com/dashboard/db/sensors"
 }
 ```