README

go-loggregator

GoDoc travis slack.cloudfoundry.org

This is a golang client library for Loggregator.

Versions

At present, Loggregator supports two API versions: v1 (UDP) and v2 (gRPC). This library provides clients for both versions.

Note that this library is also versioned. Its versions have no relation to the Loggregator API.

Usage

This repository should be imported as:

import loggregator "code.cloudfoundry.org/go-loggregator"

Examples

To build the examples, cd into the directory of the example and run go build

V1 Ingress

Emits envelopes to metron using dropsonde.

V2 Ingress

Emits envelopes to metron using the V2 loggregator-api.

Required Environment Variables:

  • CA_CERT_PATH
  • CERT_PATH
  • KEY_PATH
Runtime Stats

Emits information about the running Go proccess using a V2 ingress client.

Required Environment Variables:

  • CA_CERT_PATH
  • CERT_PATH
  • KEY_PATH
Envelope Stream Connector

Reads envelopes from the Loggregator API (e.g. Reverse Log Proxy).

Required Environment Variables:

  • CA_CERT_PATH
  • CERT_PATH
  • KEY_PATH
  • LOGS_API_ADDR
  • SHARD_ID
Expand ▾ Collapse ▴

Documentation

Overview

Package loggregator provides clients to send data to the Loggregator v1 and v2 API.

The v2 API distinguishes itself from the v1 API on three counts:

1) it uses gRPC, 2) it uses a streaming connection, and 3) it supports batching to improve performance.

The code here provides a generic interface into the two APIs. Clients who prefer more fine grained control may generate their own code using the protobuf and gRPC service definitions found at: github.com/cloudfoundry/loggregator-api.

Note that on account of the client using batching wherein multiple messages may be sent at once, there is no meaningful error return value available. Each of the methods below make a best-effort at message delivery. Even in the event of a failed send, the client will not block callers.

In general, use IngressClient for communicating with Loggregator's v2 API. For Loggregator's v1 API, see v1/client.go.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewEgressTLSConfig

func NewEgressTLSConfig(caPath, certPath, keyPath string) (*tls.Config, error)

NewEgressTLSConfig provides a convenient means for creating a *tls.Config which uses the CA, cert, and key for the egress endpoint.

func NewIngressTLSConfig

func NewIngressTLSConfig(caPath, certPath, keyPath string) (*tls.Config, error)

NewIngressTLSConfig provides a convenient means for creating a *tls.Config which uses the CA, cert, and key for the ingress endpoint.

func WithEnvelopeTag

func WithEnvelopeTag(name, value string) func(proto.Message)

WithEnvelopeTag adds a tag to the envelope.

func WithEnvelopeTags

func WithEnvelopeTags(tags map[string]string) func(proto.Message)

WithEnvelopeTags adds tag information that can be text, integer, or decimal to the envelope. WithEnvelopeTags expects a single call with a complete map and will overwrite if called a second time.

Types

type Doer

type Doer interface {
	// Do is a implementation of the http.Client's Do method.
	Do(*http.Request) (*http.Response, error)
}

Doer is used to make HTTP requests to the RLP Gateway.

type EmitCounterOption

type EmitCounterOption func(proto.Message)

EmitCounterOption is the option type passed into EmitCounter.

func WithCounterAppInfo

func WithCounterAppInfo(appID string, index int) EmitCounterOption

WithCounterAppInfo configures an envelope with both the app ID and index. Exists for backward compatability. If possible, use WithCounterSourceInfo instead.

func WithCounterSourceInfo

func WithCounterSourceInfo(sourceID, instanceID string) EmitCounterOption

WithCounterSourceInfo configures an envelope with both the app ID and source ID.

func WithDelta

func WithDelta(d uint64) EmitCounterOption

WithDelta is an option that sets the delta for a counter.

func WithTotal

func WithTotal(t uint64) EmitCounterOption

WithTotal is an option that sets the total for a counter.

type EmitEventOption

type EmitEventOption func(proto.Message)

EmitEventOption is the option type passed into EmitEvent.

func WithEventSourceInfo

func WithEventSourceInfo(sourceID, instanceID string) EmitEventOption

WithEventSourceInfo configures an envelope with both the source and instance IDs.

type EmitGaugeOption

type EmitGaugeOption func(proto.Message)

EmitGaugeOption is the option type passed into EmitGauge.

func WithGaugeAppInfo

func WithGaugeAppInfo(appID string, index int) EmitGaugeOption

WithGaugeAppInfo configures an envelope with both the app ID and index. Exists for backward compatability. If possible, use WithGaugeSourceInfo instead.

func WithGaugeSourceInfo

func WithGaugeSourceInfo(sourceID, instanceID string) EmitGaugeOption

WithGaugeSourceInfo configures an envelope with both the source ID and instance ID.

func WithGaugeValue

func WithGaugeValue(name string, value float64, unit string) EmitGaugeOption

WithGaugeValue adds a gauge information. For example, to send information about current CPU usage, one might use:

WithGaugeValue("cpu", 3.0, "percent")

An number of calls to WithGaugeValue may be passed into EmitGauge. If there are duplicate names in any of the options, i.e., "cpu" and "cpu", then the last EmitGaugeOption will take precedence.

type EmitLogOption

type EmitLogOption func(proto.Message)

EmitLogOption is the option type passed into EmitLog

func WithAppInfo

func WithAppInfo(appID, sourceType, sourceInstance string) EmitLogOption

WithAppInfo configures the meta data associated with emitted data. Exists for backward compatability. If possible, use WithSourceInfo instead.

func WithSourceInfo

func WithSourceInfo(sourceID, sourceType, sourceInstance string) EmitLogOption

WithSourceInfo configures the meta data associated with emitted data

func WithStdout

func WithStdout() EmitLogOption

WithStdout sets the output type to stdout. Without using this option, all data is assumed to be stderr output.

type EmitTimerOption

type EmitTimerOption func(proto.Message)

EmitTimerOption is the option type passed into EmitTimer.

func WithTimerSourceInfo

func WithTimerSourceInfo(sourceID, instanceID string) EmitTimerOption

WithTimerSourceInfo configures an envelope with both the source and instance IDs.

type EnvelopeStream

type EnvelopeStream func() []*loggregator_v2.Envelope

EnvelopeStream returns batches of envelopes. It blocks until its context is done or a batch of envelopes is available.

type EnvelopeStreamConnector

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

EnvelopeStreamConnector provides a way to connect to loggregator and consume a stream of envelopes. It handles reconnecting and provides a stream for the lifecycle of the given context. It should be created with the NewEnvelopeStreamConnector constructor.

func NewEnvelopeStreamConnector

func NewEnvelopeStreamConnector(
	addr string,
	t *tls.Config,
	opts ...EnvelopeStreamOption,
) *EnvelopeStreamConnector

NewEnvelopeStreamConnector creates a new EnvelopeStreamConnector. Its TLS configuration must share a CA with the loggregator server.

func (*EnvelopeStreamConnector) Stream

Stream returns a new EnvelopeStream for the given context and request. The lifecycle of the EnvelopeStream is managed by the given context. If the underlying gRPC stream dies, it attempts to reconnect until the context is done.

type EnvelopeStreamOption

type EnvelopeStreamOption func(*EnvelopeStreamConnector)

EnvelopeStreamOption configures a EnvelopeStreamConnector.

func WithEnvelopeStreamBuffer

func WithEnvelopeStreamBuffer(size int, alerter func(missed int)) EnvelopeStreamOption

WithEnvelopeStreamBuffer enables the EnvelopeStream to read more quickly from the stream. It puts each envelope in a buffer that overwrites data if it is not being drained quick enough. If the buffer drops data, the 'alerter' function will be invoked with the number of envelopes dropped.

func WithEnvelopeStreamConnectorDialOptions

func WithEnvelopeStreamConnectorDialOptions(opts ...grpc.DialOption) EnvelopeStreamOption

WithEnvelopeStreamConnectorDialOptions allows for configuration of grpc dial options.

func WithEnvelopeStreamLogger

func WithEnvelopeStreamLogger(l Logger) EnvelopeStreamOption

WithEnvelopeStreamLogger allows for the configuration of a logger. By default, the logger is disabled.

type IngressClient

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

IngressClient represents an emitter into loggregator. It should be created with the NewIngressClient constructor.

func NewIngressClient

func NewIngressClient(tlsConfig *tls.Config, opts ...IngressOption) (*IngressClient, error)

NewIngressClient creates a v2 loggregator client. Its TLS configuration must share a CA with the loggregator server.

func (*IngressClient) CloseSend

func (c *IngressClient) CloseSend() error

CloseSend will flush the envelope buffers and close the stream to the ingress server. This method will block until the buffers are flushed.

func (*IngressClient) Emit

Emit sends an envelope. It will sent within a batch.

func (*IngressClient) EmitCounter

func (c *IngressClient) EmitCounter(name string, opts ...EmitCounterOption)

EmitCounter sends a counter envelope with a delta of 1.

func (*IngressClient) EmitEvent

func (c *IngressClient) EmitEvent(ctx context.Context, title, body string, opts ...EmitEventOption) error

EmitEvent sends an Event envelope.

func (*IngressClient) EmitGauge

func (c *IngressClient) EmitGauge(opts ...EmitGaugeOption)

EmitGauge sends the configured gauge values to loggregator. If no EmitGaugeOption values are present, the client will emit an empty gauge.

func (*IngressClient) EmitLog

func (c *IngressClient) EmitLog(message string, opts ...EmitLogOption)

EmitLog sends a message to loggregator.

func (*IngressClient) EmitTimer

func (c *IngressClient) EmitTimer(name string, start, stop time.Time, opts ...EmitTimerOption)

EmitTimer sends a timer envelope with the given name, start time and stop time.

type IngressOption

type IngressOption func(*IngressClient)

IngressOption is the type of a configurable client option.

func WithAddr

func WithAddr(addr string) IngressOption

WithAddr allows for the configuration of the loggregator v2 address. The value to defaults to localhost:3458, which happens to be the default address in the loggregator server.

func WithBatchFlushInterval

func WithBatchFlushInterval(d time.Duration) IngressOption

WithBatchFlushInterval allows for the configuration of the maximum time to wait before sending a batch of messages. Note that the batch interval may be triggered prior to the batch reaching the configured maximum size.

func WithBatchMaxSize

func WithBatchMaxSize(maxSize uint) IngressOption

WithBatchMaxSize allows for the configuration of the number of messages to collect before emitting them into loggregator. By default, its value is 100 messages.

Note that aside from batch size, messages will be flushed from the client into loggregator at a fixed interval to ensure messages are not held for an undue amount of time before being sent. In other words, even if the client has not yet achieved the maximum batch size, the batch interval may trigger the messages to be sent.

func WithContext

func WithContext(ctx context.Context) IngressOption

WithContext configures the context that manages the lifecycle for the gRPC connection. It defaults to a context.Background().

func WithDialOptions

func WithDialOptions(opts ...grpc.DialOption) IngressOption

func WithLogger

func WithLogger(l Logger) IngressOption

WithLogger allows for the configuration of a logger. By default, the logger is disabled.

func WithTag

func WithTag(name, value string) IngressOption

WithTag allows for the configuration of arbitrary string value metadata which will be included in all data sent to Loggregator

type Logger

type Logger interface {
	Printf(string, ...interface{})
	Panicf(string, ...interface{})
}

Logger declares the minimal logging interface used within the v2 client

type OneToOneEnvelopeBatch

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

OneToOneEnvelopeBatch diode is optimized for a single writer and a single reader

func NewOneToOneEnvelopeBatch

func NewOneToOneEnvelopeBatch(size int, alerter gendiodes.Alerter, opts ...gendiodes.PollerConfigOption) *OneToOneEnvelopeBatch

NewOneToOneEnvelopeBatch initializes a new one to one diode for envelope batches of a given size and alerter. The alerter is called whenever data is dropped with an integer representing the number of envelope batches that were dropped.

func (*OneToOneEnvelopeBatch) Next

Next will return the next envelope batch to be read from the diode. If the diode is empty this method will block until anenvelope is available to be read.

func (*OneToOneEnvelopeBatch) Set

Set inserts the given V2 envelope into the diode.

func (*OneToOneEnvelopeBatch) TryNext

TryNext returns the next envelope batch to be read from the diode. If the diode is empty it will return a nil envelope and false for the bool.

type RLPGatewayClient

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

func NewRLPGatewayClient

func NewRLPGatewayClient(addr string, opts ...RLPGatewayClientOption) *RLPGatewayClient

func (*RLPGatewayClient) Stream

Stream returns a new EnvelopeStream for the given context and request. The lifecycle of the EnvelopeStream is managed by the given context. If the underlying SSE stream dies, it attempts to reconnect until the context is done. Any errors are logged via the client's logger.

type RLPGatewayClientOption

type RLPGatewayClientOption func(*RLPGatewayClient)

RLPGatewayClientOption is the type of a configurable client option.

func WithRLPGatewayClientLogger

func WithRLPGatewayClientLogger(log *log.Logger) RLPGatewayClientOption

WithRLPGatewayClientLogger returns a RLPGatewayClientOption to configure the logger of the RLPGatewayClient. It defaults to a silent logger.

func WithRLPGatewayHTTPClient

func WithRLPGatewayHTTPClient(d Doer) RLPGatewayClientOption

WithRLPGatewayClientLogger returns a RLPGatewayClientOption to configure the HTTP client. It defaults to the http.DefaultClient.

Directories

Path Synopsis
conversion
examples/envelope_stream_connector
examples/rlp_gateway
examples/runtime_stats
examples/v1_ingress
examples/v2_ingress
pulseemitter
rpc/loggregator_v2
runtimeemitter
v1 Package v1 provides a client to connect with the loggregtor v1 API Loggregator's v1 client library is better known to the Cloud Foundry community as Dropsonde (github.com/cloudfoundry/dropsonde).