proxy

Documentation

Overview

Package proxy handles the transmission of ReportLog collected data to the Bearer platform.

Index

• Constants
• func MustParseURL(rawURL string) *url.URL
• type AgentReport
• type ApplicationReport
• type LogReport
  • func MakeConfigReport(version string, environmentType string, secretKey string) LogReport
• type ReportDataCollectionRule
• type ReportLog
  • func NewReportLossReport(n uint) ReportLog
• type RuntimeReport
• type Sender
  • func NewSender(limit uint, endPoint string, version string, secretKey string, ...) *Sender
  • func (s *Sender) Send(log ReportLog)
  • func (s *Sender) Start()
  • func (s *Sender) Stop()
  • func (s *Sender) WriteLog(rl ReportLog)
• type Stage
  • func (s Stage) Next() Stage

Constants

const (
	// AckBacklog is the capacity of the log write acknowledgments channel.
	AckBacklog = 1000
	// QuietLoopPause is the duration of the pause the Start loop will enter
	// if no I/O is available, to avoid consuming too much power by tight looping.
	QuietLoopPause = 10 * time.Millisecond
	// FanInBacklog is the capacity of the fan-in log write channel
	FanInBacklog = 100
	// DrainingTimeout is how long to wait for draining before giving up
	DrainingTimeout = 20 * time.Second

	// End is the ReportLog Type for successful API calls.
	End = `REQUEST_END`
	// Error is the ReportLog Type for failed API calls.
	Error = `REQUEST_ERROR`
	// Loss is the ReportLog Type for synthetic reports warning of reports loss.
	Loss = `REPORT_LOSS`

	// AuthorizationHeader is the canonical Authorization header name.
	AuthorizationHeader = `Authorization`

	// AcceptHeader is the canonical Accept header name.
	AcceptHeader = `Accept`

	// ContentTypeHeader is the canonical content type header name.
	ContentTypeHeader = `Content-Type`

	// FullContentTypeHTML is the content type for HTML.
	FullContentTypeHTML = `text/html; charset=utf-8`

	// ContentTypeSimpleForm is the content type for non-multipart HTML forms.
	ContentTypeSimpleForm = `application/x-www-form-urlencoded`

	// ContentTypeJSON is the canonical content type header value for JSON.
	ContentTypeJSON = `application/json`

	// FullContentTypeJSON is the content type for JSON when emitting it.
	FullContentTypeJSON = `application/json; charset=utf-8`
)

const HostUnknown = `unknown`

HostUnknown is a reserved host name used when the Agent cannot obtain the client host name from the operating system.

Functions

func MustParseURL

func MustParseURL(rawURL string) *url.URL

MustParseURL builds a URL instance from a known-good URL string, panicking it the URL string is not well-formed.

Types

type AgentReport

type AgentReport struct {
	Type    string `json:"type"`
	Version string `json:"version"`
}

AgentReport is the part of the LogReport describing the Agent code.

type ApplicationReport

type ApplicationReport struct {
	Environment string `json:"environment,omitempty"`
}

ApplicationReport is the part of the Report describing the application execution environment, like "development", "staging", or "production".

type LogReport

type LogReport struct {
	SecretKey   string            `json:"secretKey,omitempty"`
	Application ApplicationReport `json:"application"`
	Runtime     RuntimeReport     `json:"runtime"`
	Agent       AgentReport       `json:"agent"`
	Logs        []ReportLog       `json:"logs,omitempty"`
}

LogReport is the information sent to the Bearer configuration and logs servers, describing the current agent operating environment.

func MakeConfigReport

func MakeConfigReport(version string, environmentType string, secretKey string) LogReport

MakeConfigReport creates a valid LogReport

type ReportDataCollectionRule

type ReportDataCollectionRule struct {
	FilterHash string                 `json:"filterHash,omitempty"`
	Params     map[string]interface{} `json:"params,omitempty"`
	Signature  string                 `json:"signature"`
}

ReportDataCollectionRule is a subset of a DataCollectionRule used to report triggered rules back to the platform

type ReportLog

type ReportLog struct {
	LogLevel string `json:"logLevel"`

	StartedAt                 int                         `json:"startedAt,omitempty"` // Unix timestamp UTC milliseconds
	EndedAt                   int                         `json:"endedAt,omitempty"`   // Unix timestamp UTC milliseconds
	Type                      string                      `json:"type,omitempty"`      // REQUEST_END on success, REQUEST_ERROR on connection errors
	Stage                     string                      `json:"stageType,omitempty"`
	ActiveDataCollectionRules *[]ReportDataCollectionRule `json:"activeDataCollectionRules,omitempty"` // More compact than sending the complete rule.

	Port     uint16 `json:"port"`
	Protocol string `json:"protocol"` // Scheme: http[s]
	Hostname string `json:"hostname"`

	Path           string      `json:"path,omitempty"`
	Method         string      `json:"method,omitempty"`
	URL            string      `json:"url,omitempty"`
	RequestHeaders http.Header `json:"requestHeaders"`

	ResponseHeaders http.Header `json:"responseHeaders"`
	StatusCode      int         `json:"statusCode,omitempty"`

	// filters.StageBodies. Note that these 4 may very well NOT be valid strings.
	RequestBody  string `json:"requestBody,omitempty"`
	ResponseBody string `json:"responseBody,omitempty"`
	// Payload SHAs
	RequestBodyPayloadSHA  string `json:"requestBodyPayloadSha,omitempty"`
	ResponseBodyPayloadSHA string `json:"responseBodyPayloadSha,omitempty"`

	// Error
	ErrorCode        string `json:"errorCode,omitempty"`
	ErrorFullMessage string `json:"errorFullMessage,omitempty"`
}

ReportLog is the report summarizing an API call.

func NewReportLossReport

func NewReportLossReport(n uint) ReportLog

NewReportLossReport creates an off-API ReportLog for lost records.

type RuntimeReport

type RuntimeReport struct {
	Version  string `json:"version"`
	Arch     string `json:"arch"`
	Platform string `json:"platform"`
	Type     string `json:"type"`
	Hostname string `json:"hostname,omitempty"`
}

RuntimeReport is the part of the LogReport describing the client runtime environment.

type Sender

type Sender struct {
	// Finish is used to transmit the app termination request to the background
	// sending loop.
	Finish chan struct{}

	// done is used by the background sending loop to confirm it is done, allowing
	// Stop to wait for a clean exit
	Done chan struct{}

	// ForceFinish is a channel that is closed when we no longer wish to wait for
	// draining to complete.
	ForceFinish chan struct{}

	// Draining is a channel that is closed when the sender is finishing. It is
	// used to stop Send enqueuing further logs.
	Draining chan struct{}

	// FanIn receives the ReportLog elements to send from all the goroutines
	// created on API calls termination, serializing them to the background sending loop.
	FanIn chan ReportLog

	// Acks receives the acknowledgments from the HTTP sending the marshaled
	// ReportLog elements to the Bearer platform.
	//
	// In this version, each element has value 1. When sending gets to be batched
	// in a later version, this value will represent the number of acknowledged
	// LogReport elements actually transmitted.
	Acks chan uint

	// InFlight is the number of ReportLog elements awaiting delivery to the
	// Bearer platform.
	InFlight uint

	// Lost is the number of lost and never sent ReportLog elements. It is reset
	// to 0 when transmission resumes.
	Lost uint

	// Counter is the total number of records handled.
	Counter uint

	// InflightLimit is the maximum value of Inflight before bandwidth reduction
	// is triggered. When InFlight exceeds this value, extra ReportLog elements
	// are dropped, only counting the number of lost elements, to avoid saturation
	// of the client process and network.
	InFlightLimit uint

	// LogEndpoint is the URL of the Bearer host receiving the logs.
	LogEndpoint string

	// EnvironmentType is the runtime environment type, e.g. staging or production.
	EnvironmentType string

	// SecretKey is the account secret key.
	SecretKey string

	// Version is the agent version.
	Version string

	http.Client
	*zerolog.Logger
}

Sender is the control structure for the background log writing loop.

func NewSender

func NewSender(
	limit uint, endPoint string, version string, secretKey string, environmentType string,
	transport http.RoundTripper, logger *zerolog.Logger,
) *Sender

NewSender builds a ready-to-user

func (*Sender) Send

func (s *Sender) Send(log ReportLog)

Send sends a ReportLog element to the FanIn channel for transmission. It should not be called after Stop.

func (*Sender) Start

func (s *Sender) Start()

Start configures and starts the background sending loop.

func (*Sender) Stop

func (s *Sender) Stop()

Stop notifies the background sending loop that the application is shutting down. It will then block waiting for any remaining reports to be sent. If the DrainingTimeout is reached then it will stop sending any further logs.

func (*Sender) WriteLog

func (s *Sender) WriteLog(rl ReportLog)

WriteLog attempts to transmit a ReportLog to the Bearer platform, and acknowleges it finished its attempt, whether it succeeded or not.

type Stage

type Stage string

Stage represents the stage an API call is in.

const (
	// StageUndefined represents a lack of requirement for any specific stage.
	// It is not used as one of the actual API stage.
	StageUndefined = "UndefinedStage"
	// StageConnect is the initial API call stage.
	StageConnect Stage = "ConnectStage"
	// StageRequest is the stage at which the request is being built.
	StageRequest Stage = "RequestStage"
	// StageResponse is the stage at which the response has started to return.
	StageResponse Stage = "ResponseStage"
	// StageBodies is the stage at which request and response bodies are available.
	StageBodies Stage = "BodiesStage"
	// StageInvalid is an invalid stage a request should never reach.
	StageInvalid Stage = "InvalidStage"
)

func (Stage) Next

func (s Stage) Next() Stage

Next provides the stage following the current stage.