dogstatsd-ruby 5.6.5 → 5.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2954f1cf8d8ad09e7c524c259a5c86e9a54266e4cca8d49367efec66805e788
-  data.tar.gz: e33e5b120be455a4fc40cb7a75e1e01cb4d37be8a9d8a5872a8bfac0e0a66314
+  metadata.gz: ef3f9f930d3c5f43019052d225eaaff5d45e88d47cedac035ba5ce9fa9ab956d
+  data.tar.gz: f3d38f39151c8300ec560662c29771a741c0099d75826768e20d2a97fb49ce88
 SHA512:
-  metadata.gz: 7d7cfea7c2c5236c6f24a16e8339d139a764d5ebaac4c7dba3bb48b3f8b5c2d371a5d610b53aaba29e3957a321697fcf1cec2db298e8703e14ccb2cc153962fc
-  data.tar.gz: 6b4f40d322d4a44d51702e66edde9649add859fe58d9f82eb3e7e7533e1a431b88ad5602695394ee4c6a8bcd1beeaa721e9622e727a1225b6e82d873dbb5cc83
+  metadata.gz: 366d0bb434390d69b2f018efe35b0c0b149d3cc8853c730a69456ff4c51a5f1838db187794dc6db49a4825d5dcaa26db01c2630136b8dea151f3c338d7d4bb6b
+  data.tar.gz: f468d710abbc858d333ee2dd43c8df9806e0ba56c3149075fe4e94330b3c14d0b48a4e78fc7db6b9d6941ec20267bab39ce75eae51a8625fec2c0edc65b03f92

data/README.md

@@ -2,7 +2,7 @@
 
 A client for DogStatsD, an extension of the StatsD metric server for Datadog. Full API documentation is available in [DogStatsD-ruby rubydoc](https://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/Datadog/Statsd).
 
-[![Build Status](https://secure.travis-ci.org/DataDog/dogstatsd-ruby.svg)](http://travis-ci.org/DataDog/dogstatsd-ruby)
+[![Build Status](https://github.com/DataDog/dogstatsd-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/DataDog/dogstatsd-ruby/actions/workflows/test.yml)
 
 See [CHANGELOG.md](CHANGELOG.md) for changes. To suggest a feature, report a bug, or general discussion, [open an issue](http://github.com/DataDog/dogstatsd-ruby/issues/).
 
@@ -91,7 +91,29 @@ statsd = Datadog::Statsd.new('localhost', 8125, single_thread: true)
 statsd.close()
 ```
 
-### Origin detection over UDP
+### Origin detection in Kubernetes
+
+Origin detection is a method to detect the pod that DogStatsD packets are coming from and add the pod's tags to the tag list.
+
+#### Tag cardinality
+
+The tags that can be added to metrics can be found [here][tags]. The cardinality can be specified globally by setting the `DD_CARDINALITY`
+environment or by passing a `'cardinality'` field to the constructor. Cardinality can also be specified per metric by passing the value
+in the `cardinality:` option. Valid values for this parameter are `:none`, `:low`, `:orchestrator` or `:high`. If an invalid 
+value is passed, an `ArgumentError` is raised.
+
+Origin detection is achieved in a number of ways:
+
+#### CGroups
+
+On Linux the container ID can be extracted from `procfs` entries related to `cgroups`. The client reads from `/proc/self/cgroup` or 
+`/proc/self/mountinfo` to attempt to parse the container id.
+
+In cgroup v2, the container ID can be inferred by resolving the cgroup path from `/proc/self/cgroup`, combining it with the cgroup 
+mount point from `/proc/self/mountinfo]`. The resulting directory's inode is sent to the agent. Provided the agent is on the same 
+node as the client, this can be used to identify the pod's UID.
+
+### Over UDP
 
 Origin detection is a method to detect which pod DogStatsD packets are coming from, in order to add the pod's tags to the tag list.
 
@@ -105,7 +127,20 @@ env:
         fieldPath: metadata.uid
 ```
 
-The DogStatsD client attaches an internal tag, `entity_id`. The value of this tag is the content of the `DD_ENTITY_ID` environment variable, which is the pod’s UID.
+The DogStatsD client attaches an internal tag, `entity_id`. The value of this tag is the content of the `DD_ENTITY_ID` environment
+variable, which is the pod’s UID.
+
+#### DD_EXTERNAL_ENV
+
+If the pod is annotated with the label:
+
+```
+admission.datadoghq.com/enabled: "true"
+```
+
+The [admissions controller] injects an environment variable `DD_EXTERNAL_ENV`. The value of this is sent in a field with the
+metric which can be used by the agent to determine the metrics origin.
+
 
 ## Usage
 
@@ -235,3 +270,6 @@ dogstatsd-ruby is forked from Rein Henrichs' [original Statsd client](https://gi
 
 Copyright (c) 2011 Rein Henrichs. See LICENSE.txt for
 further details.
+
+[admissions controller]: https://docs.datadoghq.com/containers/cluster_agent/admission_controller/?tab=datadogoperator
+[tags]: https://docs.datadoghq.com/containers/kubernetes/tag/?tab=datadogoperator

data/lib/datadog/statsd/forwarder.rb

@@ -22,6 +22,9 @@ module Datadog
         single_thread: false,
 
         logger: nil,
+        container_id: nil,
+        external_data: nil,
+        cardinality: nil,
 
         serializer:
       )
@@ -29,6 +32,9 @@ module Datadog
 
         @telemetry = if telemetry_flush_interval
           Telemetry.new(telemetry_flush_interval,
+            container_id,
+            external_data,
+            cardinality,
             global_tags: global_tags,
             transport_type: @transport_type
           )

data/lib/datadog/statsd/message_buffer.rb

@@ -28,8 +28,8 @@ module Datadog
         # Serializes the message if it hasn't been already. Part of the
         # delay_serialization feature.
         if message.is_a?(Array)
-          stat, delta, type, tags, sample_rate = message
-          message = @serializer.to_stat(stat, delta, type, tags: tags, sample_rate: sample_rate)
+          stat, delta, type, tags, sample_rate, cardinality = message
+          message = @serializer.to_stat(stat, delta, type, tags: tags, sample_rate: sample_rate, cardinality: cardinality)
         end
 
         message_size = message.bytesize

data/lib/datadog/statsd/origin_detection.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+module Datadog
+  class Statsd
+    private
+
+    CGROUPV1BASECONTROLLER = "memory"
+    HOSTCGROUPNAMESPACEINODE = 0xEFFFFFFB
+
+    def host_cgroup_namespace?
+      stat = File.stat("/proc/self/ns/cgroup") rescue nil
+      return false unless stat
+      stat.ino == HOSTCGROUPNAMESPACEINODE
+    end
+
+    def parse_cgroup_node_path(lines)
+      res = {}
+      lines.split("\n").each do |line|
+        tokens = line.split(':')
+        next unless tokens.length == 3
+
+        controller = tokens[1]
+        path = tokens[2]
+
+        if controller == CGROUPV1BASECONTROLLER || controller == ''
+          res[controller] = path
+        end
+      end
+
+      res
+    end
+
+    def get_cgroup_inode(cgroup_mount_path, proc_self_cgroup_path)
+      content = File.read(proc_self_cgroup_path) rescue nil
+      return nil unless content
+
+      controllers = parse_cgroup_node_path(content)
+
+      [CGROUPV1BASECONTROLLER, ''].each do |controller|
+        next unless controllers[controller]
+
+        segments = [
+          cgroup_mount_path.chomp('/'),
+          controller.strip,
+          controllers[controller].sub(/^\//, '')
+        ]
+        path = segments.reject(&:empty?).join("/")
+        inode = inode_for_path(path)
+        return inode unless inode.nil?
+      end
+
+      nil
+    end
+
+    def inode_for_path(path)
+      stat = File.stat(path) rescue nil
+      return nil unless stat
+      "in-#{stat.ino}"
+    end
+
+    def parse_container_id(handle)
+      exp_line = /^\d+:[^:]*:(.+)$/
+      uuid = /[0-9a-f]{8}[-_][0-9a-f]{4}[-_][0-9a-f]{4}[-_][0-9a-f]{4}[-_][0-9a-f]{12}/
+      container = /[0-9a-f]{64}/
+      task = /[0-9a-f]{32}-\d+/
+      exp_container_id = /(#{uuid}|#{container}|#{task})(?:\.scope)?$/
+
+      handle.each_line do |line|
+        match = line.match(exp_line)
+        next unless match && match[1]
+        id_match = match[1].match(exp_container_id)
+
+        return id_match[1] if id_match && id_match[1]
+      end
+
+      nil
+    end
+
+    def read_container_id(fpath)
+      handle = File.open(fpath, 'r') rescue nil
+      return nil unless handle
+
+      id = parse_container_id(handle)
+      handle.close
+      id
+    end
+
+    # Extracts the final container info from a line in mount info
+    def extract_container_info(line)
+      parts = line.strip.split("/")
+      return nil unless parts.last == "hostname"
+
+      # Expected structure: [..., <group>, <container_id>, ..., "hostname"]
+      container_id = nil
+      group = nil
+
+      parts.each_with_index do |part, idx|
+        # Match the container id and include the section prior to it.
+        if part.length == 64 && !!(part =~ /\A[0-9a-f]{64}\z/)
+          group = parts[idx - 1] if idx >= 1
+          container_id = part
+        elsif part.length > 32 && !!(part =~ /\A[0-9a-f]{32}-\d+\z/)
+          group = parts[idx - 1] if idx >= 1
+          container_id = part
+        elsif !!(part =~ /\A[0-9a-f]{8}(-[0-9a-f]{4}){4}\z/)
+          group = parts[idx - 1] if idx >= 1
+          container_id = part
+        end
+      end
+
+      return container_id unless group == "sandboxes"
+    end
+
+    # Parse /proc/self/mountinfo to extract the container id.
+    # Often container runtimes embed the container id in the mount paths.
+    # We parse the mount with a final `hostname` component, which is part of
+    # the containers `etc/hostname` bind mount.
+    def parse_mount_info(handle)
+      handle.each_line do |line|
+        split = line.split(" ")
+        mnt1 = split[3]
+        mnt2 = split[4]
+        [mnt1, mnt2].each do |line|
+          container_id = extract_container_info(line)
+          return container_id unless container_id.nil?
+        end
+      end
+
+      nil
+    end
+
+    def read_mount_info(path)
+      handle = File.open(path, 'r') rescue nil
+      return nil unless handle
+
+      info = parse_mount_info(handle)
+      handle.close
+      info
+    end
+
+    def get_container_id(user_provided_id, cgroup_fallback)
+      return user_provided_id unless user_provided_id.nil?
+      return nil unless cgroup_fallback
+
+      container_id = read_container_id("/proc/self/cgroup")
+      return container_id unless container_id.nil?
+
+      container_id = read_mount_info("/proc/self/mountinfo")
+      return container_id unless container_id.nil?
+
+      return nil if host_cgroup_namespace?
+
+      get_cgroup_inode("/sys/fs/cgroup", "/proc/self/cgroup")
+    end
+  end
+end

data/lib/datadog/statsd/sender.rb

@@ -20,6 +20,7 @@ module Datadog
         @mx = Mutex.new
         @queue_class = queue_class
         @thread_class = thread_class
+        @done = false
         @flush_timer = if flush_interval
           Datadog::Statsd::Timer.new(flush_interval) { flush(sync: true) }
         else
@@ -66,8 +67,11 @@ module Datadog
         # if the thread does not exist, we assume we are running in a forked process,
         # empty the message queue and message buffers (these messages belong to
         # the parent process) and spawn a new companion thread.
-        if !sender_thread.alive?
+        if sender_thread.nil? || !sender_thread.alive?
           @mx.synchronize {
+            # an attempt was previously made to start the sender thread but failed.
+            # skipping re-start
+            return if @done
             # a call from another thread has already re-created
             # the companion thread before this one acquired the lock
             break if sender_thread.alive?
@@ -96,9 +100,15 @@ module Datadog
 
         # initialize a new message queue for the background thread
         @message_queue = @queue_class.new
-        # start background thread
-        @sender_thread = @thread_class.new(&method(:send_loop))
-        @sender_thread.name = "Statsd Sender" unless Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.3')
+        begin
+          # start background thread
+          @sender_thread = @thread_class.new(&method(:send_loop))
+          @sender_thread.name = "Statsd Sender" unless Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.3')
+        rescue ThreadError => e
+          @logger.debug { "Statsd: Failed to start sender thread: #{e.message}" } if @logger
+          @mx.synchronize { @done = true }
+        end
+
         @flush_timer.start if @flush_timer
       end
 

data/lib/datadog/statsd/serialization/event_serializer.rb

@@ -13,8 +13,9 @@ module Datadog
           alert_type:       't:',
         }.freeze
 
-        def initialize(global_tags: [])
+        def initialize(container_id, external_data, global_tags: [])
           @tag_serializer = TagSerializer.new(global_tags)
+          @field_serializer = FieldSerializer.new(container_id, external_data)
         end
 
         def format(title, text, options = EMPTY_OPTIONS)
@@ -47,6 +48,10 @@ module Datadog
               event << tags
             end
 
+            if fields = field_serializer.format(options[:cardinality])
+              event << fields
+            end
+
             if event.bytesize > MAX_EVENT_SIZE
               if options[:truncate_if_too_long]
                 event.slice!(MAX_EVENT_SIZE..event.length)
@@ -59,6 +64,7 @@ module Datadog
 
         protected
         attr_reader :tag_serializer
+        attr_reader :field_serializer
 
         def escape(text)
           text.delete('|').tap do |t|

data/lib/datadog/statsd/serialization/field_serializer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Datadog
+  class Statsd
+    module Serialization
+      class FieldSerializer
+        VALID_CARDINALITY = [:none, :low, :orchestrator, :high]
+
+        def initialize(container_id, external_data)
+          @container_id = container_id
+          @external_data = external_data
+        end
+
+        def format(cardinality)
+          if @container_id.nil? && @external_data.nil? && cardinality.nil?
+            return ""
+          end
+
+          field = String.new
+          field << "|c:#{@container_id}" unless @container_id.nil?
+          field << "|e:#{@external_data}" unless @external_data.nil?
+
+          unless cardinality.nil?
+            unless VALID_CARDINALITY.include?(cardinality.to_sym)
+              raise ArgumentError, "Invalid cardinality #{cardinality}. Valid options are #{VALID_CARDINALITY.join(', ')}."
+            end
+
+            field << "|card:#{cardinality}"
+          end
+
+          field
+        end
+      end
+    end
+  end
+end

data/lib/datadog/statsd/serialization/serializer.rb

@@ -6,15 +6,15 @@ module Datadog
   class Statsd
     module Serialization
       class Serializer
-        def initialize(prefix: nil, global_tags: [])
-          @stat_serializer = StatSerializer.new(prefix, global_tags: global_tags)
-          @service_check_serializer = ServiceCheckSerializer.new(global_tags: global_tags)
-          @event_serializer = EventSerializer.new(global_tags: global_tags)
+        def initialize(prefix: nil, container_id: nil, external_data: nil, global_tags: [])
+          @stat_serializer = StatSerializer.new(prefix, container_id, external_data, global_tags: global_tags)
+          @service_check_serializer = ServiceCheckSerializer.new(container_id, external_data, global_tags: global_tags)
+          @event_serializer = EventSerializer.new(container_id, external_data, global_tags: global_tags)
         end
 
         # using *args would make new allocations
-        def to_stat(name, delta, type, tags: [], sample_rate: 1)
-          stat_serializer.format(name, delta, type, tags: tags, sample_rate: sample_rate)
+        def to_stat(name, delta, type, tags: [], sample_rate: 1, cardinality: nil)
+          stat_serializer.format(name, delta, type, tags: tags, sample_rate: sample_rate, cardinality: cardinality)
         end
 
         # using *args would make new allocations

data/lib/datadog/statsd/serialization/service_check_serializer.rb

@@ -9,8 +9,9 @@ module Datadog
           hostname:  'h:',
         }.freeze
 
-        def initialize(global_tags: [])
+        def initialize(container_id, external_data, global_tags: [])
           @tag_serializer = TagSerializer.new(global_tags)
+          @field_serializer = FieldSerializer.new(container_id, external_data)
         end
 
         def format(name, status, options = EMPTY_OPTIONS)
@@ -42,11 +43,16 @@ module Datadog
               service_check << '|#'
               service_check << tags
             end
+
+            if fields = field_serializer.format(options[:cardinality])
+              service_check << fields
+            end
           end
         end
 
         protected
         attr_reader :tag_serializer
+        attr_reader :field_serializer
 
         def escape_message(message)
           message.delete('|').tap do |m|

data/lib/datadog/statsd/serialization/stat_serializer.rb

@@ -4,26 +4,28 @@ module Datadog
   class Statsd
     module Serialization
       class StatSerializer
-        def initialize(prefix, global_tags: [])
+        def initialize(prefix, container_id, external_data, global_tags: [])
           @prefix = prefix
           @prefix_str = prefix.to_s
           @tag_serializer = TagSerializer.new(global_tags)
+          @field_serializer = FieldSerializer.new(container_id, external_data)
         end
 
-        def format(metric_name, delta, type, tags: [], sample_rate: 1)
+        def format(metric_name, delta, type, tags: [], sample_rate: 1, cardinality: nil)
           metric_name = formatted_metric_name(metric_name)
+          fields = field_serializer.format(cardinality)
 
           if sample_rate != 1
             if tags_list = tag_serializer.format(tags)
-              "#{@prefix_str}#{metric_name}:#{delta}|#{type}|@#{sample_rate}|##{tags_list}"
+              "#{@prefix_str}#{metric_name}:#{delta}|#{type}|@#{sample_rate}|##{tags_list}#{fields}"
             else
-              "#{@prefix_str}#{metric_name}:#{delta}|#{type}|@#{sample_rate}"
+              "#{@prefix_str}#{metric_name}:#{delta}|#{type}|@#{sample_rate}#{fields}"
             end
           else
             if tags_list = tag_serializer.format(tags)
-              "#{@prefix_str}#{metric_name}:#{delta}|#{type}|##{tags_list}"
+              "#{@prefix_str}#{metric_name}:#{delta}|#{type}|##{tags_list}#{fields}"
             else
-              "#{@prefix_str}#{metric_name}:#{delta}|#{type}"
+              "#{@prefix_str}#{metric_name}:#{delta}|#{type}#{fields}"
             end
           end
         end
@@ -36,6 +38,7 @@ module Datadog
 
         attr_reader :prefix
         attr_reader :tag_serializer
+        attr_reader :field_serializer
 
         if RUBY_VERSION < '3'
           def metric_name_to_string(metric_name)

data/lib/datadog/statsd/serialization.rb

@@ -10,6 +10,7 @@ end
 require_relative 'serialization/tag_serializer'
 require_relative 'serialization/service_check_serializer'
 require_relative 'serialization/event_serializer'
+require_relative 'serialization/field_serializer'
 require_relative 'serialization/stat_serializer'
 
 require_relative 'serialization/serializer'

data/lib/datadog/statsd/telemetry.rb

@@ -19,7 +19,7 @@ module Datadog
       # Rough estimation of maximum telemetry message size without tags
       MAX_TELEMETRY_MESSAGE_SIZE_WT_TAGS = 50 # bytes
 
-      def initialize(flush_interval, global_tags: [], transport_type: :udp)
+      def initialize(flush_interval, container_id, external_data, cardinality, global_tags: [], transport_type: :udp)
         @flush_interval = flush_interval
         @global_tags = global_tags
         @transport_type = transport_type
@@ -32,10 +32,15 @@ module Datadog
           client_version: VERSION,
           client_transport: transport_type,
         ).format(global_tags)
+
+        @serialized_fields = Serialization::FieldSerializer.new(
+          container_id,
+          external_data
+        ).format(cardinality)
       end
 
       def would_fit_in?(max_buffer_payload_size)
-        MAX_TELEMETRY_MESSAGE_SIZE_WT_TAGS + serialized_tags.size < max_buffer_payload_size
+        MAX_TELEMETRY_MESSAGE_SIZE_WT_TAGS + serialized_tags.size + serialized_fields.size < max_buffer_payload_size
       end
 
       def reset
@@ -98,9 +103,10 @@ module Datadog
 
       private
       attr_reader :serialized_tags
+      attr_reader :serialized_fields
 
       def pattern
-        @pattern ||= "datadog.dogstatsd.client.%s:%d|#{COUNTER_TYPE}|##{serialized_tags}"
+        @pattern ||= "datadog.dogstatsd.client.%s:%d|#{COUNTER_TYPE}|##{serialized_tags}#{serialized_fields}"
       end
 
       if Kernel.const_defined?('Process') && Process.respond_to?(:clock_gettime)

data/lib/datadog/statsd/version.rb

@@ -4,6 +4,6 @@ require_relative 'connection'
 
 module Datadog
   class Statsd
-    VERSION = '5.6.5'
+    VERSION = '5.7.1'
   end
 end

data/lib/datadog/statsd.rb

@@ -6,6 +6,7 @@ require_relative 'statsd/telemetry'
 require_relative 'statsd/udp_connection'
 require_relative 'statsd/uds_connection'
 require_relative 'statsd/connection_cfg'
+require_relative 'statsd/origin_detection'
 require_relative 'statsd/message_buffer'
 require_relative 'statsd/serialization'
 require_relative 'statsd/sender'
@@ -82,6 +83,9 @@ module Datadog
     # @option [Float] default sample rate if not overridden
     # @option [Boolean] single_thread flushes the metrics on the main thread instead of in a companion thread
     # @option [Boolean] delay_serialization delays stat serialization
+    # @option [Boolean] origin_detection is origin detection enabled
+    # @option [String] container_id the container ID field, used for origin detection
+    # @option [String] cardinality the default tag cardinality to use
     def initialize(
       host = nil,
       port = nil,
@@ -104,7 +108,11 @@ module Datadog
       delay_serialization: false,
 
       telemetry_enable: true,
-      telemetry_flush_interval: DEFAULT_TELEMETRY_FLUSH_INTERVAL
+      telemetry_flush_interval: DEFAULT_TELEMETRY_FLUSH_INTERVAL,
+
+      origin_detection: true,
+      container_id: nil,
+      cardinality: nil
     )
       unless tags.nil? || tags.is_a?(Array) || tags.is_a?(Hash)
         raise ArgumentError, 'tags must be an array of string tags or a Hash'
@@ -112,7 +120,20 @@ module Datadog
 
       @namespace = namespace
       @prefix = @namespace ? "#{@namespace}.".freeze : nil
-      @serializer = Serialization::Serializer.new(prefix: @prefix, global_tags: tags)
+
+      origin_detection_enabled = origin_detection_enabled?(origin_detection)
+      container_id = get_container_id(container_id, origin_detection_enabled)
+
+      external_data = sanitize(ENV['DD_EXTERNAL_ENV']) if origin_detection_enabled
+
+      @serializer = Serialization::Serializer.new(prefix: @prefix,
+                                                  container_id: container_id,
+                                                  external_data: external_data,
+                                                  global_tags: tags,
+                                                  )
+
+      @cardinality = cardinality || ENV['DD_CARDINALITY'] || ENV['DATADOG_CARDINALITY']
+
       @sample_rate = sample_rate
       @delay_serialization = delay_serialization
 
@@ -136,6 +157,10 @@ module Datadog
         sender_queue_size: sender_queue_size,
 
         telemetry_flush_interval: telemetry_enable ? telemetry_flush_interval : nil,
+        container_id: container_id,
+        external_data: external_data,
+        cardinality: @cardinality,
+
         serializer: serializer
       )
     end
@@ -159,6 +184,7 @@ module Datadog
     # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
     # @option opts [Numeric] :by increment value, default 1
+    # @option opts [String] :cardinality The tag cardinality to use
     # @see #count
     def increment(stat, opts = EMPTY_OPTIONS)
       opts = { sample_rate: opts } if opts.is_a?(Numeric)
@@ -174,6 +200,7 @@ module Datadog
     # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
     # @option opts [Numeric] :by decrement value, default 1
+    # @option opts [String] :cardinality The tag cardinality to use
     # @see #count
     def decrement(stat, opts = EMPTY_OPTIONS)
       opts = { sample_rate: opts } if opts.is_a?(Numeric)
@@ -189,6 +216,7 @@ module Datadog
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
     # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
+    # @option opts [String] :cardinality The tag cardinality to use
     def count(stat, count, opts = EMPTY_OPTIONS)
       opts = { sample_rate: opts } if opts.is_a?(Numeric)
       send_stats(stat, count, COUNTER_TYPE, opts)
@@ -206,6 +234,7 @@ module Datadog
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
     # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
+    # @option opts [String] :cardinality The tag cardinality to use
     # @example Report the current user count:
     #   $statsd.gauge('user.count', User.count)
     def gauge(stat, value, opts = EMPTY_OPTIONS)
@@ -221,6 +250,7 @@ module Datadog
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
     # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
+    # @option opts [String] :cardinality The tag cardinality to use
     # @example Report the current user count:
     #   $statsd.histogram('user.count', User.count)
     def histogram(stat, value, opts = EMPTY_OPTIONS)
@@ -235,6 +265,7 @@ module Datadog
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
     # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
+    # @option opts [String] :cardinality The tag cardinality to use
     # @example Report the current user count:
     #   $statsd.distribution('user.count', User.count)
     def distribution(stat, value, opts = EMPTY_OPTIONS)
@@ -251,6 +282,7 @@ module Datadog
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
     # @option opts [Array<String>] :tags An array of tags
+    # @option opts [String] :cardinality The tag cardinality to use
     # @example Report the time (in ms) taken to activate an account
     #   $statsd.distribution_time('account.activate') { @account.activate! }
     def distribution_time(stat, opts = EMPTY_OPTIONS)
@@ -272,6 +304,7 @@ module Datadog
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
     # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
+    # @option opts [String] :cardinality The tag cardinality to use
     def timing(stat, ms, opts = EMPTY_OPTIONS)
       opts = { sample_rate: opts } if opts.is_a?(Numeric)
       send_stats(stat, ms, TIMING_TYPE, opts)
@@ -287,6 +320,7 @@ module Datadog
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
     # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
+    # @option opts [String] :cardinality The tag cardinality to use
     # @yield The operation to be timed
     # @see #timing
     # @example Report the time (in ms) taken to activate an account
@@ -307,6 +341,7 @@ module Datadog
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
     # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
+    # @option opts [String] :cardinality The tag cardinality to use
     # @example Record a unique visitory by id:
     #   $statsd.set('visitors.uniques', User.id)
     def set(stat, value, opts = EMPTY_OPTIONS)
@@ -348,6 +383,7 @@ module Datadog
     # @option opts [String, nil] :alert_type ('info') Can be "error", "warning", "info" or "success".
     # @option opts [Boolean, false] :truncate_if_too_long (false) Truncate the event if it is too long
     # @option opts [Array<String>] :tags tags to be added to every metric
+    # @option opts [String] :cardinality The tag cardinality to use
     # @example Report an awful event:
     #   $statsd.event('Something terrible happened', 'The end is near if we do nothing', :alert_type=>'warning', :tags=>['end_of_times','urgent'])
     def event(title, text, opts = EMPTY_OPTIONS)
@@ -427,17 +463,43 @@ module Datadog
       telemetry.sent(metrics: 1) if telemetry
 
       sample_rate = opts[:sample_rate] || @sample_rate || 1
+      cardinality = opts[:cardinality] || @cardinality
 
       if sample_rate == 1 || opts[:pre_sampled] || rand <= sample_rate
         full_stat =
           if @delay_serialization
-            [stat, delta, type, opts[:tags], sample_rate]
+            [stat, delta, type, opts[:tags], sample_rate, cardinality]
           else
-            serializer.to_stat(stat, delta, type, tags: opts[:tags], sample_rate: sample_rate)
+            serializer.to_stat(stat, delta, type, tags: opts[:tags], sample_rate: sample_rate, cardinality: cardinality)
           end
 
         forwarder.send_message(full_stat)
       end
     end
+
+    def origin_detection_enabled?(origin_detection)
+      if !origin_detection.nil? && !origin_detection
+        return false
+      end
+
+      if ENV['DD_ORIGIN_DETECTION_ENABLED']
+        return ![
+          '0',
+          'f',
+          'false'
+        ].include?(
+          ENV['DD_ORIGIN_DETECTION_ENABLED'].downcase
+        )
+      end
+
+      return true
+    end
+
+    # Sanitize the DD_EXTERNAL_ENV input to ensure it doesn't contain invalid characters
+    # that may break the protocol.
+    # Removing any non-printable characters and `|`.
+    def sanitize(external_data)
+      external_data.gsub(/[^[:print:]]|`\|/, '') unless external_data.nil?
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dogstatsd-ruby
 version: !ruby/object:Gem::Version
-  version: 5.6.5
+  version: 5.7.1
 platform: ruby
 authors:
 - Rein Henrichs
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-03 00:00:00.000000000 Z
+date: 2025-08-20 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby DogStatsd client
 email: code@datadoghq.com
@@ -26,9 +26,11 @@ files:
 - lib/datadog/statsd/connection_cfg.rb
 - lib/datadog/statsd/forwarder.rb
 - lib/datadog/statsd/message_buffer.rb
+- lib/datadog/statsd/origin_detection.rb
 - lib/datadog/statsd/sender.rb
 - lib/datadog/statsd/serialization.rb
 - lib/datadog/statsd/serialization/event_serializer.rb
+- lib/datadog/statsd/serialization/field_serializer.rb
 - lib/datadog/statsd/serialization/serializer.rb
 - lib/datadog/statsd/serialization/service_check_serializer.rb
 - lib/datadog/statsd/serialization/stat_serializer.rb
@@ -44,9 +46,9 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/DataDog/dogstatsd-ruby/issues
-  changelog_uri: https://github.com/DataDog/dogstatsd-ruby/blob/v5.6.5/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/dogstatsd-ruby/5.6.5
-  source_code_uri: https://github.com/DataDog/dogstatsd-ruby/tree/v5.6.5
+  changelog_uri: https://github.com/DataDog/dogstatsd-ruby/blob/v5.7.1/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/dogstatsd-ruby/5.7.1
+  source_code_uri: https://github.com/DataDog/dogstatsd-ruby/tree/v5.7.1
 post_install_message: |2+
 
   If you are upgrading from v4.x of the dogstatsd-ruby library, note the major change to the threading model: