dropsonde

package module
v0.0.0-...-6af1f78 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 26, 2015 License: Apache-2.0 Imports: 16 Imported by: 0

README

Dropsonde

Build Status Coverage Status GoDoc

Go library to collect and emit metric and logging data from CF components. https://godoc.org/github.com/cloudfoundry/dropsonde

Protocol Buffer format

See dropsonde-protocol for the full specification of the dropsonde Protocol Buffer format.

Use this script to generate Go handlers for the various protobuf messages.

Initialization and Configuration

import (
    "github.com/cloudfoundry/dropsonde"
)

func main() {
    dropsonde.Initialize("localhost:3457", "router", "z1", "0")
}

This initializes dropsonde, along with the logs and metrics packages. It also instruments the default HTTP handler for outgoing requests, instrument itself (to count messages sent, etc.), and provides basic runtime stats.

The first argument is the destination for messages (typically metron). The host and port is required. The remaining arguments form the origin. This list is used by downstream portions of the dropsonde system to track the source of metrics.

Alternatively, import github.com/cloudfoundry/dropsonde/metrics to include the ability to send custom metrics, via metrics.SendValue and metrics.IncrementCounter.

Sending application logs and metrics

After calling dropsonde.Initialize (as above), the subpackages logs and metrics are also initialized. (They can be separately initialized, though this requires more setup of emitters, etc.)

Application Logs

Currently, dropsonde only supports sending logs for platform-hosted applications (i.e. not the emitting component itself).

Use logs.SendAppLog and logs.SendAppErrorLog to send single logs, e.g.

logs.SendAppLog("b7ba6142-6e6a-4e0b-81c1-d7025888cce4", "An event happened!", "APP", "0")

To process a stream of app logs (from, say, a socket of an application's STDOUT output), use logs.ScanLogStream and logs.ScanErrorLogStream:

logs.ScanLogStream("b7ba6142-6e6a-4e0b-81c1-d7025888cce4", "APP", "0", appLogSocketConnection)

See the Cloud Foundry DEA Logging Agent for an example of production code that scans log streams using these methods.

Metrics

As mentioned earlier, initializing Dropsonde automatically instruments the default HTTP server and client objects in the net/http package, and will automatically send HttpStart and HttpStop events for every request served or made.

For instrumentation of other metrics, use the metrics package.

  • metrics.SendValue(name, value, unit) sends an event that records the value of a measurement at an instant in time. (These are often called "gauge" metrics by other libraries.) The value is of type float64, and the unit is mandatory. We recommend following this guide for unit names, and highly encourage SI units and prefixes where appropriate.
  • metrics.IncrementCounter(name) and metrics.AddToCounter(name, delta) send events that increment the named counter (by one or the specified non-negative delta, respectively). Note that the cumulative total is not included in the event message, only the increment.

Manual usage

For details on manual usage of dropsonde, please refer to the Godocs. Pay particular attenion to the ByteEmitter, InstrumentedHandler, and InstrumentedRoundTripper types.

Handling dropsonde events

Programs wishing to emit events and metrics should use the package as described above. For programs that wish to process events, we provide the dropsonde/unmarshaller and dropsonde/marshaller packages for decoding/reencoding raw Protocol Buffer messages. Use dropsonde/signature to sign and validate messages.

Documentation

Overview

Package dropsonde provides sensible defaults for using dropsonde.

The default HTTP transport is instrumented, as well as some basic stats about the Go runtime. Additionally, the default emitter is itself instrumented to periodically send "heartbeat" messages containing counts of received and sent events. The default emitter sends events over UDP.

Use

dropsonde.Initialize("localhost:3457", origins...)

to initialize. See package metrics and logs for other usage.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AutowiredEmitter

func AutowiredEmitter() emitter.EventEmitter

AutowiredEmitter exposes the emitter used by Dropsonde after its initialization.

func Initialize

func Initialize(destination string, origin ...string) error

Initialize creates default emitters and instruments the default HTTP transport.

The origin variable is required and specifies the source name for all metrics emitted by this process. If it is not set, the program will run normally but will not emit metrics.

The destination variable sets the host and port to which metrics are sent. It is optional, and defaults to DefaultDestination.

func InitializeWithEmitter

func InitializeWithEmitter(emitter emitter.EventEmitter)

InitializeWithEmitter sets up Dropsonde with the passed emitter, instead of creating one.

func InstrumentedHandler

func InstrumentedHandler(handler http.Handler) http.Handler

InstrumentedHandler returns a Handler pre-configured to emit HTTP server request metrics to AutowiredEmitter.

func InstrumentedRoundTripper

func InstrumentedRoundTripper(roundTripper http.RoundTripper) http.RoundTripper

InstrumentedRoundTripper returns a RoundTripper pre-configured to emit HTTP client request metrics to AutowiredEmitter.

Types

type NullEventEmitter

type NullEventEmitter struct{}

NullEventEmitter is used when no event emission is desired. See http://en.wikipedia.org/wiki/Null_Object_pattern.

func (*NullEventEmitter) Close

func (*NullEventEmitter) Close()

Close ceases emitter operations. On NullEventEmitter, it is a no-op.

func (*NullEventEmitter) Emit

Emit is called to send an event to a remote host. On NullEventEmitter, it is a no-op.

Directories

Path Synopsis
Package control is a generated protocol buffer package.
Package control is a generated protocol buffer package.
Package dropsonde_marshaller provides a tool for marshalling Envelopes to Protocol Buffer messages.
Package dropsonde_marshaller provides a tool for marshalling Envelopes to Protocol Buffer messages.
Package dropsonde_unmarshaller provides a tool for unmarshalling Envelopes from Protocol Buffer messages.
Package dropsonde_unmarshaller provides a tool for unmarshalling Envelopes from Protocol Buffer messages.
Package events is a generated protocol buffer package.
Package events is a generated protocol buffer package.
Package logs provides a simple API for sending app logs from STDOUT and STDERR through the dropsonde system.
Package logs provides a simple API for sending app logs from STDOUT and STDERR through the dropsonde system.
package metricbatcher provides a mechanism to batch counter updates into a single event.
package metricbatcher provides a mechanism to batch counter updates into a single event.
Package metrics provides a simple API for sending value and counter metrics through the dropsonde system.
Package metrics provides a simple API for sending value and counter metrics through the dropsonde system.
Messages are prepended with a HMAC SHA256 signature (the signature makes up the first 32 bytes of a signed message; the remainder is the original message in cleartext).
Messages are prepended with a HMAC SHA256 signature (the signature makes up the first 32 bytes of a signed message; the remainder is the original message in cleartext).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL