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.

    • Syntax: literal
    • Only required when: mode = `tcp` or `udp`
  • 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.

      • Syntax: literal
      • Enum, must be one of: "tcp" "udp" "unix"
    • commonrequired*string

      path

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

      • Syntax: literal
      • Only required when: mode = `unix`
    • 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

      events_in_total

      The number of events accepted by this component either from tagged origin like file and uri, or cumulatively from other origins. This metric includes the following tags:

      • component_kind - The Vector component kind.

      • component_name - The Vector component ID.

      • component_type - The Vector component type.

      • container_name - The name of the container from which the event originates.

      • file - The file from which the event originates.

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

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

      • mode - The connection mode used by the component.

      • peer_addr - The IP from which the event originates.

      • peer_path - The pathname from which the event originates.

      • pod_name - The name of the pod from which the event originates.

      • uri - The sanitized uri from which the event originates.

    • 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

      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 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.

      • container_name - The name of the container from which the bytes originate.

      • file - The file from which the bytes originate.

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

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

      • mode - The connection mode used by the component.

      • peer_addr - The IP from which the bytes originate.

      • peer_path - The pathname from which the bytes originate.

      • pod_name - The name of the pod from which the bytes originate.

      • uri - The sanitized uri from which the bytes originate.

    • counter

      events_out_total

      The total number of events emitted 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.

      • 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 is deprecated in place of using events_in_total and events_out_total metrics. 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.

    State

    This component is stateless, meaning its behavior is consistent across each input.

    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.