From 42ff86416c2907aba95a728795728aae37bf53fe Mon Sep 17 00:00:00 2001 From: Chris Goller Date: Tue, 6 Dec 2016 11:10:26 -0600 Subject: [PATCH] Update dashboard design to be simple queries --- docs/dashboards.md | 226 +++++++++++++++++++++++++++++---------------- 1 file changed, 148 insertions(+), 78 deletions(-) diff --git a/docs/dashboards.md b/docs/dashboards.md index eb1b7c873..2ae86a327 100644 --- a/docs/dashboards.md +++ b/docs/dashboards.md @@ -1,52 +1,57 @@ ## Dashboard API -### Visualization Metadata -Currently, we don't know all features we want in the dashboard visualization. So, we'll hand-wave over that until we are actually creating the dashboards. We'll keep the codebase agile enough to add in visualization metadata as we need 'em. - ### TL; DR -Here are the objects we are thinking about; dashboards contain layouts which contain explorations. +Here are the objects we are thinking about; dashboards contain layouts which +contain explorations. #### Dashboard + ```json { "links": { "self": "/chronograf/v1/dashboards/myid" }, "id": "myid", - "layouts": [ - "/chronograf/v1/layouts/a", - "/chronograf/v1/layouts/b" + "queries": [ + { + "x": 0, + "y": 0, + "w": 2, + "h": 1, + "label": "Objects/Second", + "range": { + "upper": 100, + "lower": 10 + }, + "link": "/chronograf/v1/queries/1" + }, + { + "x": 2, + "y": 0, + "w": 2, + "h": 1, + "label": "Widgets/Second", + "range": { + "upper": 10, + "lower": 0 + }, + "link": "/chronograf/v1/queries/2" + } ], "name": "This is my dashboard", - ... visualization metadata here ... } ``` -#### Layout -(Notice that we added explorations in the cell object) -```json -{ - "id": "6dfb4d49-20dc-4157-9018-2b1b1cb75c2d", - "dashboards" :[ - "/chronograf/v1/dashboards/myid" - ], - "cells": [ - { - "visualization": "graph", - "name": "Apache Bytes/Second", - "exploration": "/chronograf/v1/explorations/1" - } - ] -} -``` - -#### Exploration -This is the same object we currently use for explorations. +#### Query ```json { - "name": "my exploration", - "data":{} + "query": "SELECT mean(n_cpu) from cpu GROUP BY time(15m)", + "db": "telegraf", + "rp": "", + "links" : { + "self": "/chronograf/v1/queries/1" + } } ``` @@ -59,30 +64,74 @@ Returns a list of dashboards ```json { - "dashboards": [ - { - "links": { - "self": "/chronograf/v1/dashboards/myid" - }, - "id": "myid", - "layouts": [ - "/chronograf/v1/layouts/a", - "/chronograf/v1/layouts/b" - ], - "name": "This is my dashboard", - }, - { - "links": { - "self": "/chronograf/v1/dashboards/myother" - }, - "id": "myother", - "layouts": [ - "/chronograf/v1/layouts/b", - "/chronograf/v1/layouts/c" - ], - "name": "This is my other dashboard", - } - ] + "dashboards": [ + { + "links": { + "self": "/chronograf/v1/dashboards/myid" + }, + "id": "myid", + "queries": [ + { + "x": 0, + "y": 0, + "w": 2, + "h": 1, + "label": "Objects/Second", + "range": { + "upper": 100, + "lower": 10 + }, + "link": "/chronograf/v1/queries/1" + }, + { + "x": 2, + "y": 0, + "w": 2, + "h": 1, + "label": "Widgets/Second", + "range": { + "upper": 10, + "lower": 0 + }, + "link": "/chronograf/v1/queries/2" + } + ], + "name": "This is my dashboard" + }, + { + "links": { + "self": "/chronograf/v1/dashboards/myid" + }, + "id": "myid", + "queries": [ + { + "x": 0, + "y": 0, + "w": 2, + "h": 1, + "label": "Objects/Second", + "range": { + "upper": 100, + "lower": 10 + }, + "link": "/chronograf/v1/queries/1" + }, + { + "x": 2, + "y": 0, + "w": 2, + "h": 1, + "label": "Widgets/Second", + "range": { + "upper": 10, + "lower": 0 + }, + "link": "/chronograf/v1/queries/2" + } + ], + "name": "This is my dashboard" + } + ] } ``` #### GET /dashboards/myid @@ -95,45 +144,66 @@ Returns an single dashboard object "self": "/chronograf/v1/dashboards/myid" }, "id": "myid", - "layouts": [ - "/chronograf/v1/layouts/a", - "/chronograf/v1/layouts/b" + "queries": [ + { + "x": 0, + "y": 0, + "w": 2, + "h": 1, + "label": "Objects/Second", + "range": { + "upper": 100, + "lower": 10 + }, + "link": "/chronograf/v1/queries/1" + }, + { + "x": 2, + "y": 0, + "w": 2, + "h": 1, + "label": "Widgets/Second", + "range": { + "upper": 10, + "lower": 0 + }, + "link": "/chronograf/v1/queries/2" + } ], - "name": "This is my dashboard", + "name": "This is my dashboard" } ``` #### PUT /dashboards/myid -We want complete updates to the dashboards because we don't know if we can actually incrementally update visualization metadata +We want complete updates to the dashboards because we don't know if we can +actually incrementally update visualization metadata This endpoint will respond with the dashboard after update. #### DELETE -Removes a dashboard but will not remove the explorations or layouts. This could lead to orphans. +Removes a dashboard but will not remove the queries. This will lead to orphans. - -Should we have a page that lists all the explorations and layouts and associated dashboards? +Should we have a page that lists all the queries? #### POST Creating a dashboard from an exploration would need to be a two-step process -1. Create Layout containing exploration -2. Create dashboard including Layout link +1. Create a query +2. Create dashboard including query link -Perhaps the creation of a new dashboard could create associated layouts? +### /queries +The queries endpoint will be a simple CRUD endpoint storing the raw query: -### Modifications to /layouts - -A layout would have an array of associated dashboards. This is a many-to-many relationship with the dashboards. - -If one edits a layout it could edit the layout for all dashboards. If a layout belongs to multiple dashboards, we could prompt the user to decide if they want to edit one or all. - -We will add another filter parameter, `dashboard`, to layouts. - -To get the layouts associated with dashboards `mydashboard` and `myotherdashboard`: -```http -GET /chronograf/v1/layouts?dashboard=mydashboard&dashboard=myotherdashboard HTTP/1.1 +```json +{ + "query": "SELECT mean(n_cpu) from cpu GROUP BY time(15m)", + "db": "telegraf", + "rp": "", + "links" : { + "self": "/chronograf/v1/queries/1" + } +} ``` - - +Over time I'd like this queries endpoint to support a `format` parameter to return +the query data in different JSON formats such as `QueryConfig`. \ No newline at end of file