transport

Documentation

Overview

Package transport provides an interface and implementation for transporting data to the Elastic APM server.

Index

• Variables
• func DefaultUserAgent() string
• type HTTPError
  • func (e *HTTPError) Error() string
• type HTTPTransport
  • func NewHTTPTransport(opts HTTPTransportOptions) (*HTTPTransport, error)
  • func (t *HTTPTransport) MajorServerVersion(ctx context.Context, refreshStale bool) uint32
  • func (t *HTTPTransport) SendProfile(ctx context.Context, metadataReader io.Reader, profileReaders ...io.Reader) error
  • func (t *HTTPTransport) SendStream(ctx context.Context, r io.Reader) error
  • func (t *HTTPTransport) SetAPIKey(apiKey string)
  • func (t *HTTPTransport) SetSecretToken(secretToken string)
  • func (t *HTTPTransport) SetServerURL(u ...*url.URL) error
  • func (t *HTTPTransport) SetUserAgent(ua string)
  • func (t *HTTPTransport) WatchConfig(ctx context.Context, args apmconfig.WatchParams) <-chan apmconfig.Change
• type HTTPTransportOptions
  • func (opts HTTPTransportOptions) Validate() error
• type Transport
  • func NewDiscardTransport(err error) Transport

Variables

var (
	// Discard is a Transport on which all operations
	// succeed without doing anything.
	Discard = discardTransport{}
)

Functions

func DefaultUserAgent

func DefaultUserAgent() string

DefaultUserAgent returns the default value to use for the User-Agent header: apm-agent-go/<agent-version>.

Types

type HTTPError

type HTTPError struct {
	Response *http.Response
	Message  string
}

HTTPError is an error returned by HTTPTransport methods when requests fail.

func (*HTTPError) Error

func (e *HTTPError) Error() string

type HTTPTransport

type HTTPTransport struct {
	// Client exposes the http.Client used by the HTTPTransport for
	// sending requests to the APM Server.
	Client *http.Client
	// contains filtered or unexported fields
}

HTTPTransport is an implementation of Transport, sending payloads via a net/http client.

func NewHTTPTransport

func NewHTTPTransport(opts HTTPTransportOptions) (*HTTPTransport, error)

NewHTTPTransport returns a new HTTPTransport, initialized with opts, which can be used for streaming data to the APM Server.

func (*HTTPTransport) MajorServerVersion

func (t *HTTPTransport) MajorServerVersion(ctx context.Context, refreshStale bool) uint32

MajorServerVersion returns the APM Server's major version. When refreshStale is true` it will request the remote APM Server's version from `/`, otherwise it will return the cached version. If the returned first argument is 0, the cache is stale.

func (*HTTPTransport) SendProfile

func (t *HTTPTransport) SendProfile(
	ctx context.Context,
	metadataReader io.Reader,
	profileReaders ...io.Reader,
) error

SendProfile sends a symbolised pprof profile, encoded as protobuf, and gzip-compressed.

NOTE this is an experimental API, and may be removed in a future minor version, without being considered a breaking change.

func (*HTTPTransport) SendStream

func (t *HTTPTransport) SendStream(ctx context.Context, r io.Reader) error

SendStream sends the stream over HTTP. If SendStream returns an error and the transport is configured with more than one APM Server URL, then the following request will be sent to the next URL in the list.

func (*HTTPTransport) SetAPIKey

func (t *HTTPTransport) SetAPIKey(apiKey string)

SetAPIKey sets the Authorization header with the given API Key.

This overrides the value specified via the ELASTIC_APM_SECRET_TOKEN or ELASTIC_APM_API_KEY environment variables, if either are set.

func (*HTTPTransport) SetSecretToken

func (t *HTTPTransport) SetSecretToken(secretToken string)

SetSecretToken sets the Authorization header with the given secret token.

This overrides the value specified via the ELASTIC_APM_SECRET_TOKEN or ELASTIC_APM_API_KEY environment variables, if either are set.

func (*HTTPTransport) SetServerURL

func (t *HTTPTransport) SetServerURL(u ...*url.URL) error

SetServerURL sets the APM Server URL (or URLs) for sending requests. At least one URL must be specified, or the method will return an error. The list will be randomly shuffled.

func (*HTTPTransport) SetUserAgent

func (t *HTTPTransport) SetUserAgent(ua string)

SetUserAgent sets the User-Agent header that will be sent with each request.

func (*HTTPTransport) WatchConfig

func (t *HTTPTransport) WatchConfig(ctx context.Context, args apmconfig.WatchParams) <-chan apmconfig.Change

WatchConfig polls the APM Server for agent config changes, sending them over the returned channel.

type HTTPTransportOptions

type HTTPTransportOptions struct {
	// APIKey holds the base64-encoded API Key credential string, used for
	// authenticating the agent. APIKey takes precedence over SecretToken.
	//
	// If unspecified, APIKey will be initialized using the
	// ELASTIC_APM_API_KEY environment variable.
	APIKey string

	// SecretToken holds the secret token configured in the APM Server, used
	// for authenticating the agent.
	//
	// If unspecified, SecretToken will be initialized using the
	// ELASTIC_APM_SECRET_TOKEN envirohnment variable.
	SecretToken string

	// ServerURLs holds the URLs for your Elastic APM Server. The Server
	// supports both HTTP and HTTPS. If you use HTTPS, then you may need to
	// configure your client machines so that the server certificate can be
	// verified. You can disable certificate verification with SkipServerVerify.
	//
	// If no URLs are specified, then ServerURLs will be initialized using the
	// ELASTIC_APM_SERVER_URL environment variable, defaulting to
	// "http://localhost:8200" if the environment variable is not set.
	ServerURLs []*url.URL

	// ServerTimeout holds the timeout for requests made to your Elastic APM
	// server.
	//
	// When set to zero, it will default to 30 seconds. Negative values
	// are not allowed.
	//
	// If ServerTimeout is zero, then it will be initialized using the
	// ELASTIC_APM_SERVER_TIMEOUT environment variable, defaulting to
	// 30 seconds if the environment variable is not set. Negative values are
	// not allowed, and will cause NewHTTPTransport to return an error.
	ServerTimeout time.Duration

	// TLSClientConfig holds client TLS configuration for use in the HTTP client.
	//
	// If TLS is nil, TLS will be constructed using the following environment
	// variables:
	//
	// - ELASTIC_APM_SERVER_CERT: the path to a PEM-encoded TLS certificate
	//   that must match the APM Server-supplied certificate. This can be used
	//   to pin a self signed certificate.
	//
	// - ELASTIC_APM_SERVER_CA_CERT_FILE: the path to a PEM-encoded TLS
	//   Certificate Authority certificate that will be used for verifying
	//   the server's TLS certificate chain.
	//
	// - ELASTIC_APM_VERIFY_SERVER_CERT: flag to control verification of the
	//   APM Server's TLS certificates. If ELASTIC_APM_SERVER_CERT is defined,
	//   ELASTIC_APM_VERIFY_SERVER_CERT is ignored.
	TLSClientConfig *tls.Config

	// UserAgent holds the value to use for the User-Agent header.
	//
	// If unspecified, UserAgent will be set to the value returned by
	// DefaultUserAgent().
	UserAgent string
}

HTTPTransportOptions for the HTTPTransport.

func (HTTPTransportOptions) Validate

func (opts HTTPTransportOptions) Validate() error

Validate ensures the HTTPTransportOptions are valid.

type Transport

type Transport interface {
	// SendStream sends a data stream to the server, returning when the
	// stream has been closed (Read returns io.EOF) or the HTTP request
	// terminates.
	SendStream(context.Context, io.Reader) error
}

Transport provides an interface for sending streams of encoded model entities to the Elastic APM server, and for querying config. Methods are not required to be safe for concurrent use.

func NewDiscardTransport

func NewDiscardTransport(err error) Transport

NewDiscardTransport returns a Transport that returns the given error from all operations.