mozzle

README

mozzle

Pull metrics for Cloud Foundry applications and forward them to Riemann.

This repo provides two functionalities - a mozzle Go package and a mozzle command-line tool.

Package mozzle provides an API for monitoring infrastructure metrics of Cloud Foundry applications and emitting them to a 3rd party monitoring system.

The mozzle command-line tool emits metrics for Cloud Foundry applications to a specified Riemann instance. The rest of this document describes its usage.

Before reading futher, make sure you have a running Riemann instance. If you want just to try out mozzle, refer to this guide how to setup one in a minute.

User's guide

If you want to monitor all applications under your current Cloud Foundry target, as set with the CF CLI, you can do the following.

mozzle -use-cf-cli-target

If you want to explicitly specify the monitored target, you can do that too.

# This example assumes that you have exported the necessary env variables
mozzle -api https://api.bosh-lite.com -access-token $CF_ACCESS_TOKEN -refresh-token $CF_REFRESH_TOKEN -org NASA -space rocket

If you do not want to deal with access and refresh tokens, you can provide plain username and password.

mozzle -api https://api.bosh-lite.com -username admin -password admin -org NASA -space rocket

And if your Cloud Foundry has invalid TLS certificate for some reason, you can skip its verification.

mozzle -insecure -api https://api.bosh-lite.com -username admin -password admin -org NASA -space rocket

Following is a full list of supported command-line flag arguments.

Usage of mozzle:
  -access-token string
    	Cloud Foundry OAuth2 token; either token or username and password must be provided
  -api string
    	Address of the Cloud Foundry API (default "https://api.bosh-lite.com")
  -events-queue-size int
    	Queue size for outgoing events (default 256)
  -events-ttl float
    	TTL for emitted events (in seconds) (default 30)
  -insecure
    	Please, please, don't!
  -org string
    	Cloud Foundry organization (default "NASA")
  -password string
    	Cloud Foundry password; usage is discouraged - see token option instead
  -refresh-interval duration
    	Time between polling the CF API (default 15s)
  -refresh-token string
    	Cloud Foundry OAuth2 refresh token; to be used with the token flag
  -riemann string
    	Address of the Riemann endpoint (default "127.0.0.1:5555")
  -rpc-timeout duration
    	Timeout for RPCs (default 15s)
  -space string
    	Cloud Foundry space (default "rocket")
  -use-cf-cli-target
    	Use CF CLI's current configured target
  -username string
    	Cloud Foundry user; usage is discouraged - see token option instead
  -v	Report mozzle version
  -version
    	Report mozzle version

Demo usage

This repo brings a vagrant automation that will setup a VM ready for showing your application metrics. For more info on settin it up, refer to its README file.

Documentation

Overview

Package mozzle implements Cloud Foundry application monitor that emits metric events.

Metrics for the following services are emitted.

Regarding memory usage of each application instance.

memory used_bytes
memory total_bytes
memory used_ratio

Regarding disk usage of each application instance.

disk used_bytes
disk total_bytes
disk used_ratio

Regarding CPU consumption.

cpu_percent

Regarding each HTTP event (request-response).

http response time_ms
http response content_length_bytes

Regarding application availability.

instance running_count
instance configured_count

Regarding application events.

app event

Each of the events has attributes specifying the application's org, space, name, id, and the insntace index (when appropriate).

Additionally, the HTTP events have attributes specifying the method, request_id, content length the returned status code and the peer type. There are two peer types - client and server. Client means that measurements are recorded via the Cloud Foundry router's HTTP client that requested the application container and server means that the measurements are recorded for responding to the end user via the router server.

The application event metrics have attributes that describe the event's actor and actee, as well as their ids.

Index

• Constants
• func Monitor(ctx context.Context, t Target, e Emitter) (err error)
• type AppMonitor
  • func (m *AppMonitor) Monitor(ctx context.Context, org, space string) error
• type Emitter
• type Firehose
• type Metric
• type RiemannEmitter
  • func (r *RiemannEmitter) Close() error
  • func (r *RiemannEmitter) Emit(m Metric)
  • func (r *RiemannEmitter) Initialize(network, addr string, ttl float32, queueSize int)
• type Target

Constants

const DefaultRPCTimeout = 15 * time.Second

DefaultRPCTimeout is the default timeout when making remote calls.

const DefaultRefreshInterval = 15 * time.Second

DefaultRefreshInterval is the default interval for refreshing application states.

Functions

func Monitor

func Monitor(ctx context.Context, t Target, e Emitter) (err error)

Monitor monitors a target for events and emits them using the provided. Emitter. It is wrapper for creating new AppMonitor and starting it for the specified organization and space. It uses default implementations of Firehose, UAA and ccv2.Client.

Types

type AppMonitor

type AppMonitor struct {
	// Emitter is the emitter used for sending metrics.
	Emitter Emitter
	// CloudController client for the API.
	CloudController *ccv2.Client
	// Firehose streaming client used for receiving logs and events.
	Firehose Firehose
	// UAA should provide valid OAuth2 tokens for the specific Cloud Foundry system.
	UAA oauth2.TokenSource
	// ErrLog is used for logging erros that occur when monitoring applications.
	ErrLog *log.Logger

	// RPCTimeout configures the timeouts when making RPCs.
	RPCTimeout time.Duration
	// RefreshInterval configures the polling interval for application
	// state changes.
	RefreshInterval time.Duration
	// contains filtered or unexported fields
}

AppMonitor implements a Cloud Foundry application monitor that collects various application metrics and emits them using a provided emitter.

func (*AppMonitor) Monitor

func (m *AppMonitor) Monitor(ctx context.Context, org, space string) error

Monitor starts monitoring all applications under the specified organization and space. Monitor blocks until the context is canceled.

type Emitter

type Emitter interface {
	// Emit emits the specified application metric.
	// It should not block and should be safe for concurrent use.
	Emit(m Metric)
}

Emitter should emit application metrics.

type Firehose

type Firehose interface {
	// Stream should listen indefinitely for all log and event messages.
	//
	// The clients should not made any assumption about the order of the
	// received events.
	//
	// Whenever an error is encountered, the error should be sent down the error
	// channel and Stream should attempt to reconnect indefinitely.
	Stream(appGUID string, authToken string) (outputChan <-chan *events.Envelope, errorChan <-chan error)
}

Firehose should implement a streaming firehose client that streams all log and event messages.

type Metric

type Metric struct {
	// Application is the name of the application.
	Application string
	// ApplicationID is the GUID of the application.
	ApplicationID string
	// Organization is the name of the application's organization.
	Organization string
	// Space is the name of the application's space.
	Space string

	// Time is the time when the event occurred.
	Time int64
	// Service for which the metric is relevant.
	Service string
	// Metric value. Could be int64, float32 or float64.
	Metric interface{}
	// State is a text description of the service's state - e.g. 'ok', 'warn'.
	State string
	// Attributes are key-value pairs describing the metric.
	Attributes map[string]string
}

Metric is a metric regarding an application.

type RiemannEmitter

type RiemannEmitter struct {
	// contains filtered or unexported fields
}

RiemannEmitter implements Emitter that interpretes metrics as Riemann events and emits them to a Riemann instance.

func (*RiemannEmitter) Close

func (r *RiemannEmitter) Close() error

Close renders the emitter unusable and frees all allocated resources. The emitter should not be used after it has been closed. There is no guarantee that any queued events will be sent before closing. This particular close never fails.

func (*RiemannEmitter) Emit

func (r *RiemannEmitter) Emit(m Metric)

Emit constructs a riemann event from the specified metric and emits it to Riemann. It is non-blocking and safe for concurrent use by multiple goroutines.

Emit must be used only after calling Initialize, and not after calling Shutdown.

func (*RiemannEmitter) Initialize

func (r *RiemannEmitter) Initialize(network, addr string, ttl float32, queueSize int)

Initialize prepares for emitting to Riemann. It should be called only once, before using the emitter.

Known networks are "tcp", "tcp4", "tcp6", "udp", "udp4" and "udp6". The queueSize argument specifies how many events will be kept in-memory if there is problem with emission.

type Target

type Target struct {
	API      string
	Username string
	Password string
	// Token should be a valid OAuth2 bearer token, including a refresh token.
	// If token is provided the username and password fields should be left emtpy.
	Token    *oauth2.Token
	Insecure bool
	Org      string
	Space    string
	// RPCTimeout configures the timeouts when making RPCs.
	RPCTimeout time.Duration
	// RefreshInterval configures the polling interval for application
	// state changes.
	RefreshInterval time.Duration
}

Target describes a monitoring target.