datadog-statsd-schema 0.1.0 → 0.1.2

data/Rakefile

@@ -1,20 +1,20 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'timeout'
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "timeout"
 
 def shell(*args)
-  puts "running: #{args.join(' ')}"
-  system(args.join(' '))
+  puts "running: #{args.join(" ")}"
+  system(args.join(" "))
 end
 
 task :clean do
-  shell('rm -rf pkg/ tmp/ coverage/ doc/ ' )
+  shell("rm -rf pkg/ tmp/ coverage/ doc/ ")
 end
 
 task gem: [:build] do
-  shell('gem install pkg/*')
+  shell("gem install pkg/*")
 end
 
 task permissions: [:clean] do

data/examples/shared.rb

@@ -15,7 +15,7 @@ STATSD = Datadog::Statsd.new(
   "localhost", 8125
 )
 
-class FakeStatsd # rubocop:disable Style/Documentation
+class FakeStatsd
   def initialize(...); end
 
   def method_missing(m, *args, **opts)

data/lib/datadog/statsd/emitter.rb

@@ -51,14 +51,32 @@ module Datadog
         end
 
         extend Forwardable
-        def_delegators :datadog_statsd,
-                       :increment,
-                       :decrement,
-                       :gauge,
-                       :histogram,
-                       :distribution,
-                       :set,
-                       :flush
+        def_delegators :datadog_statsd, :flush
+
+        # Override metric methods to ensure global tags are applied
+        def increment(*args, **opts)
+          send_metric_with_global_tags(:increment, *args, **opts)
+        end
+
+        def decrement(*args, **opts)
+          send_metric_with_global_tags(:decrement, *args, **opts)
+        end
+
+        def gauge(*args, **opts)
+          send_metric_with_global_tags(:gauge, *args, **opts)
+        end
+
+        def histogram(*args, **opts)
+          send_metric_with_global_tags(:histogram, *args, **opts)
+        end
+
+        def distribution(*args, **opts)
+          send_metric_with_global_tags(:distribution, *args, **opts)
+        end
+
+        def set(*args, **opts)
+          send_metric_with_global_tags(:set, *args, **opts)
+        end
 
         def global_tags
           @global_tags ||= OpenStruct.new
@@ -68,6 +86,32 @@ module Datadog
           yield(global_tags)
         end
 
+        private
+
+        def send_metric_with_global_tags(method_name, *args, **opts)
+          # Ensure connection is established with global tags
+          connect unless datadog_statsd
+
+          # Merge global tags with provided tags
+          merged_tags = {}
+
+          # Add global tags from Schema configuration
+          schema_global_tags = ::Datadog::Statsd::Schema.configuration.tags || {}
+          merged_tags.merge!(schema_global_tags)
+
+          # Add global tags from Emitter configuration
+          emitter_global_tags = global_tags.to_h
+          merged_tags.merge!(emitter_global_tags)
+
+          # Add method-specific tags (these take precedence)
+          merged_tags.merge!(opts[:tags]) if opts[:tags]
+
+          # Update opts with merged tags
+          opts = opts.merge(tags: merged_tags) unless merged_tags.empty?
+
+          datadog_statsd.send(method_name, *args, **opts)
+        end
+
         def connect(
           host: DEFAULT_HOST,
           port: DEFAULT_PORT,
@@ -79,7 +123,14 @@ module Datadog
           return @datadog_statsd if defined?(@datadog_statsd) && @datadog_statsd
 
           tags ||= {}
+
+          # Merge global tags from Schema configuration
+          schema_global_tags = ::Datadog::Statsd::Schema.configuration.tags || {}
+          tags = tags.merge(schema_global_tags)
+
+          # Merge global tags from Emitter configuration
           tags = tags.merge(global_tags.to_h)
+
           tags = tags.map { |k, v| "#{k}:#{v}" }
 
           opts ||= {}
@@ -107,10 +158,24 @@ module Datadog
         end
       end
 
-      attr_reader :tags, :ab_test, :sample_rate, :metric, :schema, :validation_mode
-
+      attr_reader :tags, :ab_test, :sample_rate, :metric, :schema, :validation_mode, :stderr
+
+      # @description Initializes a new Statsd::Emitter instance.
+      # @param emitter [String, Symbol, Module, Class, Object] The emitter identifier.
+      # @param stderr [IO] The stderr output stream. Defaults to $stderr.
+      # @param metric [String] The metric name (or prefix) to use for all metrics.
+      # @param tags [Hash] The tags to add to the metric.
+      # @param ab_test [Hash] The AB test to add to the metric.
+      # @param sample_rate [Float] The sample rate to use for the metric.
+      # @param schema [Schema] The schema to use for validation.
+      # @param validation_mode [Symbol] The validation mode to use. Defaults to :strict.
+      #     :strict - Raises an error if the metric is invalid.
+      #     :warn - Logs a warning if the metric is invalid.
+      #     :drop - Drops the metric if it is invalid.
+      #     :off - Disables validation.
       def initialize(
         emitter = nil,
+        stderr: $stderr,
         metric: nil,
         tags: nil,
         ab_test: nil,
@@ -123,13 +188,23 @@ module Datadog
                 "Datadog::Statsd::Emitter: use class methods if you are passing nothing to the constructor."
         end
         @sample_rate = sample_rate || 1.0
-        @tags = tags || nil
-        @tags.merge!(self.class.global_tags.to_h) if self.class.global_tags.present?
+
+        # Initialize tags with provided tags or empty hash
+        @tags = (tags || {}).dup
+
+        # Merge global tags from Schema configuration
+        schema_global_tags = ::Datadog::Statsd::Schema.configuration.tags || {}
+        @tags.merge!(schema_global_tags)
+
+        # Merge global tags from Emitter configuration
+        emitter_global_tags = self.class.global_tags.to_h
+        @tags.merge!(emitter_global_tags)
 
         @ab_test = ab_test || {}
         @metric = metric
         @schema = schema
         @validation_mode = validation_mode
+        @stderr = stderr
 
         emitter =
           case emitter
@@ -146,7 +221,6 @@ module Datadog
 
         return unless emitter
 
-        @tags ||= {}
         @tags[:emitter] = emitter
       end
 
@@ -292,9 +366,16 @@ module Datadog
         end
 
         # Check for invalid tags (if metric has allowed_tags restrictions)
-        # Exclude framework tags like 'emitter' from validation
+        # Exclude framework tags and global tags from validation
         framework_tags = %i[emitter ab_test_name ab_test_group]
-        user_provided_tags = provided_tags.reject { |key, _| framework_tags.include?(key.to_sym) }
+
+        # Get global tags to exclude from validation
+        schema_global_tags = ::Datadog::Statsd::Schema.configuration.tags&.keys || []
+        emitter_global_tags = self.class.global_tags.to_h.keys
+        global_tag_keys = (schema_global_tags + emitter_global_tags).map(&:to_sym)
+
+        excluded_tags = framework_tags + global_tag_keys
+        user_provided_tags = provided_tags.reject { |key, _| excluded_tags.include?(key.to_sym) }
 
         invalid_tags = metric_definition.invalid_tags(user_provided_tags)
         if invalid_tags.any?
@@ -312,8 +393,8 @@ module Datadog
 
         # Validate tag values against schema definitions (including framework tags)
         provided_tags.each do |tag_name, tag_value|
-          # Skip validation for framework tags that don't have schema definitions
-          next if framework_tags.include?(tag_name.to_sym) && !effective_tags[tag_name.to_sym]
+          # Skip validation for framework tags and global tags that don't have schema definitions
+          next if excluded_tags.include?(tag_name.to_sym) && !effective_tags[tag_name.to_sym]
 
           tag_definition = effective_tags[tag_name.to_sym]
           next unless tag_definition
@@ -441,17 +522,17 @@ module Datadog
         when :strict
           # Only show colored output if not in test and colored2 is available
           if Datadog::Statsd::Schema.in_test
-            warn "Schema Validation Error: #{error.message}"
+            stderr.puts "Schema Validation Error: #{error.message}"
           else
-            warn "Schema Validation Error:\n • ".yellow + error.message.to_s.red
+            stderr.puts "Schema Validation Error:\n • ".yellow + error.message.to_s.red
           end
           raise error
         when :warn
           # Only show colored output if not in test and colored2 is available
           if Datadog::Statsd::Schema.in_test
-            warn "Schema Validation Warning: #{error.message}"
+            stderr.puts "Schema Validation Warning: #{error.message}"
           else
-            warn "Schema Validation Warning:\n • ".yellow + error.message.to_s.bold.yellow
+            stderr.puts "Schema Validation Warning:\n • ".yellow + error.message.to_s.bold.yellow
           end
           nil # Continue execution
         when :drop

data/lib/datadog/statsd/schema/errors.rb

@@ -3,12 +3,35 @@
 require "colored2"
 require "active_support/core_ext/string/inflections"
 
+# @author Datadog Team
+# @since 0.1.0
 module Datadog
   class Statsd
+    # Schema definition and validation module for StatsD metrics
     module Schema
+      # Base error class for all schema validation errors
+      # Provides context about where the error occurred including namespace, metric, and tag information
+      # @abstract Base class for schema validation errors
+      # @author Datadog Team
+      # @since 0.1.0
       class SchemaError < StandardError
-        attr_reader :namespace, :metric, :tag
+        # The namespace where the error occurred
+        # @return [String] Namespace path or placeholder if not available
+        attr_reader :namespace
 
+        # The metric name where the error occurred
+        # @return [String] Metric name or placeholder if not available
+        attr_reader :metric
+
+        # The tag name where the error occurred
+        # @return [String] Tag name or placeholder if not available
+        attr_reader :tag
+
+        # Initialize a new schema error with context information
+        # @param message [String, nil] Custom error message, will be auto-generated if nil
+        # @param namespace [String] Namespace context for the error
+        # @param metric [String] Metric context for the error
+        # @param tag [String] Tag context for the error
         def initialize(message = nil, namespace: "<-no-namespace->", metric: "<-no-metric->", tag: "<-no-tag->")
           @namespace = namespace
           @metric = metric
@@ -19,16 +42,46 @@ module Datadog
         end
       end
 
+      # Raised when a metric is used that doesn't exist in the schema
+      # @example
+      #   # This would raise UnknownMetricError if 'unknown_metric' is not defined in the schema
+      #   emitter.increment('unknown_metric')
       class UnknownMetricError < SchemaError; end
 
+      # Raised when a tag is used that doesn't exist in the schema or is not allowed for the metric
+      # @example
+      #   # This would raise InvalidTagError if 'invalid_tag' is not allowed for the metric
+      #   emitter.increment('valid_metric', tags: { invalid_tag: 'value' })
       class InvalidTagError < SchemaError; end
 
+      # Raised when a required tag is missing from a metric call
+      # @example
+      #   # This would raise MissingRequiredTagError if 'environment' tag is required
+      #   emitter.increment('metric_requiring_env_tag', tags: { service: 'web' })
       class MissingRequiredTagError < SchemaError; end
 
+      # Raised when a metric is called with the wrong type
+      # @example
+      #   # This would raise InvalidMetricTypeError if 'response_time' is defined as a histogram
+      #   emitter.increment('response_time')  # Should be emitter.histogram('response_time')
       class InvalidMetricTypeError < SchemaError; end
 
+      # Raised when attempting to define a metric that already exists in the schema
+      # @example Schema definition error
+      #   namespace :web do
+      #     metrics do
+      #       counter :requests
+      #       counter :requests  # This would raise DuplicateMetricError
+      #     end
+      #   end
       class DuplicateMetricError < SchemaError; end
 
+      # Raised when a namespace definition is invalid
+      # @example
+      #   # This might be raised for namespace naming conflicts or invalid structure
+      #   namespace :invalid_namespace do
+      #     # ... invalid configuration
+      #   end
       class InvalidNamespaceError < SchemaError; end
     end
   end

data/lib/datadog/statsd/schema/metric_definition.rb

@@ -3,28 +3,78 @@
 require "dry-struct"
 require "dry-types"
 
+# @author Datadog Team
+# @since 0.1.0
 module Datadog
   class Statsd
+    # Schema definition and validation module for StatsD metrics
     module Schema
+      # Represents a metric definition within a schema namespace
+      # Defines the metric type, allowed/required tags, validation rules, and metadata
+      # @example Basic metric definition
+      #   metric_def = MetricDefinition.new(
+      #     name: :page_views,
+      #     type: :counter,
+      #     allowed_tags: [:controller, :action],
+      #     required_tags: [:controller]
+      #   )
+      # @example Metric with description and units
+      #   metric_def = MetricDefinition.new(
+      #     name: :request_duration,
+      #     type: :distribution,
+      #     description: "HTTP request processing time",
+      #     units: "milliseconds",
+      #     allowed_tags: [:controller, :action, :status_code],
+      #     required_tags: [:controller, :action]
+      #   )
+      # @author Datadog Team
+      # @since 0.1.0
       class MetricDefinition < Dry::Struct
-        # Include the types module for easier access
+        # Include the types module for easier access to Dry::Types
         module Types
           include Dry.Types()
         end
 
-        # Valid metric types in StatsD
+        # Valid metric types supported by StatsD
         VALID_METRIC_TYPES = %i[counter gauge histogram distribution timing set].freeze
 
+        # The metric name as a symbol
+        # @return [Symbol] Metric name
         attribute :name, Types::Strict::Symbol
+
+        # The metric type (counter, gauge, histogram, distribution, timing, set)
+        # @return [Symbol] One of the valid metric types
         attribute :type, Types::Strict::Symbol.constrained(included_in: VALID_METRIC_TYPES)
+
+        # Human-readable description of what this metric measures
+        # @return [String, nil] Description text
         attribute :description, Types::String.optional.default(nil)
+
+        # Array of tag names that are allowed for this metric
+        # @return [Array<Symbol>] Allowed tag names (empty array means all tags allowed)
         attribute :allowed_tags, Types::Array.of(Types::Symbol).default([].freeze)
+
+        # Array of tag names that are required for this metric
+        # @return [Array<Symbol>] Required tag names
         attribute :required_tags, Types::Array.of(Types::Symbol).default([].freeze)
+
+        # Path to another metric to inherit tags from
+        # @return [String, nil] Dot-separated path to parent metric
         attribute :inherit_tags, Types::String.optional.default(nil)
+
+        # Units of measurement for this metric (e.g., "milliseconds", "bytes")
+        # @return [String, nil] Unit description
         attribute :units, Types::String.optional.default(nil)
+
+        # The namespace this metric belongs to
+        # @return [Symbol, nil] Namespace name
         attribute :namespace, Types::Strict::Symbol.optional.default(nil)
 
         # Get the full metric name including namespace path
+        # @param namespace_path [Array<Symbol>] Array of namespace names leading to this metric
+        # @return [String] Fully qualified metric name
+        # @example
+        #   metric_def.full_name([:web, :api])  # => "web.api.page_views"
         def full_name(namespace_path = [])
           return name.to_s if namespace_path.empty?
 
@@ -32,24 +82,44 @@ module Datadog
         end
 
         # Check if a tag is allowed for this metric
+        # @param tag_name [String, Symbol] Tag name to check
+        # @return [Boolean] true if tag is allowed (or no restrictions exist)
+        # @example
+        #   metric_def.allows_tag?(:controller)  # => true
+        #   metric_def.allows_tag?(:invalid_tag) # => false (if restrictions exist)
         def allows_tag?(tag_name)
           tag_symbol = tag_name.to_sym
           allowed_tags.empty? || allowed_tags.include?(tag_symbol)
         end
 
         # Check if a tag is required for this metric
+        # @param tag_name [String, Symbol] Tag name to check
+        # @return [Boolean] true if tag is required
+        # @example
+        #   metric_def.requires_tag?(:controller)  # => true
+        #   metric_def.requires_tag?(:optional_tag) # => false
         def requires_tag?(tag_name)
           tag_symbol = tag_name.to_sym
           required_tags.include?(tag_symbol)
         end
 
         # Get all missing required tags from a provided tag set
+        # @param provided_tags [Hash] Hash of tag names to values
+        # @return [Array<Symbol>] Array of missing required tag names
+        # @example
+        #   metric_def.missing_required_tags(controller: "users")
+        #   # => [:action] (if action is also required)
         def missing_required_tags(provided_tags)
           provided_tag_symbols = provided_tags.keys.map(&:to_sym)
           required_tags - provided_tag_symbols
         end
 
         # Get all invalid tags from a provided tag set
+        # @param provided_tags [Hash] Hash of tag names to values
+        # @return [Array<Symbol>] Array of invalid tag names
+        # @example
+        #   metric_def.invalid_tags(controller: "users", invalid: "value")
+        #   # => [:invalid] (if only controller is allowed)
         def invalid_tags(provided_tags)
           return [] if allowed_tags.empty? # No restrictions
 
@@ -58,31 +128,41 @@ module Datadog
         end
 
         # Validate a complete tag set for this metric
+        # @param provided_tags [Hash] Hash of tag names to values
+        # @return [Boolean] true if all tags are valid
+        # @example
+        #   metric_def.valid_tags?(controller: "users", action: "show")  # => true
         def valid_tags?(provided_tags)
           missing_required_tags(provided_tags).empty? && invalid_tags(provided_tags).empty?
         end
 
         # Check if this is a timing-based metric
+        # @return [Boolean] true for timing, distribution, or histogram metrics
         def timing_metric?
           %i[timing distribution histogram].include?(type)
         end
 
         # Check if this is a counting metric
+        # @return [Boolean] true for counter metrics
         def counting_metric?
           %i[counter].include?(type)
         end
 
         # Check if this is a gauge metric
+        # @return [Boolean] true for gauge metrics
         def gauge_metric?
           type == :gauge
         end
 
         # Check if this is a set metric
+        # @return [Boolean] true for set metrics
         def set_metric?
           type == :set
         end
 
-        # Get effective tags by merging with inherited tags if present
+        # Get effective allowed tags by merging with inherited tags if present
+        # @param schema_registry [Object] Registry to look up inherited metrics
+        # @return [Array<Symbol>] Combined allowed tags including inherited ones
         def effective_allowed_tags(schema_registry = nil)
           return allowed_tags unless inherit_tags && schema_registry
 
@@ -92,6 +172,9 @@ module Datadog
           (inherited_metric.effective_allowed_tags(schema_registry) + allowed_tags).uniq
         end
 
+        # Get effective required tags by merging with inherited tags if present
+        # @param schema_registry [Object] Registry to look up inherited metrics
+        # @return [Array<Symbol>] Combined required tags including inherited ones
         def effective_required_tags(schema_registry = nil)
           return required_tags unless inherit_tags && schema_registry