simplejson

README

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 New(opts ...Opt) *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
  • func WithAnnotator(a Annotator) Opt
  • func WithQuerier(q Querier) Opt
  • func WithSearcher(s Searcher) Opt
  • func WithSource(src interface{}) Opt
  • func WithTableQuerier(q TableQuerier) Opt
  • func WithTagSearcher(s TagSearcher) 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

• Package

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

type AnnotationsArguments struct {
	QueryCommonArguments
}

AnnotationsArguments defines the options to a annotations query.

type Annotator

type Annotator interface {
	GrafanaAnnotations(ctx context.Context, query string, args AnnotationsArguments) ([]Annotation, error)
}

An Annotator responds to queries for annotations from Grafana

type DataPoint

type DataPoint struct {
	Time  time.Time
	Value float64
}

DataPoint represents a single datapoint at a given point in time.

type Handler

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

func New(opts ...Opt) *Handler

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

func (h *Handler) HandleAnnotations(w http.ResponseWriter, r *http.Request)

HandleAnnotations responds to the /annotation requests.

func (*Handler) HandleQuery

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

func (h *Handler) HandleRoot(w http.ResponseWriter, r *http.Request)

HandleRoot serves a plain 200 OK for /, required by Grafana

func (*Handler) HandleSearch

func (h *Handler) HandleSearch(w http.ResponseWriter, r *http.Request)

HandleSearch implements the /search endpoint.

func (*Handler) HandleTagKeys

func (h *Handler) HandleTagKeys(w http.ResponseWriter, r *http.Request)

HandleTagKeys implements the /tag-keys endpoint.

func (*Handler) HandleTagValues

func (h *Handler) HandleTagValues(w http.ResponseWriter, r *http.Request)

HandleTagValues implements the /tag-values endpoint.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP supports the http.Handler interface for a simplejson handler.

type Opt

type Opt func(*Handler) error

Opt provides configurable options for the Handler

func WithAnnotator

func WithAnnotator(a Annotator) Opt

WithAnnotator adds an annoations handler.

func WithQuerier

func WithQuerier(q Querier) Opt

WithQuerier adds a timeserie query handler.

func WithSearcher

func WithSearcher(s Searcher) Opt

WithSearcher adds a search handlers.

func WithSource

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

func WithTableQuerier(q TableQuerier) Opt

WithTableQuerier adds a table query handler.

func WithTagSearcher

func WithTagSearcher(s TagSearcher) Opt

WithTagSearcher adds adhoc filter tag search handlers.

type Querier

type Querier interface {
	GrafanaQuery(ctx context.Context, target string, args QueryArguments) ([]DataPoint, error)
}

A Querier responds to timeseri queries from Grafana

type QueryAdhocFilter

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

type QueryArguments struct {
	QueryCommonArguments
	Interval time.Duration
	MaxDPs   int
}

QueryArguments defines the options to a timeserie query.

type QueryCommonArguments

type QueryCommonArguments struct {
	From, To time.Time
	Filters  []QueryAdhocFilter
}

QueryCommonArguments describes the arguments common to timeserie and table queries.

type Searcher

type Searcher interface {
	GrafanaSearch(ctx context.Context, target string) ([]string, error)
}

A Searcher responds to search queries from Grafana

type TableColumn

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

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

type TableNumberColumn []float64

A TableNumberColumn holds values for a "number" column in a table.

type TableQuerier

type TableQuerier interface {
	GrafanaQueryTable(ctx context.Context, target string, args TableQueryArguments) ([]TableColumn, error)
}

A TableQuerier responds to table queries from Grafana

type TableQueryArguments

type TableQueryArguments struct {
	QueryCommonArguments
}

TableQueryArguments defines the options to a table query.

type TableStringColumn

type TableStringColumn []string

A TableStringColumn holds values for a "string" column in a table.

type TableTimeColumn

type TableTimeColumn []time.Time

A TableTimeColumn holds values for a "time" column in a table.

type TagInfoer

type TagInfoer interface {
	// contains filtered or unexported methods
}

TagInfoer is an internal interface to describe difference types of tag.

type TagSearcher

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

type TagStringKey string

TagStringKey represent an adhoc query string key.

type TagStringValue

type TagStringValue string

TagStringValue represent an adhoc query string key.

type TagValuer

type TagValuer interface {
	// contains filtered or unexported methods
}

TagValuer is in an internal interface used to describe tag Values.