Documentation ¶
Overview ¶
Package simplejson eases the creation of HTTP endpoints to support Grafana's simplejson data source plugin.
Example ¶
package main import ( "bytes" "context" "fmt" "io" "net/http" "net/http/httptest" "time" simplejson "github.com/tcolgate/grafana-simple-json-go" ) // GSJExample demonstrates how to create a new Grafana Simple JSON compatible // HTTP server. type GSJExample struct{} // GrafanaQuery handles timeserie type queries. func (GSJExample) GrafanaQuery(ctx context.Context, target string, args simplejson.QueryArguments) ([]simplejson.DataPoint, error) { return []simplejson.DataPoint{ {Time: args.To.Add(-5 * time.Second), Value: 1234.0}, {Time: args.To, Value: 1500.0}, }, nil } func (GSJExample) GrafanaQueryTable(ctx context.Context, target string, args simplejson.TableQueryArguments) ([]simplejson.TableColumn, error) { return []simplejson.TableColumn{ {Text: "Time", Data: simplejson.TableTimeColumn{args.To}}, {Text: "SomeText", Data: simplejson.TableStringColumn{"blah"}}, {Text: "Value", Data: simplejson.TableNumberColumn{1.0}}, }, nil } func (GSJExample) GrafanaAnnotations(ctx context.Context, query string, args simplejson.AnnotationsArguments) ([]simplejson.Annotation, error) { return []simplejson.Annotation{ // A single point in time annotation { Time: time.Unix(1234, 0), Title: "First Title", Text: "First annotation", }, // An annotation over a time range { Time: time.Unix(1235, 0), TimeEnd: time.Unix(1237, 0), Title: "Second Title", Text: "Second annotation with range", Tags: []string{"outage"}, }, }, nil } func (GSJExample) GrafanaSearch(ctx context.Context, target string) ([]string, error) { return []string{"example1", "example2", "example3"}, nil } func (GSJExample) GrafanaAdhocFilterTags(ctx context.Context) ([]simplejson.TagInfoer, error) { return []simplejson.TagInfoer{ simplejson.TagStringKey("mykey"), }, nil } func (GSJExample) GrafanaAdhocFilterTagValues(ctx context.Context, key string) ([]simplejson.TagValuer, error) { return []simplejson.TagValuer{ simplejson.TagStringValue("value1"), simplejson.TagStringValue("value2"), }, nil } func main() { gsj := simplejson.New( simplejson.WithQuerier(GSJExample{}), simplejson.WithTableQuerier(GSJExample{}), simplejson.WithSearcher(GSJExample{}), simplejson.WithAnnotator(GSJExample{}), ) // This is the format of the inbound request from Grafana reqBuf := bytes.NewBufferString(`{"range": { "from": "2016-04-15T13:44:39.070Z", "to": "2016-04-15T14:44:39.070Z" }, "rangeRaw": { "from": "now-1h", "to": "now" },"annotation": {"name":"query","datasource":"yoursjsource","query":"some query","enable":true,"iconColor":"#1234"}}`) req := httptest.NewRequest(http.MethodGet, "/annotations", reqBuf) w := httptest.NewRecorder() gsj.ServeHTTP(w, req) res := w.Result() buf := &bytes.Buffer{} io.Copy(buf, res.Body) fmt.Println(buf.String()) }
Output: [{"annotation":{"name":"query","datasource":"yoursjsource","query":"some query","enable":true,"iconColor":"#1234"},"time":1234000,"title":"First Title","text":"First annotation","tags":null},{"annotation":{"name":"query","datasource":"yoursjsource","query":"some query","enable":true,"iconColor":"#1234"},"time":1235000,"regionId":1,"title":"Second Title","text":"Second annotation with range","tags":["outage"]},{"annotation":{"name":"query","datasource":"yoursjsource","query":"some query","enable":true,"iconColor":"#1234"},"time":1237000,"regionId":1,"title":"Second Title","text":"Second annotation with range","tags":["outage"]}]
Index ¶
- type Annotation
- type AnnotationsArguments
- type Annotator
- type DataPoint
- type Handler
- func (h *Handler) HandleAnnotations(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleQuery(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleRoot(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleSearch(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleTagKeys(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleTagValues(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
- type Opt
- type Querier
- type QueryAdhocFilter
- type QueryArguments
- type QueryCommonArguments
- type Searcher
- type TableColumn
- type TableColumnData
- type TableNumberColumn
- type TableQuerier
- type TableQueryArguments
- type TableStringColumn
- type TableTimeColumn
- type TagInfoer
- type TagSearcher
- type TagStringKey
- type TagStringValue
- type TagValuer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Annotation ¶
type Annotation struct { Time time.Time `json:"time"` TimeEnd time.Time `json:"timeEnd,omitempty"` Title string `json:"title"` Text string `json:"text"` Tags []string `json:"tags"` }
Annotation represents an annotation that can be displayed on a graph, or in a table.
type AnnotationsArguments ¶ added in v0.9.0
type AnnotationsArguments struct {
QueryCommonArguments
}
AnnotationsArguments defines the options to a annotations query.
type Annotator ¶ added in v0.9.0
type Annotator interface {
GrafanaAnnotations(ctx context.Context, query string, args AnnotationsArguments) ([]Annotation, error)
}
An Annotator responds to queries for annotations from Grafana
type Handler ¶ added in v0.9.0
type Handler struct {
// contains filtered or unexported fields
}
Handler Is an opaque type that supports the required HTTP handlers for the Simple JSON plugin
func New ¶
New creates a new http.Handler that will answer to the required endpoint for a SimpleJSON source. You should use WithQuerier, WithTableQuerier, WithAnnotator and WithSearch to set handlers for each of the endpionts.
func (*Handler) HandleAnnotations ¶ added in v0.9.0
func (h *Handler) HandleAnnotations(w http.ResponseWriter, r *http.Request)
HandleAnnotations responds to the /annotation requests.
func (*Handler) HandleQuery ¶ added in v0.9.0
func (h *Handler) HandleQuery(w http.ResponseWriter, r *http.Request)
HandleQuery hands the /query endpoint, calling the appropriate timeserie or table handler.
func (*Handler) HandleRoot ¶ added in v0.9.0
func (h *Handler) HandleRoot(w http.ResponseWriter, r *http.Request)
HandleRoot serves a plain 200 OK for /, required by Grafana
func (*Handler) HandleSearch ¶ added in v0.9.0
func (h *Handler) HandleSearch(w http.ResponseWriter, r *http.Request)
HandleSearch implements the /search endpoint.
func (*Handler) HandleTagKeys ¶ added in v0.9.0
func (h *Handler) HandleTagKeys(w http.ResponseWriter, r *http.Request)
HandleTagKeys implements the /tag-keys endpoint.
func (*Handler) HandleTagValues ¶ added in v0.9.0
func (h *Handler) HandleTagValues(w http.ResponseWriter, r *http.Request)
HandleTagValues implements the /tag-values endpoint.
type Opt ¶
Opt provides configurable options for the Handler
func WithAnnotator ¶ added in v0.9.0
WithAnnotator adds an annoations handler.
func WithQuerier ¶ added in v0.9.0
WithQuerier adds a timeserie query handler.
func WithSearcher ¶ added in v0.9.0
WithSearcher adds a search handlers.
func WithSource ¶ added in v0.9.0
func WithSource(src interface{}) Opt
WithSource will attempt to use the datasource provided as a Querier, TableQuerier, Annotator, Searcher and TagSearch if it supports the required interface.
func WithTableQuerier ¶ added in v0.9.0
func WithTableQuerier(q TableQuerier) Opt
WithTableQuerier adds a table query handler.
func WithTagSearcher ¶ added in v0.9.0
func WithTagSearcher(s TagSearcher) Opt
WithTagSearcher adds adhoc filter tag search handlers.
type Querier ¶ added in v0.9.0
type Querier interface {
GrafanaQuery(ctx context.Context, target string, args QueryArguments) ([]DataPoint, error)
}
A Querier responds to timeseri queries from Grafana
type QueryAdhocFilter ¶ added in v0.9.0
type QueryAdhocFilter struct { Key string `json:"key"` Operator string `json:"operator"` Value string `json:"value"` }
QueryAdhocFilter describes a user supplied filter to be added to each query target.
type QueryArguments ¶ added in v0.9.0
type QueryArguments struct { QueryCommonArguments Interval time.Duration MaxDPs int }
QueryArguments defines the options to a timeserie query.
type QueryCommonArguments ¶ added in v0.9.0
type QueryCommonArguments struct {
From, To time.Time
Filters []QueryAdhocFilter
}
QueryCommonArguments describes the arguments common to timeserie and table queries.
type TableColumn ¶ added in v0.9.0
type TableColumn struct { Text string Data TableColumnData }
TableColumn represents a single table column. Data should be one the TableNumberColumn, TableStringColumn or TableTimeColumn types.
type TableColumnData ¶ added in v0.9.0
type TableColumnData interface {
// contains filtered or unexported methods
}
TableColumnData is a private interface to this package, you should use one of TableStringColumn, TableNumberColumn, or TableTimeColumn
type TableNumberColumn ¶ added in v0.9.0
type TableNumberColumn []float64
A TableNumberColumn holds values for a "number" column in a table.
type TableQuerier ¶ added in v0.9.0
type TableQuerier interface {
GrafanaQueryTable(ctx context.Context, target string, args TableQueryArguments) ([]TableColumn, error)
}
A TableQuerier responds to table queries from Grafana
type TableQueryArguments ¶ added in v0.9.0
type TableQueryArguments struct {
QueryCommonArguments
}
TableQueryArguments defines the options to a table query.
type TableStringColumn ¶ added in v0.9.0
type TableStringColumn []string
A TableStringColumn holds values for a "string" column in a table.
type TableTimeColumn ¶ added in v0.9.0
A TableTimeColumn holds values for a "time" column in a table.
type TagInfoer ¶ added in v0.9.0
type TagInfoer interface {
// contains filtered or unexported methods
}
TagInfoer is an internal interface to describe difference types of tag.
type TagSearcher ¶ added in v0.9.0
type TagSearcher interface { GrafanaAdhocFilterTags(ctx context.Context) ([]TagInfoer, error) GrafanaAdhocFilterTagValues(ctx context.Context, key string) ([]TagValuer, error) }
A TagSearcher allows the querying of tag keys and values for adhoc filters.
type TagStringKey ¶ added in v0.9.0
type TagStringKey string
TagStringKey represent an adhoc query string key.
type TagStringValue ¶ added in v0.9.0
type TagStringValue string
TagStringValue represent an adhoc query string key.