backend

Documentation

Index

• Constants
• Variables
• func Serve(opts ServeOpts) error
• func SetupPluginEnvironment(pluginID string)
• type CallResourceHandler
• type CallResourceRequest
• type CallResourceResponse
• type CallResourceResponseSender
• type CheckHealthHandler
• type CheckHealthRequest
• type CheckHealthResult
• type DataQuery
• type DataResponse
• type DataSourceConfig
• type HealthStatus
• type PluginConfig
• type QueryDataHandler
• type QueryDataRequest
• type QueryDataResponse
  • func NewQueryDataResponse(size int) *QueryDataResponse
• type Responses
• type ServeOpts
• type TimeRange
  • func (tr TimeRange) Duration() time.Duration
• type TransformDataCallBackHandler
• type TransformDataHandler
• type TransformHandlers
• type User

Constants

const (
	// PluginProfilerEnv is a constant for the GF_PLUGINS_PROFILER environment variable used to enable pprof.
	PluginProfilerEnv = "GF_PLUGINS_PROFILER"

	// PluginProfilerPortEnv is a constant for the GF_PLUGINS_PROFILER_PORT environment variable use to specify a pprof port (default 6060).
	PluginProfilerPortEnv = "GF_PLUGINS_PROFILER_PORT"
)

Variables

var Logger log.Logger = log.New()

Logger is the default logger instance. This can be used directly to log from your plugin to grafana-server with calls like backend.Logger.Debug(...).

Functions

func Serve

func Serve(opts ServeOpts) error

Serve starts serving the plugin over gRPC.

func SetupPluginEnvironment

func SetupPluginEnvironment(pluginID string)

SetupPluginEnvironment will read the environment variables and apply the standard environment behavior.

As the SDK evolves, this will likely change.

Currently this function enables and configures profiling with pprof.

Types

type CallResourceHandler

type CallResourceHandler interface {
	CallResource(ctx context.Context, req *CallResourceRequest, sender CallResourceResponseSender) error
}

CallResourceHandler handles resource calls.

type CallResourceRequest

type CallResourceRequest struct {
	PluginConfig PluginConfig
	Path         string
	Method       string
	URL          string
	Headers      map[string][]string
	Body         []byte
	User         *User
}

type CallResourceResponse

type CallResourceResponse struct {
	Status  int
	Headers map[string][]string
	Body    []byte
}

type CallResourceResponseSender

type CallResourceResponseSender interface {
	Send(*CallResourceResponse) error
}

CallResourceResponseSender used for sending resource call responses.

type CheckHealthHandler

type CheckHealthHandler interface {
	CheckHealth(ctx context.Context, req *CheckHealthRequest) (*CheckHealthResult, error)
}

CheckHealthHandler enables users to send health check requests to a backend plugin

type CheckHealthRequest

type CheckHealthRequest struct {
	PluginConfig PluginConfig
}

CheckHealthRequest contains the healthcheck request

type CheckHealthResult

type CheckHealthResult struct {
	Status      HealthStatus
	Message     string
	JSONDetails []byte
}

CheckHealthResult contains the healthcheck response

type DataQuery

type DataQuery struct {
	// RefID is the unique identifer of the query, set by the frontend call.
	RefID string

	// MaxDataPoints is the maximum number of datapoints that should be returned from a time series query.
	MaxDataPoints int64

	// Interval is the suggested duration between time points in a time series query.
	Interval time.Duration

	// TimeRange is the Start and End of the query as sent by the frontend.
	TimeRange TimeRange

	// JSON is the raw JSON query and includes the above properties as well as custom properties.
	JSON json.RawMessage
}

DataQuery represents a single query as sent from the frontend. A slice of DataQuery makes up the Queries property of a QueryDataRequest.

type DataResponse

type DataResponse struct {
	// The data returned from the Query. Each Frame repeats the RefID.
	Frames data.Frames

	// Meta contains a custom JSON object for custom response metadata about the query. WARNING: Currently ignored by front end of Grafana.
	Meta json.RawMessage

	// Error is a property to be set if the the corresponding DataQuery has an error.
	Error error
}

DataResponse contains the results from a DataQuery. A map of RefIDs (unique query identifers) to this type makes up the Responses property of a QueryDataResponse. The Error property is used to allow for partial success responses from the containing QueryDataResponse.

type DataSourceConfig

type DataSourceConfig struct {
	// ID is the Grafana assigned numeric identifier of the the data source instance.
	ID int64

	// Name is the configured name of the data source instance.
	Name string

	// URL is the configured URL of a data source instance (e.g. the URL of an API endpoint).
	URL string

	// User is a configured user for a data source instance. This is not a Grafana user, rather an arbitrary string.
	User string

	// Database is the configured database for a data source instance. (e.g. the default Database a SQL data source would connect to).
	Database string

	// BasicAuthEnabled indicates if this data source instance should use basic authentication.
	BasicAuthEnabled bool

	// BasicAuthUser is the configured user for basic authentication. (e.g. when a data source uses basic authentication to connect to whatever API it fetches data from).
	BasicAuthUser string

	// JSONData contains the raw DataSourceConfig as JSON as stored by Grafana server. It repeats the properties in this object and includes custom properties.
	JSONData json.RawMessage

	// DecryptedSecureJSONData contains key,value pairs where the encrypted configuration in Grafana server have been decrypted before passing them to the plugin.
	DecryptedSecureJSONData map[string]string

	// Updated is the last time the configuration for the data source instance was updated.
	Updated time.Time
}

DataSourceConfig holds configuration for a data source instance.

type HealthStatus

type HealthStatus int

HealthStatus is the status of the plugin.

const (
	// HealthStatusUnknown means the status of the plugin is unknown.
	HealthStatusUnknown HealthStatus = iota

	// HealthStatusOk means the status of the plugin is good.
	HealthStatusOk

	// HealthStatusError means the plugin is in an error state.
	HealthStatusError
)

type PluginConfig

type PluginConfig struct {
	// OrgID is the Grafana identifier of the Grafana organization this plugin instance belongs too.
	OrgID int64

	// PluginID is the unique identifer from the plugin.json id property.
	PluginID string

	// JSONData repeats the properties at this level of the object (excluding DataSourceConfig), and also includes any custom properties associated with the plugin config instance.
	JSONData json.RawMessage

	// DecryptedSecureJSONData contains key,value pairs where the encrypted configuration plugin instance in Grafana server have been decrypted before passing them to the plugin.
	DecryptedSecureJSONData map[string]string

	// Updated is the last time this plugin instance's configuration was updated.
	Updated time.Time

	// DataSourceConfig is the configuration of a data source instance for this plugin.
	// If the request is a data source request, this will be set to the specific datasource instance
	// the request is for.
	DataSourceConfig *DataSourceConfig
}

PluginConfig holds the configuration for a plugin instance.

Grafana supports multiple organizations and only one plugin instance per Grafana organization. A plugin instance can have multiple data source instances.

PluginConfig is attached to incoming requests to uniquely identify the Plugin instance the request belongs to. If the request is a data source request, it also contains the configuration of the data source instance.

type QueryDataHandler

type QueryDataHandler interface {
	// QueryData handles multiple queries and returns multiple responses.
	// req contains the queries []DataQuery (where each query contains RefID as a unique identifer).
	// The QueryDataResponse contains a map of RefID to the response for each query, and each response
	// contains Frames ([]*Frame).
	QueryData(ctx context.Context, req *QueryDataRequest) (*QueryDataResponse, error)
}

QueryDataHandler handles data queries.

type QueryDataRequest

type QueryDataRequest struct {
	PluginConfig PluginConfig
	Headers      map[string]string
	Queries      []DataQuery

	// User is information about the grafana-server user that made the request.
	User *User
}

QueryDataRequest contains a single request which contains multiple queries. It is the input type for a QueryData call.

type QueryDataResponse

type QueryDataResponse struct {
	// Responses is a map of RefIDs (Unique Query ID) to *DataResponse.
	Responses Responses
}

QueryDataResponse contains the results from a QueryDataRequest. It is the return type of a QueryData call.

func NewQueryDataResponse

func NewQueryDataResponse(size int) *QueryDataResponse

NewQueryDataResponse returns a QueryDataResponse with the Responses property initialized to size.

type Responses

type Responses map[string]*DataResponse

Responses is a map of RefIDs (Unique Query ID) to *DataResponse.

type ServeOpts

type ServeOpts struct {
	// CheckHealthHandler handler for health checks.
	CheckHealthHandler CheckHealthHandler

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

	// QueryDataHandler handler for data queries.
	// Required to implement if data source.
	QueryDataHandler QueryDataHandler

	// TransformDataHandler handler for data transformations.
	// Very experimental and shouldn't be implemented in most cases.
	// Optional to implement.
	TransformDataHandler TransformDataHandler

	// MaxGRPCReceiveMsgSize the max gRPC message size in bytes the plugin can receive.
	// If this is <= 0, gRPC uses the default 4MB.
	MaxGRPCReceiveMsgSize int

	// MaxGRPCSendMsgSize the max gRPC message size in bytes the plugin can send.
	// If this is <= 0, gRPC uses the default `math.MaxInt32`.
	MaxGRPCSendMsgSize int
}

ServeOpts options for serving plugins.

type TimeRange

type TimeRange struct {
	// From is the start time of the query.
	From time.Time

	// To is the end time of the query.
	To time.Time
}

TimeRange represents a time range for a query and is a property of DataQuery.

func (TimeRange) Duration

func (tr TimeRange) Duration() time.Duration

Duration returns a time.Duration representing the amount of time between From and To.

type TransformDataCallBackHandler

type TransformDataCallBackHandler interface {
	// TODO: Forget if I actually need PluginConfig on the callback or not.
	QueryData(ctx context.Context, req *QueryDataRequest) (*QueryDataResponse, error)
}

type TransformDataHandler

type TransformDataHandler interface {
	TransformData(ctx context.Context, req *QueryDataRequest, callBack TransformDataCallBackHandler) (*QueryDataResponse, error)
}

type TransformHandlers

type TransformHandlers interface {
	TransformDataHandler
}

type User

type User struct {
	Login string
	Name  string
	Email string
	Role  string
}

User represents the Grafana user.