statsd

package
v5.5.0 Latest Latest
Warning

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

 Go to latest Published: Jan 24, 2024 License: MIT Imports: 19 Imported by: 184

README

Overview

Package statsd provides a Go dogstatsd client. Dogstatsd extends Statsd, adding tags and histograms.

Documentation

Overview

Package statsd provides a Go dogstatsd client. Dogstatsd extends the popular statsd, adding tags and histograms and pushing upstream to Datadog.

Refer to http://docs.datadoghq.com/guides/dogstatsd/ for information about DogStatsD.

statsd is based on go-statsd-client.

Index

Constants

View Source 
const DefaultMaxAgentPayloadSize = 8192

DefaultMaxAgentPayloadSize is the default maximum payload size the agent can receive. This can be adjusted by changing dogstatsd_buffer_size in the agent configuration file datadog.yaml. This is also used as the optimal payload size for UDS datagrams.

View Source 
const DefaultUDPBufferPoolSize = 2048

DefaultUDPBufferPoolSize is the default size of the buffer pool for UDP clients.

View Source 
const DefaultUDSBufferPoolSize = 512

DefaultUDSBufferPoolSize is the default size of the buffer pool for UDS clients.

View Source 
const ErrNoClient = noClientErr("statsd client is nil")

ErrNoClient is returned if statsd reporting methods are invoked on a nil client.

View Source 
const InvalidTimestamp = invalidTimestampErr("invalid timestamp")

InvalidTimestamp is returned if a provided timestamp is invalid.

View Source 
const MaxUDPPayloadSize = 65467

MaxUDPPayloadSize defines the maximum payload size for a UDP datagram. Its value comes from the calculation: 65535 bytes Max UDP datagram size - 8byte UDP header - 60byte max IP headers any number greater than that will see frames being cut out.

View Source 
const OptimalUDPPayloadSize = 1432

OptimalUDPPayloadSize defines the optimal payload size for a UDP datagram, 1432 bytes is optimal for regular networks with an MTU of 1500 so datagrams don't get fragmented. It's generally recommended not to fragment UDP datagrams as losing a single fragment will cause the entire datagram to be lost.

View Source 
const UnixAddressDatagramPrefix = "unixgram://"

UnixDatagramAddressPrefix holds the prefix to use to enable Unix Domain Socket datagram traffic instead of UDP.

View Source 
const UnixAddressPrefix = "unix://"

UnixAddressPrefix holds the prefix to use to enable Unix Domain Socket traffic instead of UDP. The type of the socket will be guessed.

View Source 
const UnixAddressStreamPrefix = "unixstream://"

UnixAddressStreamPrefix holds the prefix to use to enable Unix Domain Socket stream traffic instead of UDP.

View Source 
const WindowsPipeAddressPrefix = `\\.\pipe\`

WindowsPipeAddressPrefix holds the prefix to use to enable Windows Named Pipes traffic instead of UDP.

Variables

View Source 
var (
	AddressPrefixes = []string{UnixAddressPrefix, UnixAddressDatagramPrefix, UnixAddressStreamPrefix, WindowsPipeAddressPrefix}
)

Functions

func LoggingErrorHandler added in v5.4.0 

func LoggingErrorHandler(err error)

Types

type Client 

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

A Client is a handle for sending messages to dogstatsd. It is safe to use one Client from multiple goroutines simultaneously.

func CloneWithExtraOptions 

func CloneWithExtraOptions(c *Client, options ...Option) (*Client, error)

CloneWithExtraOptions create a new Client with extra options

func New 

func New(addr string, options ...Option) (*Client, error)

New returns a pointer to a new Client given an addr in the format "hostname:port" for UDP, "unix:///path/to/socket" for UDS or "\\.\pipe\path\to\pipe" for Windows Named Pipes.

func NewWithWriter 

func NewWithWriter(w io.WriteCloser, options ...Option) (*Client, error)

NewWithWriter creates a new Client with given writer. Writer is a io.WriteCloser

func (*Client) Close 

func (c *Client) Close() error

Close the client connection.

func (*Client) Count 

func (c *Client) Count(name string, value int64, tags []string, rate float64) error

Count tracks how many times something happened per second.

func (*Client) CountWithTimestamp added in v5.2.0 

func (c *Client) CountWithTimestamp(name string, value int64, tags []string, rate float64, timestamp time.Time) error

CountWithTimestamp tracks how many times something happened at the given second. BETA - Please contact our support team for more information to use this feature: https://www.datadoghq.com/support/ The value will bypass any aggregation on the client side and agent side, this is useful when sending points in the past.

Minimum Datadog Agent version: 7.40.0

func (*Client) Decr 

func (c *Client) Decr(name string, tags []string, rate float64) error

Decr is just Count of -1

func (*Client) Distribution 

func (c *Client) Distribution(name string, value float64, tags []string, rate float64) error

Distribution tracks the statistical distribution of a set of values across your infrastructure.

func (*Client) Event 

func (c *Client) Event(e *Event) error

Event sends the provided Event.

func (*Client) Flush 

func (c *Client) Flush() error

Flush forces a flush of all the queued dogstatsd payloads This method is blocking and will not return until everything is sent through the network. In mutexMode, this will also block sampling new data to the client while the workers and sender are flushed.

func (*Client) Gauge 

func (c *Client) Gauge(name string, value float64, tags []string, rate float64) error

Gauge measures the value of a metric at a particular time.

func (*Client) GaugeWithTimestamp added in v5.2.0 

func (c *Client) GaugeWithTimestamp(name string, value float64, tags []string, rate float64, timestamp time.Time) error

GaugeWithTimestamp measures the value of a metric at a given time. BETA - Please contact our support team for more information to use this feature: https://www.datadoghq.com/support/ The value will bypass any aggregation on the client side and agent side, this is useful when sending points in the past.

Minimum Datadog Agent version: 7.40.0

func (*Client) GetTelemetry 

func (c *Client) GetTelemetry() Telemetry

GetTelemetry return the telemetry metrics for the client since it started.

func (*Client) GetTransport added in v5.4.0 

func (c *Client) GetTransport() string

GetTransport return the name of the transport used.

func (*Client) Histogram 

func (c *Client) Histogram(name string, value float64, tags []string, rate float64) error

Histogram tracks the statistical distribution of a set of values on each host.

func (*Client) Incr 

func (c *Client) Incr(name string, tags []string, rate float64) error

Incr is just Count of 1

func (*Client) IsClosed added in v5.1.0 

func (c *Client) IsClosed() bool

IsClosed returns if the client has been closed.

func (*Client) ServiceCheck 

func (c *Client) ServiceCheck(sc *ServiceCheck) error

ServiceCheck sends the provided ServiceCheck.

func (*Client) Set 

func (c *Client) Set(name string, value string, tags []string, rate float64) error

Set counts the number of unique elements in a group.

func (*Client) SimpleEvent 

func (c *Client) SimpleEvent(title, text string) error

SimpleEvent sends an event with the provided title and text.

func (*Client) SimpleServiceCheck 

func (c *Client) SimpleServiceCheck(name string, status ServiceCheckStatus) error

SimpleServiceCheck sends an serviceCheck with the provided name and status.

func (*Client) TimeInMilliseconds 

func (c *Client) TimeInMilliseconds(name string, value float64, tags []string, rate float64) error

TimeInMilliseconds sends timing information in milliseconds. It is flushed by statsd with percentiles, mean and other info (https://github.com/etsy/statsd/blob/master/docs/metric_types.md#timing)

func (*Client) Timing 

func (c *Client) Timing(name string, value time.Duration, tags []string, rate float64) error

Timing sends timing information, it is an alias for TimeInMilliseconds

type ClientDirect added in v5.5.0 

type ClientDirect struct {
	*Client
}

ClientDirect is an *experimental* statsd client that gives direct access to some dogstatsd features.

It is not recommended to use this client in production. This client might allow you to take advantage of new features in the agent before they are released, but it might also break your application.

func NewDirect added in v5.5.0 

func NewDirect(addr string, options ...Option) (*ClientDirect, error)

NewDirect returns a pointer to a new ClientDirect given an addr in the format "hostname:port" for UDP, "unix:///path/to/socket" for UDS or "\\.\pipe\path\to\pipe" for Windows Named Pipes.

func NewDirectWithWriter added in v5.5.0 

func NewDirectWithWriter(writer io.WriteCloser, options ...Option) (*ClientDirect, error)

func (*ClientDirect) DistributionSamples added in v5.5.0 

func (c *ClientDirect) DistributionSamples(name string, values []float64, tags []string, rate float64) error

DistributionSamples is similar to Distribution, but it lets the client deals with the sampling.

The provided `rate` is the sampling rate applied by the client and will *not* be used to apply further sampling. This is recommended in high performance cases were the overhead of the statsd library might be significant and the sampling is already done by the client.

`WithMaxBufferedMetricsPerContext` is ignored when using this method.

type ClientDirectInterface added in v5.5.0 

type ClientDirectInterface interface {
	DistributionSamples(name string, values []float64, tags []string, rate float64) error
}

type ClientInterface 

type ClientInterface interface {
	// Gauge measures the value of a metric at a particular time.
	Gauge(name string, value float64, tags []string, rate float64) error

	// GaugeWithTimestamp measures the value of a metric at a given time.
	// BETA - Please contact our support team for more information to use this feature: https://www.datadoghq.com/support/
	// The value will bypass any aggregation on the client side and agent side, this is
	// useful when sending points in the past.
	//
	// Minimum Datadog Agent version: 7.40.0
	GaugeWithTimestamp(name string, value float64, tags []string, rate float64, timestamp time.Time) error

	// Count tracks how many times something happened per second.
	Count(name string, value int64, tags []string, rate float64) error

	// CountWithTimestamp tracks how many times something happened at the given second.
	// BETA - Please contact our support team for more information to use this feature: https://www.datadoghq.com/support/
	// The value will bypass any aggregation on the client side and agent side, this is
	// useful when sending points in the past.
	//
	// Minimum Datadog Agent version: 7.40.0
	CountWithTimestamp(name string, value int64, tags []string, rate float64, timestamp time.Time) error

	// Histogram tracks the statistical distribution of a set of values on each host.
	Histogram(name string, value float64, tags []string, rate float64) error

	// Distribution tracks the statistical distribution of a set of values across your infrastructure.
	//
	// It is recommended to use `WithMaxBufferedMetricsPerContext` to avoid dropping metrics at high throughput, `rate` can
	// also be used to limit the load. Both options can *not* be used together.
	Distribution(name string, value float64, tags []string, rate float64) error

	// Decr is just Count of -1
	Decr(name string, tags []string, rate float64) error

	// Incr is just Count of 1
	Incr(name string, tags []string, rate float64) error

	// Set counts the number of unique elements in a group.
	Set(name string, value string, tags []string, rate float64) error

	// Timing sends timing information, it is an alias for TimeInMilliseconds
	Timing(name string, value time.Duration, tags []string, rate float64) error

	// TimeInMilliseconds sends timing information in milliseconds.
	// It is flushed by statsd with percentiles, mean and other info (https://github.com/etsy/statsd/blob/master/docs/metric_types.md#timing)
	TimeInMilliseconds(name string, value float64, tags []string, rate float64) error

	// Event sends the provided Event.
	Event(e *Event) error

	// SimpleEvent sends an event with the provided title and text.
	SimpleEvent(title, text string) error

	// ServiceCheck sends the provided ServiceCheck.
	ServiceCheck(sc *ServiceCheck) error

	// SimpleServiceCheck sends an serviceCheck with the provided name and status.
	SimpleServiceCheck(name string, status ServiceCheckStatus) error

	// Close the client connection.
	Close() error

	// Flush forces a flush of all the queued dogstatsd payloads.
	Flush() error

	// IsClosed returns if the client has been closed.
	IsClosed() bool

	// GetTelemetry return the telemetry metrics for the client since it started.
	GetTelemetry() Telemetry
}

ClientInterface is an interface that exposes the common client functions for the purpose of being able to provide a no-op client or even mocking. This can aid downstream users' with their testing.

type ErrorHandler added in v5.4.0 

type ErrorHandler func(error)

type ErrorInputChannelFull added in v5.4.0 

type ErrorInputChannelFull struct {
	Metric      metric
	ChannelSize int
	Msg         string
}

func (ErrorInputChannelFull) Error added in v5.4.0 

func (e ErrorInputChannelFull) Error() string

type ErrorSenderChannelFull added in v5.4.0 

type ErrorSenderChannelFull struct {
	LostElements int
	ChannelSize  int
	Msg          string
}

func (*ErrorSenderChannelFull) Error added in v5.4.0 

func (e *ErrorSenderChannelFull) Error() string

type Event 

type Event struct {
	// Title of the event.  Required.
	Title string
	// Text is the description of the event.
	Text string
	// Timestamp is a timestamp for the event.  If not provided, the dogstatsd
	// server will set this to the current time.
	Timestamp time.Time
	// Hostname for the event.
	Hostname string
	// AggregationKey groups this event with others of the same key.
	AggregationKey string
	// Priority of the event.  Can be statsd.Low or statsd.Normal.
	Priority EventPriority
	// SourceTypeName is a source type for the event.
	SourceTypeName string
	// AlertType can be statsd.Info, statsd.Error, statsd.Warning, or statsd.Success.
	// If absent, the default value applied by the dogstatsd server is Info.
	AlertType EventAlertType
	// Tags for the event.
	Tags []string
}

An Event is an object that can be posted to your DataDog event stream.

func NewEvent 

func NewEvent(title, text string) *Event

NewEvent creates a new event with the given title and text. Error checking against these values is done at send-time, or upon running e.Check.

func (*Event) Check 

func (e *Event) Check() error

Check verifies that an event is valid.

type EventAlertType 

type EventAlertType string

EventAlertType is the alert type for events 

const (
	// Info is the "info" AlertType for events
	Info EventAlertType = "info"
	// Error is the "error" AlertType for events
	Error EventAlertType = "error"
	// Warning is the "warning" AlertType for events
	Warning EventAlertType = "warning"
	// Success is the "success" AlertType for events
	Success EventAlertType = "success"
)

type EventPriority 

type EventPriority string

EventPriority is the event priority for events 

const (
	// Normal is the "normal" Priority for events
	Normal EventPriority = "normal"
	// Low is the "low" Priority for events
	Low EventPriority = "low"
)

type MessageTooLongError added in v5.1.0 

type MessageTooLongError struct{}

MessageTooLongError is an error returned when a sample, event or service check is too large once serialized. See WithMaxBytesPerPayload option for more details.

func (MessageTooLongError) Error added in v5.1.0 

func (e MessageTooLongError) Error() string

type NoOpClient 

type NoOpClient struct{}

NoOpClient is a statsd client that does nothing. Can be useful in testing situations for library users.

func (*NoOpClient) Close 

func (n *NoOpClient) Close() error

Close does nothing and returns nil

func (*NoOpClient) Count 

func (n *NoOpClient) Count(name string, value int64, tags []string, rate float64) error

Count does nothing and returns nil

func (*NoOpClient) CountWithTimestamp added in v5.2.0 

func (n *NoOpClient) CountWithTimestamp(name string, value int64, tags []string, rate float64, timestamp time.Time) error

CountWithTimestamp does nothing and returns nil

func (*NoOpClient) Decr 

func (n *NoOpClient) Decr(name string, tags []string, rate float64) error

Decr does nothing and returns nil

func (*NoOpClient) Distribution 

func (n *NoOpClient) Distribution(name string, value float64, tags []string, rate float64) error

Distribution does nothing and returns nil

func (*NoOpClient) Event 

func (n *NoOpClient) Event(e *Event) error

Event does nothing and returns nil

func (*NoOpClient) Flush 

func (n *NoOpClient) Flush() error

Flush does nothing and returns nil

func (*NoOpClient) Gauge 

func (n *NoOpClient) Gauge(name string, value float64, tags []string, rate float64) error

Gauge does nothing and returns nil

func (*NoOpClient) GaugeWithTimestamp added in v5.2.0 

func (n *NoOpClient) GaugeWithTimestamp(name string, value float64, tags []string, rate float64, timestamp time.Time) error

GaugeWithTimestamp does nothing and returns nil

func (*NoOpClient) GetTelemetry added in v5.1.0 

func (n *NoOpClient) GetTelemetry() Telemetry

GetTelemetry does nothing and returns an empty Telemetry

func (*NoOpClient) Histogram 

func (n *NoOpClient) Histogram(name string, value float64, tags []string, rate float64) error

Histogram does nothing and returns nil

func (*NoOpClient) Incr 

func (n *NoOpClient) Incr(name string, tags []string, rate float64) error

Incr does nothing and returns nil

func (*NoOpClient) IsClosed added in v5.1.0 

func (n *NoOpClient) IsClosed() bool

IsClosed does nothing and return false

func (*NoOpClient) ServiceCheck 

func (n *NoOpClient) ServiceCheck(sc *ServiceCheck) error

ServiceCheck does nothing and returns nil

func (*NoOpClient) Set 

func (n *NoOpClient) Set(name string, value string, tags []string, rate float64) error

Set does nothing and returns nil

func (*NoOpClient) SimpleEvent 

func (n *NoOpClient) SimpleEvent(title, text string) error

SimpleEvent does nothing and returns nil

func (*NoOpClient) SimpleServiceCheck 

func (n *NoOpClient) SimpleServiceCheck(name string, status ServiceCheckStatus) error

SimpleServiceCheck does nothing and returns nil

func (*NoOpClient) TimeInMilliseconds 

func (n *NoOpClient) TimeInMilliseconds(name string, value float64, tags []string, rate float64) error

TimeInMilliseconds does nothing and returns nil

func (*NoOpClient) Timing 

func (n *NoOpClient) Timing(name string, value time.Duration, tags []string, rate float64) error

Timing does nothing and returns nil

type NoOpClientDirect added in v5.5.0 

type NoOpClientDirect struct {
	NoOpClient
}

NoOpClientDirect implements ClientDirectInterface and does nothing.

func (*NoOpClientDirect) DistributionSamples added in v5.5.0 

func (n *NoOpClientDirect) DistributionSamples(name string, values []float64, tags []string, rate float64) error

DistributionSamples does nothing and returns nil

type Option 

type Option func(*Options) error

Option is a client option. Can return an error if validation fails.

func WithAggregationInterval 

func WithAggregationInterval(interval time.Duration) Option

WithAggregationInterval sets the interval at which aggregated metrics are flushed. See WithClientSideAggregation and WithExtendedClientSideAggregation for more.

The default interval is 2s. The interval must divide the Agent reporting period (default=10s) evenly to reduce "aliasing" that can cause values to appear irregular/spiky.

For example a 3s aggregation interval will create spikes in the final graph: a application sending a count metric that increments at a constant 1000 time per second will appear noisy with an interval of 3s. This is because client-side aggregation would report every 3 seconds, while the agent is reporting every 10 seconds. This means in each agent bucket, the values are: 9000, 9000, 12000.

func WithBufferFlushInterval 

func WithBufferFlushInterval(bufferFlushInterval time.Duration) Option

WithBufferFlushInterval sets the interval after which the current buffer is flushed.

A buffers are used to serialized data, they're flushed either when full (see WithMaxBytesPerPayload) or when it's been open for longer than this interval.

With apps sending a high number of metrics/events/service_checks the interval rarely timeout. But with slow sending apps increasing this value will reduce the number of payload sent on the wire as more data is serialized in the same payload.

Default is 100ms

func WithBufferPoolSize 

func WithBufferPoolSize(bufferPoolSize int) Option

WithBufferPoolSize sets the size of the pool of buffers used to serialized metrics, events and service_checks.

The default, 0, will set the option to the optimal size for the transport protocol used: 2048 for UDP and named pipe and 512 for UDS.

func WithChannelMode 

func WithChannelMode() Option

WithChannelMode make the client use channels to receive metrics

This determines how the client receive metrics from the app (for example when calling the `Gauge()` method). The client will either drop the metrics if its buffers are full (WithChannelMode option) or block the caller until the metric can be handled (WithMutexMode option). By default, the client use mutexes.

WithChannelMode uses a channel (see WithChannelModeBufferSize to configure its size) to receive metrics and drops metrics if the channel is full. Sending metrics in this mode is much slower that WithMutexMode (because of the channel), but will not block the application. This mode is made for application using statsd directly into the application code instead of a separated periodic reporter. The goal is to not slow down the application at the cost of dropping metrics and having a lower max throughput.

func WithChannelModeBufferSize 

func WithChannelModeBufferSize(bufferSize int) Option

WithChannelModeBufferSize sets the size of the channel holding incoming metrics when WithChannelMode is used.

func WithChannelModeErrorsWhenFull added in v5.4.0 

func WithChannelModeErrorsWhenFull() Option

WithChannelModeErrorsWhenFull makes the client return an error when the channel is full. This should be enabled if you want to be notified when the client is dropping metrics. You will also need to set `WithErrorHandler` to be notified of sender error. This might have a small performance impact.

func WithClientSideAggregation 

func WithClientSideAggregation() Option

WithClientSideAggregation enables client side aggregation for Gauges, Counts and Sets.

func WithConnectTimeout added in v5.5.0 

func WithConnectTimeout(connectTimeout time.Duration) Option

WithConnectTimeout sets the timeout for network connection with the Agent, after this interval the connection attempt is aborted. This is only used for UDS connection. This will also reset the connection if nothing can be written to it for this duration.

func WithContainerID added in v5.1.0 

func WithContainerID(id string) Option

WithContainerID allows passing the container ID, this will be used by the Agent to enrich metrics with container tags. This feature requires Datadog Agent version >=6.35.0 && <7.0.0 or Agent versions >=7.35.0. When configured, the provided container ID is prioritized over the container ID discovered via Origin Detection. The client prioritizes the value passed via DD_ENTITY_ID (if set) over the container ID.

func WithErrorHandler added in v5.4.0 

func WithErrorHandler(errorHandler ErrorHandler) Option

WithErrorHandler sets a function that will be called when an error occurs.

func WithExtendedClientSideAggregation 

func WithExtendedClientSideAggregation() Option

WithExtendedClientSideAggregation enables client side aggregation for all types. This feature is only compatible with Agent's version >=6.25.0 && <7.0.0 or Agent's versions >=7.25.0. When enabled, the use of `rate` with distribution is discouraged and `WithMaxSamplesPerContext()` should be used. If `rate` is used with different values of `rate` the resulting rate is not guaranteed to be correct.

func WithMaxBytesPerPayload 

func WithMaxBytesPerPayload(MaxBytesPerPayload int) Option

WithMaxBytesPerPayload sets the maximum number of bytes a single payload can contain. Each sample, even and service check must be lower than this value once serialized or an `MessageTooLongError` is returned.

The default value 0 which will set the option to the optimal size for the transport protocol used: 1432 for UDP and named pipe and 8192 for UDS. Those values offer the best performances. Be careful when changing this option, see https://docs.datadoghq.com/developers/dogstatsd/high_throughput/#ensure-proper-packet-sizes.

func WithMaxMessagesPerPayload 

func WithMaxMessagesPerPayload(maxMessagesPerPayload int) Option

WithMaxMessagesPerPayload sets the maximum number of metrics, events and/or service checks that a single payload can contain.

The default is 'math.MaxInt32' which will most likely let the WithMaxBytesPerPayload option take precedence. This option can be set to `1` to create an unbuffered client (each metrics/event/service check will be send in its own payload to the agent).

func WithMaxSamplesPerContext added in v5.4.0 

func WithMaxSamplesPerContext(maxSamplesPerDistribution int) Option

WithMaxSamplesPerContext limits the number of sample for metric types that require multiple samples to be send over statsd to the agent, such as distributions or timings. This limits the number of sample per context for a distribution to a given number. Gauges and counts will not be affected as a single sample per context is sent with client side aggregation. - This will enable client side aggregation for all metrics. - This feature should be used with `WithExtendedClientSideAggregation` for optimal results.

func WithMutexMode 

func WithMutexMode() Option

WithMutexMode will use mutex to receive metrics from the app through the API.

This determines how the client receive metrics from the app (for example when calling the `Gauge()` method). The client will either drop the metrics if its buffers are full (WithChannelMode option) or block the caller until the metric can be handled (WithMutexMode option). By default the client use mutexes.

WithMutexMode uses mutexes to receive metrics which is much faster than channels but can cause some lock contention when used with a high number of goroutines sending the same metrics. Mutexes are sharded based on the metrics name which limit mutex contention when multiple goroutines send different metrics (see WithWorkersCount). This is the default behavior which will produce the best throughput.

func WithNamespace 

func WithNamespace(namespace string) Option

WithNamespace sets a string to be prepend to all metrics, events and service checks name.

A '.' will automatically be added after the namespace if needed. For example a metrics 'test' with a namespace 'prod' will produce a final metric named 'prod.test'.

func WithOriginDetection added in v5.1.0 

func WithOriginDetection() Option

WithOriginDetection enables the client origin detection. This feature requires Datadog Agent version >=6.35.0 && <7.0.0 or Agent versions >=7.35.0. When enabled, the client tries to discover its container ID and sends it to the Agent to enrich the metrics with container tags. Origin detection can be disabled by configuring the environment variabe DD_ORIGIN_DETECTION_ENABLED=false The client tries to read the container ID by parsing the file /proc/self/cgroup, this is not supported on Windows. The client prioritizes the value passed via DD_ENTITY_ID (if set) over the container ID.

More on this here: https://docs.datadoghq.com/developers/dogstatsd/?tab=kubernetes#origin-detection-over-udp

func WithSenderQueueSize 

func WithSenderQueueSize(senderQueueSize int) Option

WithSenderQueueSize sets the size of the sender queue in number of buffers.

After data has been serialized in a buffer they're pushed to a queue that the sender will consume and then each one ot the agent.

The default value 0 will set the option to the optimal size for the transport protocol used: 2048 for UDP and named pipe and 512 for UDS.

func WithTags 

func WithTags(tags []string) Option

WithTags sets global tags to be applied to every metrics, events and service checks.

func WithTelemetryAddr 

func WithTelemetryAddr(addr string) Option

WithTelemetryAddr sets a different address for telemetry metrics. By default the same address as the client is used for telemetry.

More on this here: https://docs.datadoghq.com/developers/dogstatsd/high_throughput/#client-side-telemetry

func WithWorkersCount 

func WithWorkersCount(workersCount int) Option

WithWorkersCount sets the number of workers that will be used to serialized data.

Those workers allow the use of multiple buffers at the same time (see WithBufferPoolSize) to reduce lock contention.

Default is 32.

func WithWriteTimeout 

func WithWriteTimeout(writeTimeout time.Duration) Option

WithWriteTimeout sets the timeout for network communication with the Agent, after this interval a payload is dropped. This is only used for UDS and named pipes connection.

func WithoutChannelModeErrorsWhenFull added in v5.4.0 

func WithoutChannelModeErrorsWhenFull() Option

WithoutChannelModeErrorsWhenFull makes the client not return an error when the channel is full.

func WithoutClientSideAggregation 

func WithoutClientSideAggregation() Option

WithoutClientSideAggregation disables client side aggregation.

func WithoutOriginDetection added in v5.1.0 

func WithoutOriginDetection() Option

WithoutOriginDetection disables the client origin detection. When enabled, the client tries to discover its container ID and sends it to the Agent to enrich the metrics with container tags. Origin detection can also be disabled by configuring the environment variabe DD_ORIGIN_DETECTION_ENABLED=false The client tries to read the container ID by parsing the file /proc/self/cgroup, this is not supported on Windows. The client prioritizes the value passed via DD_ENTITY_ID (if set) over the container ID.

More on this here: https://docs.datadoghq.com/developers/dogstatsd/?tab=kubernetes#origin-detection-over-udp

func WithoutTelemetry 

func WithoutTelemetry() Option

WithoutTelemetry disables the client telemetry.

More on this here: https://docs.datadoghq.com/developers/dogstatsd/high_throughput/#client-side-telemetry

type Options 

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

Options contains the configuration options for a client.

type ServiceCheck 

type ServiceCheck struct {
	// Name of the service check.  Required.
	Name string
	// Status of service check.  Required.
	Status ServiceCheckStatus
	// Timestamp is a timestamp for the serviceCheck.  If not provided, the dogstatsd
	// server will set this to the current time.
	Timestamp time.Time
	// Hostname for the serviceCheck.
	Hostname string
	// A message describing the current state of the serviceCheck.
	Message string
	// Tags for the serviceCheck.
	Tags []string
}

A ServiceCheck is an object that contains status of DataDog service check.

func NewServiceCheck 

func NewServiceCheck(name string, status ServiceCheckStatus) *ServiceCheck

NewServiceCheck creates a new serviceCheck with the given name and status. Error checking against these values is done at send-time, or upon running sc.Check.

func (*ServiceCheck) Check 

func (sc *ServiceCheck) Check() error

Check verifies that a service check is valid.

type ServiceCheckStatus 

type ServiceCheckStatus byte

ServiceCheckStatus support 

const (
	// Ok is the "ok" ServiceCheck status
	Ok ServiceCheckStatus = 0
	// Warn is the "warning" ServiceCheck status
	Warn ServiceCheckStatus = 1
	// Critical is the "critical" ServiceCheck status
	Critical ServiceCheckStatus = 2
	// Unknown is the "unknown" ServiceCheck status
	Unknown ServiceCheckStatus = 3
)

type Telemetry 

type Telemetry struct {

	// TotalMetrics is the total number of metrics sent by the client before aggregation and sampling.
	TotalMetrics uint64
	// TotalMetricsGauge is the total number of gauges sent by the client before aggregation and sampling.
	TotalMetricsGauge uint64
	// TotalMetricsCount is the total number of counts sent by the client before aggregation and sampling.
	TotalMetricsCount uint64
	// TotalMetricsHistogram is the total number of histograms sent by the client before aggregation and sampling.
	TotalMetricsHistogram uint64
	// TotalMetricsDistribution is the total number of distributions sent by the client before aggregation and
	// sampling.
	TotalMetricsDistribution uint64
	// TotalMetricsSet is the total number of sets sent by the client before aggregation and sampling.
	TotalMetricsSet uint64
	// TotalMetricsTiming is the total number of timings sent by the client before aggregation and sampling.
	TotalMetricsTiming uint64
	// TotalEvents is the total number of events sent by the client before aggregation and sampling.
	TotalEvents uint64
	// TotalServiceChecks is the total number of service_checks sent by the client before aggregation and sampling.
	TotalServiceChecks uint64

	// TotalDroppedOnReceive is the total number metrics/event/service_checks dropped when using ChannelMode (see
	// WithChannelMode option).
	TotalDroppedOnReceive uint64

	// TotalPayloadsSent is the total number of payload (packet on the network) succesfully sent by the client. When
	// using UDP we don't know if packet dropped or not, so all packet are considered as succesfully sent.
	TotalPayloadsSent uint64
	// TotalPayloadsDropped is the total number of payload dropped by the client. This includes all cause of dropped
	// (TotalPayloadsDroppedQueueFull and TotalPayloadsDroppedWriter). When using UDP This won't includes the
	// network dropped.
	TotalPayloadsDropped uint64
	// TotalPayloadsDroppedWriter is the total number of payload dropped by the writer (when using UDS or named
	// pipe) due to network timeout or error.
	TotalPayloadsDroppedWriter uint64
	// TotalPayloadsDroppedQueueFull is the total number of payload dropped internally because the queue of payloads
	// waiting to be sent on the wire is full. This means the client is generating more metrics than can be sent on
	// the wire. If your app sends metrics in batch look at WithSenderQueueSize option to increase the queue size.
	TotalPayloadsDroppedQueueFull uint64

	// TotalBytesSent is the total number of bytes succesfully sent by the client. When using UDP we don't know if
	// packet dropped or not, so all packet are considered as succesfully sent.
	TotalBytesSent uint64
	// TotalBytesDropped is the total number of bytes dropped by the client. This includes all cause of dropped
	// (TotalBytesDroppedQueueFull and TotalBytesDroppedWriter). When using UDP This
	// won't includes the network dropped.
	TotalBytesDropped uint64
	// TotalBytesDroppedWriter is the total number of bytes dropped by the writer (when using UDS or named pipe) due
	// to network timeout or error.
	TotalBytesDroppedWriter uint64
	// TotalBytesDroppedQueueFull is the total number of bytes dropped internally because the queue of payloads
	// waiting to be sent on the wire is full. This means the client is generating more metrics than can be sent on
	// the wire. If your app sends metrics in batch look at WithSenderQueueSize option to increase the queue size.
	TotalBytesDroppedQueueFull uint64

	// AggregationNbContext is the total number of contexts flushed by the aggregator when either
	// WithClientSideAggregation or WithExtendedClientSideAggregation options are enabled.
	AggregationNbContext uint64
	// AggregationNbContextGauge is the total number of contexts for gauges flushed by the aggregator when either
	// WithClientSideAggregation or WithExtendedClientSideAggregation options are enabled.
	AggregationNbContextGauge uint64
	// AggregationNbContextCount is the total number of contexts for counts flushed by the aggregator when either
	// WithClientSideAggregation or WithExtendedClientSideAggregation options are enabled.
	AggregationNbContextCount uint64
	// AggregationNbContextSet is the total number of contexts for sets flushed by the aggregator when either
	// WithClientSideAggregation or WithExtendedClientSideAggregation options are enabled.
	AggregationNbContextSet uint64
	// AggregationNbContextHistogram is the total number of contexts for histograms flushed by the aggregator when either
	// WithClientSideAggregation or WithExtendedClientSideAggregation options are enabled.
	AggregationNbContextHistogram uint64
	// AggregationNbContextDistribution is the total number of contexts for distributions flushed by the aggregator when either
	// WithClientSideAggregation or WithExtendedClientSideAggregation options are enabled.
	AggregationNbContextDistribution uint64
	// AggregationNbContextTiming is the total number of contexts for timings flushed by the aggregator when either
	// WithClientSideAggregation or WithExtendedClientSideAggregation options are enabled.
	AggregationNbContextTiming uint64
}

Telemetry represents internal metrics about the client behavior since it started.

type Transport added in v5.4.0 

type Transport interface {
	io.WriteCloser

	// GetTransportName returns the name of the transport
	GetTransportName() string
}

Source Files

View all Source files

Directories

Path Synopsis
Package mock_statsd is a generated GoMock package.
 Package mock_statsd is a generated GoMock package.

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.