noaa

README

#NOAA

NOAA is a client library to consume metric and log messages from Doppler.

##WARNING

This library does not work with Go 1.3 through 1.3.3, due to a bug in the standard libraries.

##Usage

See the included sample applications. In order to use the samples, you will have to export the following environment variable:

• CF_ACCESS_TOKEN - You can get this value by executing ($ cf oauth-token). Example:

export CF_ACCESS_TOKEN="bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI3YmM2MzllOC0wZGM0LTQ4YzItYTAzYS0xYjkyYzRhMWFlZTIiLCJzdWIiOiI5YTc5MTVkOS04MDc1LTQ3OTUtOTBmOS02MGM0MTU0YTJlMDkiLCJzY29wZSI6WyJzY2ltLnJlYWQiLCJjbG91ZF9jb250cm9sbGVyLmFkbWluIiwicGFzc3dvcmQud3JpdGUiLCJzY2ltLndyaXRlIiwib3BlbmlkIiwiY2xvdWRfY29udHJvbGxlci53cml0ZSIsImNsb3VkX2NvbnRyb2xsZXIucmVhZCJdLCJjbGllbnRfaWQiOiJjZiIsImNpZCI6ImNmIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjlhNzkxNWQ5LTgwNzUtNDc5NS05MGY5LTYwYzQxNTRhMmUwOSIsInVzZXJfbmFtZSI6ImFkbWluIiwiZW1haWwiOiJhZG1pbiIsImlhdCI6MTQwNDg0NzU3NywiZXhwIjoxNDA0ODQ4MTc3LCJpc3MiOiJodHRwczovL3VhYS4xMC4yNDQuMC4zNC54aXAuaW8vb2F1dGgvdG9rZW4iLCJhdWQiOlsic2NpbSIsIm9wZW5pZCIsImNsb3VkX2NvbnRyb2xsZXIiLCJwYXNzd29yZCJdfQ.mAaOJthCotW763lf9fysygqdES_Mz1KFQ3HneKbwY4VJx-ARuxxiLh8l_8Srx7NJBwGlyEtfYOCBcIdvyeDCiQ0wT78Zw7ZJYFjnJ5-ZkDy5NbMqHbImDFkHRnPzKFjJHip39jyjAZpkFcrZ8_pUD8XxZraqJ4zEf6LFdAHKFBM"

• DOPPLER_ADDR - It is based on your environment. Example:

export DOPPLER_ADDR="wss://doppler.10.244.0.34.xip.io:443"

###Application logs

The sample/main.go application streams logs for a particular app. The following environment variable needs to be set:

• APP_GUID - You can get this value from running $ cf app APP --guid. Example:

export APP_GUID=55fdb274-d6c9-4b8c-9b1f-9b7e7f3a346c

Then you can run the sample app like this:

go build -o bin/sample sample/main.go
bin/sample

###Logs and metrics firehose

The firehose_sample/main.go application streams metrics data and logs for all apps.

You can run the firehose sample app like this:

go build -o bin/firehose_sample firehose_sample/main.go
bin/firehose_sample

Multiple subscribers may connect to the firehose endpoint, each with a unique subscription_id (configurable in main.go). Each subscriber (in practice, a pool of clients with a common subscription_id) receives the entire stream. For each subscription_id, all data will be distributed evenly among that subscriber's client pool.

###Container metrics

The container_metrics_sample/main.go application streams container metrics for the specified appId.

You can run the container metrics sample app like this:

go build -o bin/containermetrics_sample container_metrics_sample/main.go
bin/containermetrics_sample

For more information to setup a test environment in order to pull container metrics look at the README.md in the container_metrics_sample.

##Development

Use go get -d -v -t ./... && ginkgo --race --randomizeAllSpecs --failOnPending --skipMeasurements --cover to run the tests.

Documentation

Index

• Variables
• func SortContainerMetrics(messages []*events.ContainerMetric) []*events.ContainerMetric
• func SortRecent(messages []*events.LogMessage) []*events.LogMessage
• type Consumer
  • func NewConsumer(trafficControllerUrl string, tlsConfig *tls.Config, ...) *Consumer
  • func (cnsmr *Consumer) Close() error
  • func (cnsmr *Consumer) ContainerMetrics(appGuid string, authToken string) ([]*events.ContainerMetric, error)
  • func (cnsmr *Consumer) Firehose(subscriptionId string, authToken string, outputChan chan<- *events.Envelope, ...)
  • func (cnsmr *Consumer) FirehoseWithoutReconnect(subscriptionId string, authToken string, outputChan chan<- *events.Envelope) error
  • func (cnsmr *Consumer) RecentLogs(appGuid string, authToken string) ([]*events.LogMessage, error)
  • func (cnsmr *Consumer) SetDebugPrinter(debugPrinter DebugPrinter)
  • func (cnsmr *Consumer) SetOnConnectCallback(cb func())
  • func (cnsmr *Consumer) Stream(appGuid string, authToken string, outputChan chan<- *events.Envelope, ...)
  • func (cnsmr *Consumer) StreamWithoutReconnect(appGuid string, authToken string, outputChan chan<- *events.Envelope) error
  • func (cnsmr *Consumer) TailingLogs(appGuid string, authToken string, outputChan chan<- *events.LogMessage, ...)
  • func (cnsmr *Consumer) TailingLogsWithoutReconnect(appGuid string, authToken string, outputChan chan<- *events.LogMessage) error
• type DebugPrinter

Variables

var (
	// KeepAlive sets the interval between keep-alive messages sent by the client to loggregator.
	KeepAlive = 25 * time.Second

	ErrNotOK          = errors.New("unknown issue when making HTTP request to Loggregator")
	ErrNotFound       = ErrNotOK // NotFound isn't an accurate description of how this is used; please use ErrNotOK instead
	ErrBadResponse    = errors.New("bad server response")
	ErrBadRequest     = errors.New("bad client request")
	ErrLostConnection = errors.New("remote server terminated connection unexpectedly")
)

Functions

func SortContainerMetrics

func SortContainerMetrics(messages []*events.ContainerMetric) []*events.ContainerMetric

SortContainerMetrics sorts a slice of containerMetrics by InstanceIndex.

The input slice is sorted; the return value is simply a pointer to the same slice.

func SortRecent

func SortRecent(messages []*events.LogMessage) []*events.LogMessage

SortRecent sorts a slice of LogMessages by timestamp. The sort is stable, so messages with the same timestamp are sorted in the order that they are received.

The input slice is sorted; the return value is simply a pointer to the same slice.

Types

type Consumer

type Consumer struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Consumer represents the actions that can be performed against traffic controller.

func NewConsumer

func NewConsumer(trafficControllerUrl string, tlsConfig *tls.Config, proxy func(*http.Request) (*url.URL, error)) *Consumer

NewConsumer creates a new consumer to a traffic controller.

func (*Consumer) Close

func (cnsmr *Consumer) Close() error

Close terminates the websocket connection to traffic controller.

func (*Consumer) ContainerMetrics

func (cnsmr *Consumer) ContainerMetrics(appGuid string, authToken string) ([]*events.ContainerMetric, error)

ContainerMetrics connects to traffic controller via its 'containermetrics' http(s) endpoint and returns the most recent messages for an app. The returned metrics will be sorted by InstanceIndex.

func (*Consumer) Firehose

func (cnsmr *Consumer) Firehose(subscriptionId string, authToken string, outputChan chan<- *events.Envelope, errorChan chan<- error)

Firehose behaves exactly as FirehoseWithoutReconnect, except that it retries 5 times if the connection to the remote server is lost.

func (*Consumer) FirehoseWithoutReconnect

func (cnsmr *Consumer) FirehoseWithoutReconnect(subscriptionId string, authToken string, outputChan chan<- *events.Envelope) error

FirehoseWithoutReconnect streams all data. All clients with the same subscriptionId will receive a proportionate share of the message stream. Each pool of clients will receive the entire stream.

If you wish to be able to terminate the listen early, run FirehoseWithoutReconnect in a Goroutine and call Close() when you are finished listening.

Messages are presented in the order received from the loggregator server. Chronological or other ordering is not guaranteed. It is the responsibility of the consumer of these channels to provide any desired sorting mechanism.

func (*Consumer) RecentLogs

func (cnsmr *Consumer) RecentLogs(appGuid string, authToken string) ([]*events.LogMessage, error)

RecentLogs connects to traffic controller via its 'recentlogs' http(s) endpoint and returns a slice of recent messages. It does not guarantee any order of the messages; they are in the order returned by traffic controller.

The SortRecent method is provided to sort the data returned by this method.

func (*Consumer) SetDebugPrinter

func (cnsmr *Consumer) SetDebugPrinter(debugPrinter DebugPrinter)

SetDebugPrinter enables logging of the websocket handshake.

func (*Consumer) SetOnConnectCallback

func (cnsmr *Consumer) SetOnConnectCallback(cb func())

SetOnConnectCallback sets a callback function to be called with the websocket connection is established.

func (*Consumer) Stream

func (cnsmr *Consumer) Stream(appGuid string, authToken string, outputChan chan<- *events.Envelope, errorChan chan<- error)

Stream behaves exactly as StreamWithoutReconnect, except that it retries 5 times if the connection to the remote server is lost.

func (*Consumer) StreamWithoutReconnect

func (cnsmr *Consumer) StreamWithoutReconnect(appGuid string, authToken string, outputChan chan<- *events.Envelope) error

StreamWithoutReconnect listens indefinitely for all log and event messages.

If you wish to be able to terminate the listen early, run StreamWithoutReconnect in a Goroutine and call Close() when you are finished listening.

Messages are presented in the order received from the loggregator server. Chronological or other ordering is not guaranteed. It is the responsibility of the consumer of these channels to provide any desired sorting mechanism.

func (*Consumer) TailingLogs

func (cnsmr *Consumer) TailingLogs(appGuid string, authToken string, outputChan chan<- *events.LogMessage, errorChan chan<- error)

TailingLogs behaves exactly as TailingLogsWithoutReconnect, except that it retries 5 times if the connection to the remote server is lost and returns all errors from each attempt on errorChan.

func (*Consumer) TailingLogsWithoutReconnect

func (cnsmr *Consumer) TailingLogsWithoutReconnect(appGuid string, authToken string, outputChan chan<- *events.LogMessage) error

TailingLogsWithoutReconnect listens indefinitely for log messages only; other event types are dropped.

If you wish to be able to terminate the listen early, run TailingLogsWithoutReconnect in a Goroutine and call Close() when you are finished listening.

Messages are presented in the order received from the loggregator server. Chronological or other ordering is not guaranteed. It is the responsibility of the consumer of these channels to provide any desired sorting mechanism.

type DebugPrinter

type DebugPrinter interface {
	Print(title, dump string)
}