statsd-instrument 2.5.1 → 2.6.0

data/lib/statsd/instrument/backends/udp_backend.rb

@@ -7,23 +7,10 @@ module StatsD::Instrument::Backends
     BASE_SUPPORTED_METRIC_TYPES = { c: true, ms: true, g: true, s: true }
 
     class DogStatsDProtocol
-      EVENT_OPTIONS = {
-        date_happened: 'd',
-        hostname: 'h',
-        aggregation_key: 'k',
-        priority: 'p',
-        source_type_name: 's',
-        alert_type: 't',
-      }
-
-      SERVICE_CHECK_OPTIONS = {
-        timestamp: 'd',
-        hostname: 'h',
-        message: 'm',
-      }
-
       SUPPORTED_METRIC_TYPES = BASE_SUPPORTED_METRIC_TYPES.merge(h: true, _e: true, _sc: true, d: true)
 
+      SERVICE_CHECK_STATUSES = { ok: 0, warning: 1, critical: 2, unknown: 3 }
+
       def generate_packet(metric)
         packet = +""
 
@@ -32,27 +19,31 @@ module StatsD::Instrument::Backends
           escaped_text = metric.value.gsub("\n", "\\n")
 
           packet << "_e{#{escaped_title.size},#{escaped_text.size}}:#{escaped_title}|#{escaped_text}"
-          packet << generate_metadata(metric, EVENT_OPTIONS)
+          packet << "|h:#{metric.metadata[:hostname]}" if metric.metadata[:hostname]
+          packet << "|d:#{metric.metadata[:timestamp].to_i}" if metric.metadata[:timestamp]
+          packet << "|k:#{metric.metadata[:aggregation_key]}" if metric.metadata[:aggregation_key]
+          packet << "|p:#{metric.metadata[:priority]}" if metric.metadata[:priority]
+          packet << "|s:#{metric.metadata[:source_type_name]}" if metric.metadata[:source_type_name]
+          packet << "|t:#{metric.metadata[:alert_type]}" if metric.metadata[:alert_type]
+          packet << "|##{metric.tags.join(',')}" if metric.tags
+
         elsif metric.type == :_sc
-          packet << "_sc|#{metric.name}|#{metric.value}"
-          packet << generate_metadata(metric, SERVICE_CHECK_OPTIONS)
+          status = metric.value.is_a?(Integer) ? metric.value : SERVICE_CHECK_STATUSES.fetch(metric.value.to_sym)
+
+          packet << "_sc|#{metric.name}|#{status}"
+          packet << "|h:#{metric.metadata[:hostname]}" if metric.metadata[:hostname]
+          packet << "|d:#{metric.metadata[:timestamp].to_i}" if metric.metadata[:timestamp]
+          packet << "|##{metric.tags.join(',')}" if metric.tags
+          packet << "|m:#{metric.metadata[:message]}" if metric.metadata[:message]
+
         else
           packet << "#{metric.name}:#{metric.value}|#{metric.type}"
+          packet << "|@#{metric.sample_rate}" if metric.sample_rate < 1
+          packet << "|##{metric.tags.join(',')}" if metric.tags
         end
 
-        packet << "|@#{metric.sample_rate}" if metric.sample_rate < 1
-        packet << "|##{metric.tags.join(',')}" if metric.tags
-
         packet
       end
-
-      private
-
-      def generate_metadata(metric, options)
-        (metric.metadata.keys & options.keys).map do |key|
-          "|#{options[key]}:#{metric.metadata[key]}"
-        end.join
-      end
     end
 
     class StatsiteStatsDProtocol

data/lib/statsd/instrument/capture_sink.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# @note This class is part of the new Client implementation that is intended
+#   to become the new default in the next major release of this library.
+class StatsD::Instrument::CaptureSink
+  attr_reader :parent, :datagrams, :datagram_class
+
+  def initialize(parent:, datagram_class: StatsD::Instrument::Datagram)
+    @parent = parent
+    @datagram_class = datagram_class
+    @datagrams = []
+  end
+
+  def sample?(_sample_rate)
+    true
+  end
+
+  def <<(datagram)
+    @datagrams << datagram_class.new(datagram)
+    parent << datagram
+    self
+  end
+
+  def clear
+    @datagrams.clear
+  end
+end

data/lib/statsd/instrument/client.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require 'statsd/instrument/datagram'
+require 'statsd/instrument/datagram_builder'
+require 'statsd/instrument/statsd_datagram_builder'
+require 'statsd/instrument/dogstatsd_datagram_builder'
+require 'statsd/instrument/null_sink'
+require 'statsd/instrument/udp_sink'
+require 'statsd/instrument/capture_sink'
+require 'statsd/instrument/log_sink'
+
+# The Client is the main interface for using StatsD.
+#
+# @note This new new Client implementation that is intended to become the new default in
+#   the next major release of this library. While this class may already be functional,
+#   we provide no guarantees about the API and the behavior may change.
+class StatsD::Instrument::Client
+  attr_reader :sink, :datagram_builder_class, :prefix, :default_tags, :default_sample_rate
+
+  def initialize(
+    sink: StatsD::Instrument::NullSink.new,
+    prefix: nil,
+    default_sample_rate: 1,
+    default_tags: nil,
+    datagram_builder_class: StatsD::Instrument::StatsDDatagramBuilder
+  )
+    @sink = sink
+    @datagram_builder_class = datagram_builder_class
+
+    @prefix = prefix
+    @default_tags = default_tags
+    @default_sample_rate = default_sample_rate
+
+    @datagram_builder = { false => nil, true => nil }
+  end
+
+  # @!group Metric Methods
+
+  # Emits a counter metric.
+  #
+  # You should use a counter metric to count the frequency of something happening. As a
+  # result, the value should generally be set to 1 (the default), unless you reporting
+  # about a batch of activity. E.g. `increment('messages.processed', messages.size)`
+  # For values that are not frequencies, you should use another metric type, e.g.
+  # {#histogram} or {#distribution}.
+  #
+  # @param name [String] The name of the metric.
+  #
+  #   - We recommend using `snake_case.metric_names` as naming scheme.
+  #   - A `.` should be used for namespacing, e.g. `foo.bar.baz`
+  #   - A metric name should not include the following characters: `|`, `@`, and `:`.
+  #     The library will convert these characters to `_`.
+  #
+  # @param value [Integer] (default: 1) The value to increment the counter by.
+  #
+  #   You should not compensate for the sample rate using the counter increment. E.g., if
+  #   your sample rate is set to `0.01`, you should not use 100 as increment to compensate
+  #   for it. The sample rate is part of the packet that is being sent to the server, and
+  #   the server should know how to compensate for it.
+  #
+  # @param [Float] sample_rate (default: `#default_sample_rate`) The rate at which to sample
+  #   this metric call. This value should be between 0 and 1. This value can be used to reduce
+  #   the amount of network I/O (and CPU cycles) is being used for very frequent metrics.
+  #
+  #   - A value of `0.1` means that only 1 out of 10 calls will be emitted; the other 9 will
+  #     be short-circuited.
+  #   - When set to `1`, every metric will be emitted.
+  #   - If this parameter is not set, the default sample rate for this client will be used.
+  #
+  # @param [Hash<Symbol, String>, Array<String>] tags (default: nil)
+  # @return [void]
+  def increment(name, value = 1, sample_rate: nil, tags: nil, no_prefix: false)
+    sample_rate ||= @default_sample_rate
+    return unless sample?(sample_rate)
+    emit(datagram_builder(no_prefix: no_prefix).c(name, value, sample_rate, tags))
+  end
+
+  # Emits a timing metric.
+  #
+  # @param name (see #increment)
+  # @param [Numeric] value The duration to record, in milliseconds.
+  # @param sample_rate (see #increment)
+  # @param tags (see #increment)
+  # @return [void]
+  def measure(name, value = nil, sample_rate: nil, tags: nil, no_prefix: false, &block)
+    if block_given?
+      return latency(name, sample_rate: sample_rate, tags: tags, metric_type: :ms, no_prefix: no_prefix, &block)
+    end
+
+    sample_rate ||= @default_sample_rate
+    return unless sample?(sample_rate)
+    emit(datagram_builder(no_prefix: no_prefix).ms(name, value, sample_rate, tags))
+  end
+
+  # Emits a gauge metric.
+  #
+  # You should use a gauge if you are reporting the current value of
+  # something that can only have one value at the time. E.g., the
+  # speed of your car. A newly reported value will repla e the previously
+  # reported value.
+  #
+  #
+  # @param name (see #increment)
+  # @param [Numeric] value The gauged value.
+  # @param sample_rate (see #increment)
+  # @param tags (see #increment)
+  # @return [void]
+  def gauge(name, value, sample_rate: nil, tags: nil, no_prefix: false)
+    sample_rate ||= @default_sample_rate
+    return unless sample?(sample_rate)
+    emit(datagram_builder(no_prefix: no_prefix).g(name, value, sample_rate, tags))
+  end
+
+  # Emits a set metric, which counts distinct values.
+  #
+  # @param name (see #increment)
+  # @param [Numeric, String] value The value to count for distinct occurrences.
+  # @param sample_rate (see #increment)
+  # @param tags (see #increment)
+  # @return [void]
+  def set(name, value, sample_rate: nil, tags: nil, no_prefix: false)
+    sample_rate ||= @default_sample_rate
+    return unless sample?(sample_rate)
+    emit(datagram_builder(no_prefix: no_prefix).s(name, value, sample_rate, tags))
+  end
+
+  # Emits a distribution metric, which builds a histogram of the reported
+  # values.
+  #
+  # @note The distribution metric type is not available on all implementations.
+  #   A `NotImplemetedError` will be raised if you call this method, but
+  #   the active implementation does not support it.
+  #
+  # @param name (see #increment)
+  # @param [Numeric] value The value to include in the distribution histogram.
+  # @param sample_rate (see #increment)
+  # @param tags (see #increment)
+  # @return [void]
+  def distribution(name, value = nil, sample_rate: nil, tags: nil, no_prefix: false, &block)
+    if block_given?
+      return latency(name, sample_rate: sample_rate, tags: tags, metric_type: :d, no_prefix: no_prefix, &block)
+    end
+
+    sample_rate ||= @default_sample_rate
+    return unless sample?(sample_rate)
+    emit(datagram_builder(no_prefix: no_prefix).d(name, value, sample_rate, tags))
+  end
+
+  # Emits a histogram metric, which builds a histogram of the reported values.
+  #
+  # @note The histogram metric type is not available on all implementations.
+  #   A `NotImplemetedError` will be raised if you call this method, but
+  #   the active implementation does not support it.
+  #
+  # @param name (see #increment)
+  # @param [Numeric] value The value to include in the histogram.
+  # @param sample_rate (see #increment)
+  # @param tags (see #increment)
+  # @return [void]
+  def histogram(name, value, sample_rate: nil, tags: nil, no_prefix: false)
+    sample_rate ||= @default_sample_rate
+    return unless sample?(sample_rate)
+    emit(datagram_builder(no_prefix: no_prefix).h(name, value, sample_rate, tags))
+  end
+
+  # @!endgroup
+
+  # Measures the latency of the given block in milliseconds, and emits it as a metric.
+  #
+  # @param name (see #increment)
+  # @param sample_rate (see #increment)
+  # @param tags (see #increment)
+  # @param [Symbol] metric_type The metric type to use. If not specified, we will
+  #   use the preferred metric type of the implementation. The default is `:ms`.
+  #   Generally, you should not have to set this.
+  # @yield The latency (execution time) of the block
+  # @return The return value of the proivded block will be passed through.
+  def latency(name, sample_rate: nil, tags: nil, metric_type: nil, no_prefix: false)
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    begin
+      yield
+    ensure
+      stop = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      sample_rate ||= @default_sample_rate
+      if sample?(sample_rate)
+        metric_type ||= datagram_builder(no_prefix: no_prefix).latency_metric_type
+        latency_in_ms = 1000.0 * (stop - start)
+        emit(datagram_builder(no_prefix: no_prefix).send(metric_type, name, latency_in_ms, sample_rate, tags))
+      end
+    end
+  end
+
+  # Emits a service check.
+  #
+  # @param [String] title Event title.
+  # @param [String] text Event description. Newlines are allowed.
+  # @param [Time] timestamp The of the event. If not provided,
+  #   Datadog will interpret it as the current timestamp.
+  # @param [String] hostname A hostname to associate with the event.
+  # @param [String] aggregation_key An aggregation key to group events with the same key.
+  # @param [String] priority Priority of the event. Either "normal" (default) or "low".
+  # @param [String] source_type_name The source type of the event.
+  # @param [String] alert_type Either "error", "warning", "info" (default) or "success".
+  # @param [Array, Hash] tags Tags to associate with the event.
+  # @return [void]
+  #
+  # @note Supported by the Datadog implementation only.
+  def service_check(name, status, timestamp: nil, hostname: nil, tags: nil, message: nil, no_prefix: false)
+    emit(datagram_builder(no_prefix: no_prefix)._sc(name, status,
+      timestamp: timestamp, hostname: hostname, tags: tags, message: message))
+  end
+
+  # Emits an event.
+  #
+  # @param [String] name Name of the service
+  # @param [Symbol] status Either `:ok`, `:warning`, `:critical` or `:unknown`
+  # @param [Time] timestamp The moment when the service was checked. If not provided,
+  #   Datadog will interpret it as the current timestamp.
+  # @param [String] hostname A hostname to associate with the check.
+  # @param [Array, Hash] tags Tags to associate with the check.
+  # @param [String] message A message describing the current state of the service check.
+  # @return [void]
+  #
+  # @note Supported by the Datadog implementation only.
+  def event(title, text, timestamp: nil, hostname: nil, aggregation_key: nil, priority: nil,
+    source_type_name: nil, alert_type: nil, tags: nil, no_prefix: false)
+
+    emit(datagram_builder(no_prefix: no_prefix)._e(title, text, timestamp: timestamp,
+      hostname: hostname, tags: tags, aggregation_key: aggregation_key, priority: priority,
+      source_type_name: source_type_name, alert_type: alert_type))
+  end
+
+  # Instantiates a new StatsD client that uses the settings of the current client,
+  # except for the provided overrides.
+  #
+  # @yield [client] A new client will be constructed with the altered settings, and
+  #   yielded to the block. The original client will not be affected. The new client
+  #   will be disposed after the block returns
+  # @return The return value of the block will be passed on as return value.
+  def with_options(
+    sink: nil,
+    prefix: nil,
+    default_sample_rate: nil,
+    default_tags: nil,
+    datagram_builder_class: nil
+  )
+    client = clone_with_options(sink: sink, prefix: prefix,
+      default_sample_rate: default_sample_rate, default_tags: default_tags,
+      datagram_builder_class: datagram_builder_class)
+
+    yield(client)
+  end
+
+  def clone_with_options(
+    sink: nil,
+    prefix: nil,
+    default_sample_rate: nil,
+    default_tags: nil,
+    datagram_builder_class: nil
+  )
+    self.class.new(
+      sink: sink || @sink,
+      prefix: prefix || @prefix,
+      default_sample_rate: default_sample_rate || @default_sample_rate,
+      default_tags: default_tags || @default_tags,
+      datagram_builder_class: datagram_builder_class || @datagram_builder_class,
+    )
+  end
+
+  def capture_sink
+    StatsD::Instrument::CaptureSink.new(
+      parent: @sink,
+      datagram_class: datagram_builder(no_prefix: false).datagram_class,
+    )
+  end
+
+  def with_capture_sink(capture_sink)
+    @sink = capture_sink
+    yield
+  ensure
+    @sink = @sink.parent
+  end
+
+  # Captures metrics that were emitted during the provided block.
+  #
+  # @yield During the execution of the provided block, metrics will be captured.
+  # @return [Array<StatsD::Instagram::Datagram>] The list of metrics that were
+  #   emitted during the block, in the same order in which they were emitted.
+  def capture(&block)
+    sink = capture_sink
+    with_capture_sink(sink, &block)
+    sink.datagrams
+  end
+
+  protected
+
+  def datagram_builder(no_prefix:)
+    @datagram_builder[no_prefix] ||= @datagram_builder_class.new(
+      prefix: no_prefix ? nil : prefix,
+      default_tags: default_tags,
+    )
+  end
+
+  def sample?(sample_rate)
+    @sink.sample?(sample_rate)
+  end
+
+  def emit(datagram)
+    @sink << datagram
+    nil
+  end
+end

data/lib/statsd/instrument/datagram.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# The Datagram class parses and inspects a StatsD datagrans
+#
+# @note This class is part of the new Client implementation that is intended
+#   to become the new default in the next major release of this library.
+class StatsD::Instrument::Datagram
+  attr_reader :source
+
+  def initialize(source)
+    @source = source
+  end
+
+  # @return [Float] The sample rate at which this datagram was emitted, between 0 and 1.
+  def sample_rate
+    parsed_datagram[:sample_rate] ? Float(parsed_datagram[:sample_rate]) : 1.0
+  end
+
+  def type
+    parsed_datagram[:type]
+  end
+
+  def name
+    parsed_datagram[:name]
+  end
+
+  def value
+    parsed_datagram[:value]
+  end
+
+  def tags
+    @tags ||= parsed_datagram[:tags] ? parsed_datagram[:tags].split(',') : nil
+  end
+
+  def inspect
+    "#<#{self.class.name}:\"#{@source}\">"
+  end
+
+  def hash
+    source.hash
+  end
+
+  def eql?(other)
+    case other
+    when StatsD::Instrument::Datagram
+      source == other.source
+    when String
+      source == other
+    else
+      false
+    end
+  end
+
+  alias_method :==, :eql?
+
+  private
+
+  PARSER = %r{
+    \A
+    (?<name>[^\:\|\@]+)\:(?<value>[^\:\|\@]+)\|(?<type>c|ms|g|s|h|d)
+    (?:\|\@(?<sample_rate>\d*(?:\.\d*)?))?
+    (?:\|\#(?<tags>(?:[^\|\#,]+(?:,[^\|\#,]+)*)))?
+    \n? # In some implementations, the datagram may include a trailing newline.
+    \z
+  }x
+  private_constant :PARSER
+
+  def parsed_datagram
+    @parsed ||= if (match_info = PARSER.match(@source))
+      match_info
+    else
+      raise ArgumentError, "Invalid StatsD datagram: #{@source}"
+    end
+  end
+end

data/lib/statsd/instrument/datagram_builder.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# @note This class is part of the new Client implementation that is intended
+#   to become the new default in the next major release of this library.
+class StatsD::Instrument::DatagramBuilder
+  unless Regexp.method_defined?(:match?) # for ruby 2.3
+    module RubyBackports
+      refine Regexp do
+        def match?(str)
+          match(str) != nil
+        end
+      end
+    end
+
+    using RubyBackports
+  end
+
+  def self.unsupported_datagram_types(*types)
+    types.each do |type|
+      define_method(type) do |_, _, _, _|
+        raise NotImplementedError, "Type #{type} metrics are not suppered by #{self.class.name}."
+      end
+    end
+  end
+
+  def initialize(prefix: nil, default_tags: nil)
+    @prefix = prefix.nil? ? "" : "#{normalize_name(prefix)}."
+    @default_tags = normalize_tags(default_tags)
+  end
+
+  def c(name, value, sample_rate, tags)
+    generate_generic_datagram(name, value, 'c', sample_rate, tags)
+  end
+
+  def g(name, value, sample_rate, tags)
+    generate_generic_datagram(name, value, 'g', sample_rate, tags)
+  end
+
+  def ms(name, value, sample_rate, tags)
+    generate_generic_datagram(name, value, 'ms', sample_rate, tags)
+  end
+
+  def s(name, value, sample_rate, tags)
+    generate_generic_datagram(name, value, 's', sample_rate, tags)
+  end
+
+  def h(name, value, sample_rate, tags)
+    generate_generic_datagram(name, value, 'h', sample_rate, tags)
+  end
+
+  def d(name, value, sample_rate, tags)
+    generate_generic_datagram(name, value, 'd', sample_rate, tags)
+  end
+
+  def kv(name, value, sample_rate, tags)
+    generate_generic_datagram(name, value, 'kv', sample_rate, tags)
+  end
+
+  def datagram_class
+    StatsD::Instrument::Datagram
+  end
+
+  def latency_metric_type
+    :ms
+  end
+
+  protected
+
+  attr_reader :prefix, :default_tags
+
+  # Utility function to convert tags to the canonical form.
+  #
+  # - Tags specified as key value pairs will be converted into an array
+  # - Tags are normalized to remove unsupported characters
+  #
+  # @param tags [Array<String>, Hash<String, String>, nil] Tags specified in any form.
+  # @return [Array<String>, nil] the list of tags in canonical form.
+  def normalize_tags(tags)
+    return [] unless tags
+    tags = tags.map { |k, v| "#{k}:#{v}" } if tags.is_a?(Hash)
+
+    # Fast path when no string replacement is needed
+    return tags unless tags.any? { |tag| /[|,]/.match?(tag) }
+    tags.map { |tag| tag.tr('|,', '') }
+  end
+
+  # Utility function to remove invalid characters from a StatsD metric name
+  def normalize_name(name)
+    # Fast path when no normalization is needed to avoid copying the string
+    return name unless /[:|@]/.match?(name)
+    name.tr(':|@', '_')
+  end
+
+  def generate_generic_datagram(name, value, type, sample_rate, tags)
+    tags = normalize_tags(tags) + default_tags
+    datagram = +"#{@prefix}#{normalize_name(name)}:#{value}|#{type}"
+    datagram << "|@#{sample_rate}" if sample_rate && sample_rate < 1
+    datagram << "|##{tags.join(',')}" unless tags.empty?
+    datagram
+  end
+end

data/lib/statsd/instrument/dogstatsd_datagram_builder.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# @note This class is part of the new Client implementation that is intended
+#   to become the new default in the next major release of this library.
+class StatsD::Instrument::DogStatsDDatagramBuilder < StatsD::Instrument::DatagramBuilder
+  unsupported_datagram_types :kv
+
+  def latency_metric_type
+    :d
+  end
+
+  # Constricts an event datagram.
+  #
+  # @param [String] title Event title.
+  # @param [String] text Event description. Newlines are allowed.
+  # @param [Time] timestamp The of the event. If not provided,
+  #   Datadog will interpret it as the current timestamp.
+  # @param [String] hostname A hostname to associate with the event.
+  # @param [String] aggregation_key An aggregation key to group events with the same key.
+  # @param [String] priority Priority of the event. Either "normal" (default) or "low".
+  # @param [String] source_type_name The source type of the event.
+  # @param [String] alert_type Either "error", "warning", "info" (default) or "success".
+  # @param [Array, Hash] tags Tags to associate with the event.
+  # @return [String] The correctly formatted service check datagram
+  #
+  # @see https://docs.datadoghq.com/developers/dogstatsd/datagram_shell/#events
+  def _e(title, text, timestamp: nil, hostname: nil, aggregation_key: nil, priority: nil,
+    source_type_name: nil, alert_type: nil, tags: nil)
+
+    escaped_title = "#{@prefix}#{title}".gsub("\n", '\n')
+    escaped_text = text.gsub("\n", '\n')
+    tags = normalize_tags(tags) + default_tags
+
+    datagram = +"_e{#{escaped_title.length},#{escaped_text.length}}:#{escaped_title}|#{escaped_text}"
+    datagram << "|h:#{hostname}" if hostname
+    datagram << "|d:#{timestamp.to_i}" if timestamp
+    datagram << "|k:#{aggregation_key}" if aggregation_key
+    datagram << "|p:#{priority}" if priority
+    datagram << "|s:#{source_type_name}" if source_type_name
+    datagram << "|t:#{alert_type}" if alert_type
+    datagram << "|##{tags.join(',')}" unless tags.empty?
+    datagram
+  end
+
+  # Constricts a service check datagram.
+  #
+  # @param [String] name Name of the service
+  # @param [Symbol] status Either `:ok`, `:warning`, `:critical` or `:unknown`
+  # @param [Time] timestamp The moment when the service was checked. If not provided,
+  #   Datadog will interpret it as the current timestamp.
+  # @param [String] hostname A hostname to associate with the check.
+  # @param [Array, Hash] tags Tags to associate with the check.
+  # @param [String] message A message describing the current state of the service check.
+  # @return [String] The correctly formatted service check datagram
+  #
+  # @see https://docs.datadoghq.com/developers/dogstatsd/datagram_shell/#service-checks
+  def _sc(name, status, timestamp: nil, hostname: nil, tags: nil, message: nil)
+    status_number = status.is_a?(Integer) ? status : SERVICE_CHECK_STATUS_VALUES.fetch(status.to_sym)
+    tags = normalize_tags(tags) + default_tags
+
+    datagram = +"_sc|#{@prefix}#{normalize_name(name)}|#{status_number}"
+    datagram << "|h:#{hostname}" if hostname
+    datagram << "|d:#{timestamp.to_i}" if timestamp
+    datagram << "|##{tags.join(',')}" unless tags.empty?
+    datagram << "|m:#{normalize_name(message)}" if message
+    datagram
+  end
+
+  SERVICE_CHECK_STATUS_VALUES = { ok: 0, warning: 1, critical: 2, unknown: 3 }.freeze
+  private_constant :SERVICE_CHECK_STATUS_VALUES
+end