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.

##Get the Code

This Go project is designed to be imported into $GOPATH, rather than being cloned into any working directory. There are two ways to do this.

• The easiest way with with go get. This will import the project, along with all dependencies, into your $ GOPATH.

  $ echo $GOPATH
  /Users/myuser/go
  
  $ go get github.com/cloudfoundry/noaa
  
  $ ls ~/go/src/github.com/cloudfoundry/
  noaa/         sonde-go/
  

• You can also manually clone the repo into your $GOPATH, but you then have to manually import dependencies.

  $ echo $GOPATH
  /Users/myuser/go
  
  $ cd /Users/myuser/go/src/github.com/cloudfoundry
  $ git clone git@github.com:cloudfoundry/noaa.git
  $ cd noaa
  $ go get ./...
  

Sample Applications

Prerequisites

In order to use the sample applications below, you will have to export the following environment variables:

• 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:4443"

Application logs

The samples/app_logs/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/app_logs samples/app_logs/main.go
bin/app_logs

Logs and metrics firehose

The samples/firehose/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 samples/firehose/main.go
bin/firehose

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 samples/container_metrics/consumer/main.go application streams container metrics for the specified appId.

You can run the container metrics sample app like this:

go build -o bin/container_metrics samples/container_metrics/consumer/main.go
bin/container_metrics

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) SetIdleTimeout(idleTimeout time.Duration)
  • 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
• type NullDebugPrinter
  • func (NullDebugPrinter) Print(title, body string)

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
}

noaa.Consumer is deprecated. Use the one in the consumer package.

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

noaa.Consumer is deprecated. Use the one in the consumer package.

NewConsumer creates a new consumer to a traffic controller.

func (*Consumer) Close

func (cnsmr *Consumer) Close() error

noaa.Consumer is deprecated. Use the one in the consumer package.

Close terminates the websocket connection to traffic controller.

func (*Consumer) ContainerMetrics

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

noaa.Consumer is deprecated. Use the one in the consumer package.

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)

noaa.Consumer is deprecated. Use the one in the consumer package.

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

noaa.Consumer is deprecated. Use the one in the consumer package.

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)

noaa.Consumer is deprecated. Use the one in the consumer package.

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)

noaa.Consumer is deprecated. Use the one in the consumer package.

SetDebugPrinter enables logging of the websocket handshake.

func (*Consumer) SetIdleTimeout

func (cnsmr *Consumer) SetIdleTimeout(idleTimeout time.Duration)

func (*Consumer) SetOnConnectCallback

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

noaa.Consumer is deprecated. Use the one in the consumer package.

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)

noaa.Consumer is deprecated. Use the one in the consumer package.

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

noaa.Consumer is deprecated. Use the one in the consumer package.

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)

noaa.Consumer is deprecated. Use the one in the consumer package.

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

noaa.Consumer is deprecated. Use the one in the consumer package.

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

type NullDebugPrinter

type NullDebugPrinter struct {
}

func (NullDebugPrinter) Print

func (NullDebugPrinter) Print(title, body string)