loggregator

package module
v9.2.1 Latest Latest
Warning

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

 Go to latest Published: Apr 19, 2024 License: Apache-2.0 Imports: 20 Imported by: 18

README

go-loggregator

GoDoc

This is a golang client library for Loggregator.

If you have any questions, or want to get attention for a PR or issue please reach out on the #logging-and-metrics channel in the cloudfoundry slack

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/v9"

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

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 

func (c *EnvelopeStreamConnector) Stream(ctx context.Context, req *loggregator_v2.EgressBatchRequest) EnvelopeStream

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 GatewayLogger 

type GatewayLogger interface {
	Printf(format string, v ...interface{})
	Panicf(format string, v ...interface{})
}

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 

func (c *IngressClient) Emit(e *loggregator_v2.Envelope)

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 

func (d *OneToOneEnvelopeBatch) Next() []*loggregator_v2.Envelope

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 

func (d *OneToOneEnvelopeBatch) Set(data []*loggregator_v2.Envelope)

Set inserts the given V2 envelope into the diode.

func (*OneToOneEnvelopeBatch) TryNext 

func (d *OneToOneEnvelopeBatch) TryNext() ([]*loggregator_v2.Envelope, bool)

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 

func (c *RLPGatewayClient) Stream(ctx context.Context, req *loggregator_v2.EgressBatchRequest) EnvelopeStream

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 GatewayLogger) RLPGatewayClientOption

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

func WithRLPGatewayErrChan 

func WithRLPGatewayErrChan(errChan chan error) RLPGatewayClientOption

WithRLPGatewayErrChan returns a RLPGatewayClientOption to configure an error channel to communicate errors when the client exceeds max retries

func WithRLPGatewayHTTPClient 

func WithRLPGatewayHTTPClient(d Doer) RLPGatewayClientOption

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

func WithRLPGatewayMaxRetries 

func WithRLPGatewayMaxRetries(r int) RLPGatewayClientOption

WithRLPGatewayMaxRetries returns a RLPGatewayClientOption to configure how many times the client will attempt to connect to the RLP gateway before giving up.

Source Files

View all Source files

Directories

Path Synopsis
Pacakge rfc5424 is a library for parsing and serializing RFC-5424 structured syslog messages.
 Pacakge rfc5424 is a library for parsing and serializing RFC-5424 structured syslog messages.
rpc
loggregator_v2
Package v1 provides a client to connect with the loggregtor v1 API
 Package v1 provides a client to connect with the loggregtor v1 API

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.