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
• 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) 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) GetTenant(ctx context.Context) (*synthetic_monitoring.Tenant, error)
  • func (h *Client) Init(ctx context.Context, adminToken string) (*model.RegistrationInitResponse, 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) RefreshToken(ctx context.Context) error
  • func (h *Client) ResetProbeToken(ctx context.Context, probe synthetic_monitoring.Probe) (*synthetic_monitoring.Probe, []byte, error)
  • func (h *Client) Save(ctx context.Context, adminToken string, metricInstanceID, logInstanceID int64) 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")
)

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) 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) GetTenant

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

GetTenant retrieves the information associated with the authenticated tenant.

func (*Client) Init

func (h *Client) Init(ctx context.Context, adminToken string) (*model.RegistrationInitResponse, error)

Init uses provided admin token to call the deprecated registration init entrypoint in order to create a Synthetic Monitoring tenant.

Note that the client will not any validation on the provided token and it will simply pass it to the corresponding API server.

The returned RegistrationInitResponse 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) 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) 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) Save

func (h *Client) Save(ctx context.Context, adminToken string, metricInstanceID, logInstanceID int64) error

Save should be called after Init to select the desired hosted metrics and hosted logs instance to be used by Synthetic Monitoring probes.

After this call, the tenant is fully configured and can be used to create checks and probes.

Just as Init, Save is deprecated.

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
}

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