StatsD Source

The Vector statsd source receives metrics from StatsD.

Configuration

[sources.my_source_id]
type = "statsd" # required
address = "0.0.0.0:8125" # required, required when mode = `tcp` or `udp`
mode = "tcp" # required
path = "/path/to/socket" # required, required when mode = `unix`
  • commonrequired*string

    address

    The address to listen for connections on, or systemd#N to use the Nth socket passed by systemd socket activation. If an address is used it must include a port.

    • Only required when: mode = `tcp` or `udp`
    • View examples
  • optionaltable

    keepalive

    Configures the TCP keepalive behavior for the connection to the source.

    • optionaluint

      time_secs

      The time a connection needs to be idle before sending TCP keepalive probes.

    • enumcommonrequiredstring

      mode

      The type of socket to use.

      • Enum, must be one of: "tcp" "udp" "unix"
      • View examples
    • commonrequired*string

      path

      The unix socket path. This should be an absolute path.

      • Only required when: mode = `unix`
      • View examples
    • optionaluint

      shutdown_timeout_secs

      The timeout before a connection is forcefully closed during shutdown.

      • Only relevant when: mode = `tcp`
      • Default: 30 (seconds)

    Output

    This component outputs the following metric events:

    • counter

      counter

      A single value that can only be incremented or reset to zero value, it cannot be decremented. This metric includes the following tags:

      • * - Any tags present on the metric.

    • distribution

      distribution

      A distribution represents a distribution of sampled values. It is used with services that support global histograms and summaries. This metric includes the following tags:

      • * - Any tags present on the metric.

    • gauge

      gauge

      A gauge represents a point-in-time value that can increase and decrease. Vector's internal gauge type represents changes to that value. Gauges should be used to track fluctuations in values, like current memory or CPU usage. This metric includes the following tags:

      • * - Any tags present on the metric.

    • gauge

      set

      A set represents an array of unique values. This metric includes the following tags:

      • * - Any tags present on the metric.

    Telemetry

    This component provides the following metrics that can be retrieved through the internal_metrics source. See the metrics section in the monitoring page for more info.

    • counter

      connection_errors_total

      The total number of connection errors for this Vector instance. This metric includes the following tags:

      • instance - The Vector instance identified by host and port.

      • job - The name of the job producing Vector metrics.

    • counter

      invalid_record_total

      The total number of invalid records that have been discarded. This metric includes the following tags:

      • component_kind - The Vector component kind.

      • component_name - The Vector component ID.

      • component_type - The Vector component type.

      • instance - The Vector instance identified by host and port.

      • job - The name of the job producing Vector metrics.

    • counter

      processed_events_total

      The total number of events processed by this component. This metric includes the following tags:

      • component_kind - The Vector component kind.

      • component_name - The Vector component ID.

      • component_type - The Vector component type.

      • file - The file that produced the error

      • instance - The Vector instance identified by host and port.

      • job - The name of the job producing Vector metrics.

    • counter

      invalid_record_bytes_total

      The total number of bytes from invalid records that have been discarded. This metric includes the following tags:

      • component_kind - The Vector component kind.

      • component_name - The Vector component ID.

      • component_type - The Vector component type.

      • instance - The Vector instance identified by host and port.

      • job - The name of the job producing Vector metrics.

    • counter

      processed_bytes_total

      The total number of bytes processed by the component. This metric includes the following tags:

      • component_kind - The Vector component kind.

      • component_name - The Vector component ID.

      • component_type - The Vector component type.

      • instance - The Vector instance identified by host and port.

      • job - The name of the job producing Vector metrics.

    How It Works

    Context

    By default, the statsd source will augment events with helpful context keys as shown in the "Output" section.

    Timestamps

    StatsD protocol does not provide support for sending metric timestamps. You'll notice that each parsed metric is assigned a null timestamp, which is a special value which means "a real time metric", i.e. not a historical one. Normally such null timestamps will be substituted by current time by downstream sinks or 3rd party services during sending/ingestion. See the metric data model page for more info.