loggregator

README

go-loggregator

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. Presently, v2.0.0 is the most recent release.

Usage

This repository should be imported as:

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

Example

Example implementation of the client is provided in examples/main.go.

Build the example client by running go build -o client main.go

Collocate the client with a metron agent and set the following environment variables: CA_CERT_PATH, CERT_PATH, KEY_PATH

Documentation

Overview

Package v2 provides a client to send data to the Loggregator 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 v2 API. 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.

Index

• func NewEgressTLSConfig(caPath, certPath, keyPath string) (*tls.Config, error)
• func NewIngressTLSConfig(caPath, certPath, keyPath string) (*tls.Config, error)
• func WithEnvelopeDecimalTag(name string, value float64) func(*loggregator_v2.Envelope)
• func WithEnvelopeIntegerTag(name string, value int64) func(*loggregator_v2.Envelope)
• func WithEnvelopeStringTag(name, value string) func(*loggregator_v2.Envelope)
• type EgressClient
  • func NewEgressClient(addr string, c *tls.Config) (*EgressClient, io.Closer, error)
  • func (c *EgressClient) Receiver(ctx context.Context, in *loggregator_v2.EgressRequest) (loggregator_v2.Egress_ReceiverClient, error)
• type EmitCounterOption
  • func WithDelta(d uint64) EmitCounterOption
• type EmitGaugeOption
  • func WithGaugeAppInfo(appID string) EmitGaugeOption
  • func WithGaugeTags(tags map[string]string) EmitGaugeOption
  • func WithGaugeValue(name string, value float64, unit string) EmitGaugeOption
• type EmitLogOption
  • func WithAppInfo(appID, sourceType, sourceInstance string) EmitLogOption
  • func WithStdout() EmitLogOption
• type IngressClient
  • func NewIngressClient(tlsConfig *tls.Config, opts ...IngressOption) (*IngressClient, error)
  • func (c *IngressClient) EmitCounter(name string, opts ...EmitCounterOption)
  • func (c *IngressClient) EmitGauge(opts ...EmitGaugeOption)
  • func (c *IngressClient) EmitLog(message string, opts ...EmitLogOption)
• type IngressOption
  • func WithAddr(addr string) IngressOption
  • func WithBatchFlushInterval(d time.Duration) IngressOption
  • func WithBatchMaxSize(maxSize uint) IngressOption
  • func WithDecimalTag(name string, value float64) IngressOption
  • func WithIntegerTag(name string, value int64) IngressOption
  • func WithLogger(l Logger) IngressOption
  • func WithStringTag(name, value string) IngressOption
• type Logger
• type RawIngressClient
  • func NewRawIngressClient(addr string, tlsConfig *tls.Config) (*RawIngressClient, error)
  • func (c *RawIngressClient) Emit(e []*loggregator_v2.Envelope) error

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 WithEnvelopeDecimalTag

func WithEnvelopeDecimalTag(name string, value float64) func(*loggregator_v2.Envelope)

WithEnvelopeDecimalTag adds a decimal tag to the envelope.

func WithEnvelopeIntegerTag

func WithEnvelopeIntegerTag(name string, value int64) func(*loggregator_v2.Envelope)

WithEnvelopeIntegerTag adds a integer tag to the envelope.

func WithEnvelopeStringTag

func WithEnvelopeStringTag(name, value string) func(*loggregator_v2.Envelope)

WithEnvelopeStringTag adds a string tag to the envelope.

Types

type EgressClient

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

func NewEgressClient

func NewEgressClient(addr string, c *tls.Config) (*EgressClient, io.Closer, error)

NewEgressClient creates a new EgressClient for the given addr and TLS configuration.

func (*EgressClient) Receiver

func (c *EgressClient) Receiver(ctx context.Context, in *loggregator_v2.EgressRequest) (loggregator_v2.Egress_ReceiverClient, error)

Receiver wraps the created EgressClient's Receiver method.

type EmitCounterOption

type EmitCounterOption func(*loggregator_v2.Envelope)

EmitCounterOption is the option type passed into EmitCounter.

func WithDelta

func WithDelta(d uint64) EmitCounterOption

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

type EmitGaugeOption

type EmitGaugeOption func(*loggregator_v2.Envelope)

EmitGaugeOption is the option type passed into EmitGauge

func WithGaugeAppInfo

func WithGaugeAppInfo(appID string) EmitGaugeOption

WithGaugeAppInfo configures an ID associated with the gauge

func WithGaugeTags

func WithGaugeTags(tags map[string]string) EmitGaugeOption

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

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(*loggregator_v2.Envelope)

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

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

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

EmitCounter sends a counter envelope with a delta of 1.

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.

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 WithDecimalTag

func WithDecimalTag(name string, value float64) IngressOption

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

func WithIntegerTag

func WithIntegerTag(name string, value int64) IngressOption

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

func WithLogger

func WithLogger(l Logger) IngressOption

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

func WithStringTag

func WithStringTag(name, value string) IngressOption

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

Logger declares the minimal logging interface used within the v2 client

type RawIngressClient

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

RawIngressClient is an emitter of bare envelopes to loggregator. Only use this if you do not want the tagging and batching features of ingress client.

func NewRawIngressClient

func NewRawIngressClient(addr string, tlsConfig *tls.Config) (*RawIngressClient, error)

NewRawIngressClient creates a new RawIngressClient.

func (*RawIngressClient) Emit

func (c *RawIngressClient) Emit(e []*loggregator_v2.Envelope) error

Emit will send the batch of envelopes down the current stream to the loggregator system. It will not alter any of the envelopes in any way.