The highest tagged major version is
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.
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 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 ¶
- func NewEgressTLSConfig(caPath, certPath, keyPath string) (*tls.Config, error)
- func NewIngressTLSConfig(caPath, certPath, keyPath string) (*tls.Config, error)
- func WithEnvelopeTag(name, value string) func(proto.Message)
- func WithEnvelopeTags(tags map[string]string) func(proto.Message)
- type EmitCounterOption
- type EmitEventOption
- type EmitGaugeOption
- type EmitLogOption
- type EnvelopeStream
- type EnvelopeStreamConnector
- type EnvelopeStreamOption
- type IngressClient
- func (c *IngressClient) CloseSend() error
- func (c *IngressClient) EmitCounter(name string, opts ...EmitCounterOption)
- func (c *IngressClient) EmitEvent(title, body string, opts ...EmitEventOption)
- func (c *IngressClient) EmitGauge(opts ...EmitGaugeOption)
- func (c *IngressClient) EmitLog(message string, opts ...EmitLogOption)
- type IngressOption
- type Logger
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewEgressTLSConfig ¶
NewEgressTLSConfig provides a convenient means for creating a *tls.Config which uses the CA, cert, and key for the egress endpoint.
func NewIngressTLSConfig ¶
NewIngressTLSConfig provides a convenient means for creating a *tls.Config which uses the CA, cert, and key for the ingress endpoint.
func WithEnvelopeTag ¶
WithEnvelopeTag adds a tag to the envelope.
Types ¶
type EmitCounterOption ¶
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 EmitEventOption ¶
EmitEventOption is the option type passed into EmitEvent.
type EmitGaugeOption ¶
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.
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 ¶
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 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
NewEnvelopeStream 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 WithEnvelopeStreamBalancer ¶
func WithEnvelopeStreamBalancer(b grpc.Balancer) EnvelopeStreamOption
WithEnvelopeStreamBalancer sets the balancer for connecting to Loggregator endpoints. It defaults to a RoundRobin load balancer with a DNS resolver.
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) 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(title, body string, opts ...EmitEventOption)
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.
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 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
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
rpc
|
|
|
loggregator_v2
Package loggregator_v2 is a generated protocol buffer package.
|
Package loggregator_v2 is a generated protocol buffer 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).
|
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). |