smapi

README

Synthetic Monitoring API Go client

This is a Go client for the API used by Grafana's Synthetic Monitoring application.

For instructions about setting up Synthetic Monitoring in your Grafana Cloud instance, please visit our docs

API documentation

Please consult the documentation for the API that this library accesses.

Documentation

Overview

Package smapi provides access to the Synthetic Monitoring API.

Index

• Variables
• func ValidateResponse(action string, resp *http.Response, result interface{}) error
• type Client
  • func NewClient(baseURL, accessToken string, client *http.Client) *Client
  • func NewDatasourceClient(baseURL, accessToken string, client *http.Client) *Client
  • func (h *Client) AddCheck(ctx context.Context, check synthetic_monitoring.Check) (*synthetic_monitoring.Check, error)
  • func (h *Client) AddProbe(ctx context.Context, probe synthetic_monitoring.Probe) (*synthetic_monitoring.Probe, []byte, error)
  • func (h *Client) CreateToken(ctx context.Context) (string, error)
  • func (h *Client) Delete(ctx context.Context, url string, auth bool) (*http.Response, error)
  • func (h *Client) DeleteCheck(ctx context.Context, id int64) error
  • func (h *Client) DeleteProbe(ctx context.Context, id int64) error
  • func (h *Client) DeleteToken(ctx context.Context) error
  • func (h *Client) Get(ctx context.Context, url string, auth bool, headers http.Header) (*http.Response, error)
  • func (h *Client) GetCheck(ctx context.Context, id int64) (*synthetic_monitoring.Check, error)
  • func (h *Client) GetProbe(ctx context.Context, id int64) (*synthetic_monitoring.Probe, error)
  • func (h *Client) GetTenant(ctx context.Context) (*synthetic_monitoring.Tenant, error)
  • func (h *Client) Install(ctx context.Context, stackID, metricsInstanceID, logsInstanceID int64, ...) (*model.RegistrationInstallResponse, error)
  • func (h *Client) ListChecks(ctx context.Context) ([]synthetic_monitoring.Check, error)
  • func (h *Client) ListProbes(ctx context.Context) ([]synthetic_monitoring.Probe, error)
  • func (h *Client) Post(ctx context.Context, url string, auth bool, headers http.Header, ...) (*http.Response, error)
  • func (h *Client) PostJSON(ctx context.Context, url string, auth bool, req interface{}) (*http.Response, error)
  • func (h *Client) RefreshToken(ctx context.Context) error
  • func (h *Client) ResetProbeToken(ctx context.Context, probe synthetic_monitoring.Probe) (*synthetic_monitoring.Probe, []byte, error)
  • func (h *Client) UpdateCheck(ctx context.Context, check synthetic_monitoring.Check) (*synthetic_monitoring.Check, error)
  • func (h *Client) UpdateProbe(ctx context.Context, probe synthetic_monitoring.Probe) (*synthetic_monitoring.Probe, error)
  • func (h *Client) UpdateTenant(ctx context.Context, tenant synthetic_monitoring.Tenant) (*synthetic_monitoring.Tenant, error)
  • func (h *Client) ValidateToken(ctx context.Context) error
• type HTTPError
  • func (e *HTTPError) Error() string

Variables

var (
	// ErrAuthorizationTokenRequired is the error returned by client
	// calls that require an authorization token.
	//
	// Authorization tokens can be obtained using Install or Init.
	ErrAuthorizationTokenRequired = errors.New("authorization token required")

	// ErrCannotEncodeJSONRequest is the error returned if it's not
	// possible to encode the request as a JSON object. This error
	// should never happen.
	ErrCannotEncodeJSONRequest = errors.New("cannot encode request")

	// ErrUnexpectedResponse is returned by client calls that get
	// unexpected responses, for example some field that must not be
	// zero is zero. If possible a more specific error should be
	// used.
	ErrUnexpectedResponse = errors.New("unexpected response")
)

Functions

func ValidateResponse

func ValidateResponse(action string, resp *http.Response, result interface{}) error

ValidateResponse handles responses from the SM API.

If the status code of the request is not 200, it is expected that there's an error included with the response. This function will decode that response and return in the form of an HTTPError.

In the case of success, this function attempts to decode the response as a JSON object and storing it the `result` argument.

Types

type Client

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

Client is a Synthetic Monitoring API client.

It should be initialized using the NewClient function in this package.

func NewClient

func NewClient(baseURL, accessToken string, client *http.Client) *Client

NewClient creates a new client for the Synthetic Monitoring API.

The accessToken is optional. If it's not specified, it's necessary to use one of the registration calls to obtain one, Install or Init.

If no client is provided, http.DefaultClient will be used.

func NewDatasourceClient

func NewDatasourceClient(baseURL, accessToken string, client *http.Client) *Client

NewDatasourceClient creates a new client for the Synthetic Monitoring API using a Grafana datasource proxy.

The accessToken should be the grafana access token.

If no client is provided, http.DefaultClient will be used.

func (*Client) AddCheck

func (h *Client) AddCheck(ctx context.Context, check synthetic_monitoring.Check) (*synthetic_monitoring.Check, error)

AddCheck creates a new Synthetic Monitoring check in the API server.

The return value contains the assigned ID.

func (*Client) AddProbe

func (h *Client) AddProbe(ctx context.Context, probe synthetic_monitoring.Probe) (*synthetic_monitoring.Probe, []byte, error)

AddProbe is used to create a new Synthetic Monitoring probe.

The return value includes the assigned probe ID as well as the access token that should be used by that probe to communicate with the Synthetic Monitoring API.

func (*Client) CreateToken

func (h *Client) CreateToken(ctx context.Context) (string, error)

CreateToken is used to obtain a new access token for the authenticated tenant.

The newly created token _does not_ replace the token currently used by the client.

func (*Client) Delete

func (h *Client) Delete(ctx context.Context, url string, auth bool) (*http.Response, error)

Delete is a utility method to send a DELETE request to the SM API.

The `url` argument specifies the additional URL path of the request (minus the base, which is part of the client). `auth` specifies whether or not to include authorization headers. `headers` specifies any additional headers that need to be included with the request.

func (*Client) DeleteCheck

func (h *Client) DeleteCheck(ctx context.Context, id int64) error

DeleteCheck deletes an existing Synthetic Monitoring check from the API server.

func (*Client) DeleteProbe

func (h *Client) DeleteProbe(ctx context.Context, id int64) error

DeleteProbe is used to remove a new Synthetic Monitoring probe.

func (*Client) DeleteToken

func (h *Client) DeleteToken(ctx context.Context) error

DeleteToken deletes the access token that the client is currently using.

After this call, the client won't be able to make furhter calls into the API.

func (*Client) Get

func (h *Client) Get(ctx context.Context, url string, auth bool, headers http.Header) (*http.Response, error)

Get is a utility method to send a GET request to the SM API.

The `url` argument specifies the additional URL path of the request (minus the base, which is part of the client). `auth` specifies whether or not to include authorization headers. `headers` specifies any additional headers that need to be included with the request.

func (*Client) GetCheck

func (h *Client) GetCheck(ctx context.Context, id int64) (*synthetic_monitoring.Check, error)

GetCheck returns a single Synthetic Monitoring check identified by the provided ID.

func (*Client) GetProbe

func (h *Client) GetProbe(ctx context.Context, id int64) (*synthetic_monitoring.Probe, error)

GetProbe is used to obtain the details about a single existing Synthetic Monitoring probe.

func (*Client) GetTenant

func (h *Client) GetTenant(ctx context.Context) (*synthetic_monitoring.Tenant, error)

GetTenant retrieves the information associated with the authenticated tenant.

func (*Client) Install

func (h *Client) Install(ctx context.Context, stackID, metricsInstanceID, logsInstanceID int64, publisherToken string) (*model.RegistrationInstallResponse, error)

Install takes a stack ID, a hosted metrics instance ID, a hosted logs instance ID and a publisher token that can be used to publish data to those instances and sets up a new Synthetic Monitoring tenant using those parameters.

Note that the client will not any validation on these arguments and it will simply pass them to the corresponding API server.

The returned RegistrationInstallResponse will contain the access token used to make further calls to the API server. This call will _modify_ the client in order to use that access token.

func (*Client) ListChecks

func (h *Client) ListChecks(ctx context.Context) ([]synthetic_monitoring.Check, error)

ListChecks returns the list of Synthetic Monitoring checks for the authenticated tenant.

func (*Client) ListProbes

func (h *Client) ListProbes(ctx context.Context) ([]synthetic_monitoring.Probe, error)

ListProbes returns the list of probes accessible to the authenticated tenant.

func (*Client) Post

func (h *Client) Post(ctx context.Context, url string, auth bool, headers http.Header, body io.Reader) (*http.Response, error)

Post is a utility method to send a POST request to the SM API.

The `url` argument specifies the additional URL path of the request (minus the base, which is part of the client). `auth` specifies whether or not to include authorization headers. `headers` specifies any additional headers that need to be included with the request. `body` is the body sent with the POST request.

func (*Client) PostJSON

func (h *Client) PostJSON(ctx context.Context, url string, auth bool, req interface{}) (*http.Response, error)

PostJSON is a utility method to send a POST request to the SM API with a body specified by the `req` argument encoded as JSON.

The `url` argument specifies the additional URL path of the request (minus the base, which is part of the client). `auth` specifies whether or not to include authorization headers. `headers` specifies any additional headers that need to be included with the request.

func (*Client) RefreshToken

func (h *Client) RefreshToken(ctx context.Context) error

RefreshToken creates a new access token in the API which replaces the one that the client is currently using.

func (*Client) ResetProbeToken

func (h *Client) ResetProbeToken(ctx context.Context, probe synthetic_monitoring.Probe) (*synthetic_monitoring.Probe, []byte, error)

ResetProbeToken requests a _new_ token for the probe.

func (*Client) UpdateCheck

func (h *Client) UpdateCheck(ctx context.Context, check synthetic_monitoring.Check) (*synthetic_monitoring.Check, error)

UpdateCheck updates an existing check in the API server.

The return value contains the updated check (updated timestamps, etc).

func (*Client) UpdateProbe

func (h *Client) UpdateProbe(ctx context.Context, probe synthetic_monitoring.Probe) (*synthetic_monitoring.Probe, error)

UpdateProbe is used to update details about an existing Synthetic Monitoring probe.

The return value contains the new representation of the probe according the Synthetic Monitoring API server.

func (*Client) UpdateTenant

func (h *Client) UpdateTenant(ctx context.Context, tenant synthetic_monitoring.Tenant) (*synthetic_monitoring.Tenant, error)

UpdateTenant updates the specified tenant in the Synthetic Monitoring API. The updated tenant (possibly with updated timestamps) is returned.

func (*Client) ValidateToken

func (h *Client) ValidateToken(ctx context.Context) error

ValidateToken contacts the API server and verifies that the currently installed token is still valid. one that the client is currently using.

type HTTPError

type HTTPError struct {
	Code   int
	Status string
	Action string
	Api    struct {
		Msg   string
		Error string
	}
}

HTTPError represents errors returned from the Synthetic Monitoring API server.

It implements the error interface, so it can be returned from functions interacting with the Synthetic Monitoring API server.

func (*HTTPError) Error

func (e *HTTPError) Error() string

Error allows HTTPError to implement the error interface.

The formatting of the error is a little opinionated, as it has to communicate an error from the API if it's there, or an error from the HTTP client.