datasource

Documentation

Overview

Package datasource provides utilities for creating and serving a data source plugin over gRPC.

Example

package main

import (
	"context"
	"net/http"
	"os"

	"github.com/grafana/grafana-plugin-sdk-go/backend"
	"github.com/grafana/grafana-plugin-sdk-go/backend/datasource"
	"github.com/grafana/grafana-plugin-sdk-go/backend/httpclient"
	"github.com/grafana/grafana-plugin-sdk-go/backend/instancemgmt"
	"github.com/grafana/grafana-plugin-sdk-go/backend/resource/httpadapter"
)

type testDataSourceInstanceSettings struct {
	httpClient *http.Client
}

func newDataSourceInstance(setting backend.DataSourceInstanceSettings) (instancemgmt.Instance, error) {
	opts, err := setting.HTTPClientOptions()
	if err != nil {
		return nil, err
	}

	client, err := httpclient.New(opts)
	if err != nil {
		return nil, err
	}

	return &testDataSourceInstanceSettings{
		httpClient: client,
	}, nil
}

func (s *testDataSourceInstanceSettings) Dispose() {
	// Cleanup
}

type testDataSource struct {
	im instancemgmt.InstanceManager
}

func newDataSource() datasource.ServeOpts {
	im := datasource.NewInstanceManager(newDataSourceInstance)
	ds := &testDataSource{
		im: im,
	}

	mux := http.NewServeMux()
	mux.HandleFunc("/test", ds.handleTest)

	return datasource.ServeOpts{
		CheckHealthHandler:  ds,
		CallResourceHandler: httpadapter.New(mux),
		QueryDataHandler:    ds,
	}
}

func (ds *testDataSource) getSettings(ctx context.Context, pluginContext backend.PluginContext) (*testDataSourceInstanceSettings, error) {
	iface, err := ds.im.Get(ctx, pluginContext)
	if err != nil {
		return nil, err
	}

	return iface.(*testDataSourceInstanceSettings), nil
}

func (ds *testDataSource) CheckHealth(ctx context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error) {
	settings, err := ds.getSettings(ctx, req.PluginContext)
	if err != nil {
		return nil, err
	}

	// Handle request
	resp, err := settings.httpClient.Get("http://")
	if err != nil {
		return nil, err
	}
	resp.Body.Close()
	return nil, nil
}

func (ds *testDataSource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
	var resp *backend.QueryDataResponse
	err := ds.im.Do(ctx, req.PluginContext, func(settings *testDataSourceInstanceSettings) error {
		// Handle request
		resp, err := settings.httpClient.Get("http://")
		if err != nil {
			return err
		}
		resp.Body.Close()
		return nil
	})

	return resp, err
}

func (ds *testDataSource) handleTest(rw http.ResponseWriter, req *http.Request) {
	ctx := req.Context()
	pluginContext := httpadapter.PluginConfigFromContext(ctx)
	settings, err := ds.getSettings(ctx, pluginContext)
	if err != nil {
		rw.WriteHeader(500)
		return
	}

	// Handle request
	resp, err := settings.httpClient.Get("http://")
	if err != nil {
		rw.WriteHeader(500)
		return
	}
	resp.Body.Close()
}

func main() {
	err := datasource.Serve(newDataSource())
	if err != nil {
		backend.Logger.Error(err.Error())
		os.Exit(1)
	}
}

Index

• func Manage(pluginID string, instanceFactory InstanceFactoryFunc, opts ManageOpts) error
• func NewInstanceManager(fn InstanceFactoryFunc) instancemgmt.InstanceManager
• func NewInstanceProvider(fn InstanceFactoryFunc) instancemgmt.InstanceProvider
• func Serve(opts ServeOpts) error
• type InstanceFactoryFunc
• type ManageOpts
• type QueryTypeMux
  • func NewQueryTypeMux() *QueryTypeMux
  • func (mux *QueryTypeMux) Handle(queryType string, handler backend.QueryDataHandler)
  • func (mux *QueryTypeMux) HandleFunc(queryType string, ...)
  • func (mux *QueryTypeMux) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error)
• type ServeOpts

Examples

• Package
• QueryTypeMux

Functions

func Manage

func Manage(pluginID string, instanceFactory InstanceFactoryFunc, opts ManageOpts) error

Manage starts serving the data source over gPRC with automatic instance management. pluginID should match the one from plugin.json.

func NewInstanceManager

func NewInstanceManager(fn InstanceFactoryFunc) instancemgmt.InstanceManager

NewInstanceManager creates a new data source instance manager,

This is a helper method for calling NewInstanceProvider and creating a new instancemgmt.InstanceProvider, and providing that to instancemgmt.New.

func NewInstanceProvider

func NewInstanceProvider(fn InstanceFactoryFunc) instancemgmt.InstanceProvider

NewInstanceProvider create a new data source instance provuder,

The instance provider is responsible for providing cache keys for data source instances, creating new instances when needed and invalidating cached instances when they have been updated in Grafana. Cache key is based on the numerical data source identifier. If fn is nil, NewInstanceProvider panics.

func Serve

func Serve(opts ServeOpts) error

Serve starts serving the data source over gPRC.

Types

type InstanceFactoryFunc

type InstanceFactoryFunc func(settings backend.DataSourceInstanceSettings) (instancemgmt.Instance, error)

InstanceFactoryFunc factory method for creating data source instances.

type ManageOpts

type ManageOpts struct {
	// GRPCSettings settings for gPRC.
	GRPCSettings backend.GRPCSettings

	// TracingOpts contains settings for tracing setup.
	TracingOpts tracing.Opts
}

ManageOpts can modify Manage behaviour.

type QueryTypeMux

type QueryTypeMux struct {
	// contains filtered or unexported fields
}

QueryTypeMux is a query type multiplexer.

Example

package main

import (
	"context"

	"github.com/grafana/grafana-plugin-sdk-go/backend"
	"github.com/grafana/grafana-plugin-sdk-go/backend/datasource"
)

func main() {
	mux := datasource.NewQueryTypeMux()
	mux.HandleFunc("queryTypeA", func(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
		// handle queryTypeA
		return nil, nil
	})
	mux.HandleFunc("queryTypeB", func(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
		// handle queryTypeB
		return nil, nil
	})

	_ = datasource.ServeOpts{
		QueryDataHandler: mux,
	}
}

func NewQueryTypeMux

func NewQueryTypeMux() *QueryTypeMux

NewQueryTypeMux allocates and returns a new QueryTypeMux.

func (*QueryTypeMux) Handle

func (mux *QueryTypeMux) Handle(queryType string, handler backend.QueryDataHandler)

Handle registers the handler for the given query type.

Providing an empty queryType registers the handler as a fallback handler that will be called when query type doesn't match any registered handlers. If handler is nil, Handle panics. If a handler already exists for queryType, Handle panics.

func (*QueryTypeMux) HandleFunc

func (mux *QueryTypeMux) HandleFunc(queryType string, handler func(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error))

HandleFunc registers the handler function for the given query type.

Providing an empty queryType registers the handler as a fallback handler that will be called when query type doesn't match any registered handlers. If handler is nil, Handle panics. If a handler already exists for queryType, Handle panics.

func (*QueryTypeMux) QueryData

func (mux *QueryTypeMux) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error)

QueryData dispatches the request to the handler(s) whose query type matches the request queries query type.

type ServeOpts

type ServeOpts struct {
	// CheckHealthHandler handler for health checks.
	// Optional to implement.
	backend.CheckHealthHandler

	// CallResourceHandler handler for resource calls.
	// Optional to implement.
	backend.CallResourceHandler

	// QueryDataHandler handler for data queries.
	// Required to implement.
	backend.QueryDataHandler

	// StreamHandler for streaming queries.
	backend.StreamHandler

	// GRPCSettings settings for gPRC.
	GRPCSettings backend.GRPCSettings
}

ServeOpts options for serving a data source plugin.