datadog-statsd-schema 0.1.0

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+require "dry-types"
+
+module Datadog
+  class Statsd
+    module Schema
+      class MetricDefinition < Dry::Struct
+        # Include the types module for easier access
+        module Types
+          include Dry.Types()
+        end
+
+        # Valid metric types in StatsD
+        VALID_METRIC_TYPES = %i[counter gauge histogram distribution timing set].freeze
+
+        attribute :name, Types::Strict::Symbol
+        attribute :type, Types::Strict::Symbol.constrained(included_in: VALID_METRIC_TYPES)
+        attribute :description, Types::String.optional.default(nil)
+        attribute :allowed_tags, Types::Array.of(Types::Symbol).default([].freeze)
+        attribute :required_tags, Types::Array.of(Types::Symbol).default([].freeze)
+        attribute :inherit_tags, Types::String.optional.default(nil)
+        attribute :units, Types::String.optional.default(nil)
+        attribute :namespace, Types::Strict::Symbol.optional.default(nil)
+
+        # Get the full metric name including namespace path
+        def full_name(namespace_path = [])
+          return name.to_s if namespace_path.empty?
+
+          "#{namespace_path.join(".")}.#{name}"
+        end
+
+        # Check if a tag is allowed for this metric
+        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
+        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
+        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
+        def invalid_tags(provided_tags)
+          return [] if allowed_tags.empty? # No restrictions
+
+          provided_tag_symbols = provided_tags.keys.map(&:to_sym)
+          provided_tag_symbols - allowed_tags
+        end
+
+        # Validate a complete tag set for this metric
+        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
+        def timing_metric?
+          %i[timing distribution histogram].include?(type)
+        end
+
+        # Check if this is a counting metric
+        def counting_metric?
+          %i[counter].include?(type)
+        end
+
+        # Check if this is a gauge metric
+        def gauge_metric?
+          type == :gauge
+        end
+
+        # Check if this is a set metric
+        def set_metric?
+          type == :set
+        end
+
+        # Get effective tags by merging with inherited tags if present
+        def effective_allowed_tags(schema_registry = nil)
+          return allowed_tags unless inherit_tags && schema_registry
+
+          inherited_metric = schema_registry.find_metric(inherit_tags)
+          return allowed_tags unless inherited_metric
+
+          (inherited_metric.effective_allowed_tags(schema_registry) + allowed_tags).uniq
+        end
+
+        def effective_required_tags(schema_registry = nil)
+          return required_tags unless inherit_tags && schema_registry
+
+          inherited_metric = schema_registry.find_metric(inherit_tags)
+          return required_tags unless inherited_metric
+
+          (inherited_metric.effective_required_tags(schema_registry) + required_tags).uniq
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+require "dry-types"
+require_relative "tag_definition"
+require_relative "metric_definition"
+
+module Datadog
+  class Statsd
+    module Schema
+      class Namespace < Dry::Struct
+        # Include the types module for easier access
+        module Types
+          include Dry.Types()
+        end
+
+        attribute :name, Types::Strict::Symbol
+        attribute :tags, Types::Hash.map(Types::Symbol, TagDefinition).default({}.freeze)
+        attribute :metrics, Types::Hash.map(Types::Symbol, MetricDefinition).default({}.freeze)
+        attribute :namespaces, Types::Hash.map(Types::Symbol, Namespace).default({}.freeze)
+        attribute :description, Types::String.optional.default(nil)
+
+        # Get the full path of this namespace
+        def full_path(parent_path = [])
+          return [name] if parent_path.empty?
+
+          parent_path + [name]
+        end
+
+        # Find a metric by name within this namespace
+        def find_metric(metric_name)
+          metric_symbol = metric_name.to_sym
+          metrics[metric_symbol]
+        end
+
+        # Find a tag definition by name within this namespace
+        def find_tag(tag_name)
+          tag_symbol = tag_name.to_sym
+          tags[tag_symbol]
+        end
+
+        # Find a nested namespace by name
+        def find_namespace(namespace_name)
+          namespace_symbol = namespace_name.to_sym
+          namespaces[namespace_symbol]
+        end
+
+        # Add a new metric to this namespace
+        def add_metric(metric_definition)
+          new(metrics: metrics.merge(metric_definition.name => metric_definition))
+        end
+
+        # Add a new tag definition to this namespace
+        def add_tag(tag_definition)
+          new(tags: tags.merge(tag_definition.name => tag_definition))
+        end
+
+        # Add a nested namespace
+        def add_namespace(namespace)
+          new(namespaces: namespaces.merge(namespace.name => namespace))
+        end
+
+        # Get all metric names in this namespace (not including nested)
+        def metric_names
+          metrics.keys
+        end
+
+        # Get all tag names in this namespace
+        def tag_names
+          tags.keys
+        end
+
+        # Get all nested namespace names
+        def namespace_names
+          namespaces.keys
+        end
+
+        # Check if this namespace contains a metric
+        def has_metric?(metric_name)
+          metric_symbol = metric_name.to_sym
+          metrics.key?(metric_symbol)
+        end
+
+        # Check if this namespace contains a tag definition
+        def has_tag?(tag_name)
+          tag_symbol = tag_name.to_sym
+          tags.key?(tag_symbol)
+        end
+
+        # Check if this namespace contains a nested namespace
+        def has_namespace?(namespace_name)
+          namespace_symbol = namespace_name.to_sym
+          namespaces.key?(namespace_symbol)
+        end
+
+        # Get all metrics recursively including from nested namespaces
+        def all_metrics(path = [])
+          # Filter out :root from the path to avoid it appearing in metric names
+          current_path = path + [name]
+          filtered_path = current_path.reject { |part| part == :root }
+          result = {}
+
+          # Add metrics from this namespace
+          metrics.each do |_metric_name, metric_def|
+            full_metric_name = metric_def.full_name(filtered_path)
+            result[full_metric_name] = {
+              definition: metric_def,
+              namespace_path: filtered_path,
+              namespace: self
+            }
+          end
+
+          # Add metrics from nested namespaces recursively
+          namespaces.each do |_, nested_namespace|
+            result.merge!(nested_namespace.all_metrics(current_path))
+          end
+
+          result
+        end
+
+        # Get all tag definitions including inherited from parent namespaces
+        def effective_tags(parent_tags = {})
+          parent_tags.merge(tags)
+        end
+
+        # Validate that all tag references in metrics exist
+        def validate_tag_references
+          errors = []
+
+          metrics.each do |metric_name, metric_def|
+            # Check allowed tags
+            metric_def.allowed_tags.each do |tag_name|
+              errors << "Metric #{metric_name} references unknown tag: #{tag_name}" unless has_tag?(tag_name)
+            end
+
+            # Check required tags
+            metric_def.required_tags.each do |tag_name|
+              errors << "Metric #{metric_name} requires unknown tag: #{tag_name}" unless has_tag?(tag_name)
+            end
+          end
+
+          # Validate nested namespaces recursively
+          namespaces.each do |_, nested_namespace|
+            errors.concat(nested_namespace.validate_tag_references)
+          end
+
+          errors
+        end
+
+        # Find metric by path (e.g., "request.duration" within web namespace)
+        def find_metric_by_path(path)
+          parts = path.split(".")
+
+          if parts.length == 1
+            # Single part, look for metric in this namespace
+            find_metric(parts.first)
+          else
+            # Multiple parts, navigate to nested namespace
+            namespace_name = parts.first
+            remaining_path = parts[1..-1].join(".")
+
+            nested_namespace = find_namespace(namespace_name)
+            return nil unless nested_namespace
+
+            nested_namespace.find_metric_by_path(remaining_path)
+          end
+        end
+
+        # Get namespace by path (e.g., "web.request")
+        def find_namespace_by_path(path)
+          return self if path.empty?
+
+          parts = path.split(".")
+
+          if parts.length == 1
+            find_namespace(parts.first)
+          else
+            namespace_name = parts.first
+            remaining_path = parts[1..-1].join(".")
+
+            nested_namespace = find_namespace(namespace_name)
+            return nil unless nested_namespace
+
+            nested_namespace.find_namespace_by_path(remaining_path)
+          end
+        end
+
+        # Count total metrics including nested namespaces
+        def total_metrics_count
+          metrics.count + namespaces.values.sum(&:total_metrics_count)
+        end
+
+        # Count total namespaces including nested
+        def total_namespaces_count
+          namespaces.count + namespaces.values.sum(&:total_namespaces_count)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require_relative "namespace"
+require_relative "tag_definition"
+require_relative "metric_definition"
+
+module Datadog
+  class Statsd
+    module Schema
+      class SchemaBuilder
+        attr_reader :transformers, :root_namespace
+
+        def initialize
+          @transformers = {}
+          @root_namespace = Namespace.new(name: :root)
+        end
+
+        # Define transformers that can be used by tag definitions
+        def transformers(&)
+          return @transformers unless block_given?
+
+          TransformerBuilder.new(@transformers).instance_eval(&)
+        end
+
+        # Define a namespace
+        def namespace(name, &)
+          builder = NamespaceBuilder.new(name, @transformers)
+          builder.instance_eval(&) if block_given?
+          namespace_def = builder.build
+
+          @root_namespace = @root_namespace.add_namespace(namespace_def)
+        end
+
+        # Build the final schema (returns the root namespace)
+        def build
+          @root_namespace
+        end
+
+        # Validate the schema for consistency
+        def validate!
+          errors = @root_namespace.validate_tag_references
+          raise SchemaError, "Schema validation failed: #{errors.join(", ")}" unless errors.empty?
+        end
+
+        # Helper class for building transformers
+        class TransformerBuilder
+          def initialize(transformers)
+            @transformers = transformers
+          end
+
+          def method_missing(name, proc = nil, &block)
+            @transformers[name.to_sym] = proc || block
+          end
+
+          def respond_to_missing?(_name, _include_private = false)
+            true
+          end
+        end
+
+        # Helper class for building namespaces
+        class NamespaceBuilder
+          attr_reader :name, :transformers, :tags, :metrics, :namespaces, :description
+
+          def initialize(name, transformers = {})
+            @name = name.to_sym
+            @transformers = transformers
+            @tags = {}
+            @metrics = {}
+            @namespaces = {}
+            @description = nil
+          end
+
+          # Set description for this namespace
+          def description(desc)
+            @description = desc
+          end
+
+          # Define tags for this namespace
+          def tags(&)
+            TagsBuilder.new(@tags, @transformers).instance_eval(&)
+          end
+
+          # Define metrics for this namespace
+          def metrics(&)
+            MetricsBuilder.new(@metrics, @transformers).instance_eval(&)
+          end
+
+          # Define nested namespace
+          def namespace(name, &)
+            builder = NamespaceBuilder.new(name, @transformers)
+            builder.instance_eval(&) if block_given?
+            @namespaces[name.to_sym] = builder.build
+          end
+
+          def build
+            Namespace.new(
+              name: @name,
+              description: @description,
+              tags: @tags,
+              metrics: @metrics,
+              namespaces: @namespaces
+            )
+          end
+        end
+
+        # Helper class for building tags within a namespace
+        class TagsBuilder
+          def initialize(tags, transformers)
+            @tags = tags
+            @transformers = transformers
+          end
+
+          def tag(name, **options)
+            tag_def = TagDefinition.new(
+              name: name.to_sym,
+              values: options[:values],
+              type: options[:type] || :string,
+              transform: Array(options[:transform] || []),
+              validate: options[:validate],
+              namespace: @current_namespace
+            )
+            @tags[name.to_sym] = tag_def
+          end
+        end
+
+        # Helper class for building metrics within a namespace
+        class MetricsBuilder
+          def initialize(metrics, transformers)
+            @metrics = metrics
+            @transformers = transformers
+            @current_namespace = nil
+          end
+
+          # Define a nested namespace for metrics
+          def namespace(name, &)
+            @current_namespace = name.to_sym
+            instance_eval(&)
+            @current_namespace = nil
+          end
+
+          # Define individual metric types
+          %i[counter gauge histogram distribution timing set].each do |metric_type|
+            define_method(metric_type) do |name, **options, &block|
+              metric_name = @current_namespace ? :"#{@current_namespace}_#{name}" : name.to_sym
+
+              metric_def = MetricDefinition.new(
+                name: metric_name,
+                type: metric_type,
+                description: options[:description],
+                allowed_tags: extract_allowed_tags(options),
+                required_tags: extract_required_tags(options),
+                inherit_tags: options[:inherit_tags],
+                units: options[:units],
+                namespace: @current_namespace
+              )
+
+              unless block.nil?
+                metric_builder = MetricBuilder.new(metric_def)
+                metric_builder.instance_eval(&block)
+                metric_def = metric_builder.build
+              end
+
+              @metrics[metric_name] = metric_def
+            end
+          end
+
+          private
+
+          def extract_allowed_tags(options)
+            tags_option = options[:tags]
+            return [] unless tags_option
+
+            if tags_option.is_a?(Hash)
+              Array(tags_option[:allowed] || []).map(&:to_sym)
+            else
+              Array(tags_option).map(&:to_sym)
+            end
+          end
+
+          def extract_required_tags(options)
+            tags_option = options[:tags]
+            return [] unless tags_option
+
+            if tags_option.is_a?(Hash)
+              Array(tags_option[:required] || []).map(&:to_sym)
+            else
+              []
+            end
+          end
+        end
+
+        # Helper class for building individual metrics with block syntax
+        class MetricBuilder
+          def initialize(metric_def)
+            @metric_def = metric_def
+          end
+
+          def description(desc)
+            @metric_def = @metric_def.new(description: desc)
+          end
+
+          def tags(**options)
+            allowed = Array(options[:allowed] || []).map(&:to_sym)
+            required = Array(options[:required] || []).map(&:to_sym)
+
+            @metric_def = @metric_def.new(
+              allowed_tags: allowed,
+              required_tags: required
+            )
+          end
+
+          def units(unit_name)
+            @metric_def = @metric_def.new(units: unit_name)
+          end
+
+          def inherit_tags(metric_path)
+            @metric_def = @metric_def.new(inherit_tags: metric_path)
+          end
+
+          def build
+            @metric_def
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+require "dry-types"
+
+module Datadog
+  class Statsd
+    module Schema
+      class TagDefinition < Dry::Struct
+        # Include the types module for easier access
+        module Types
+          include Dry.Types()
+        end
+
+        attribute :name, Types::Strict::Symbol
+        attribute :values, Types::Any.optional.default(nil) # Allow any type: Array, Regexp, Proc, or single value
+        attribute :type, Types::Strict::Symbol.default(:string)
+        attribute :transform, Types::Array.of(Types::Symbol).default([].freeze)
+        attribute :validate, Types::Any.optional.default(nil) # Proc for custom validation
+        attribute :namespace, Types::Strict::Symbol.optional.default(nil)
+
+        # Check if a value is allowed for this tag
+        def allows_value?(value)
+          return true if values.nil? # No restrictions
+
+          case values
+          when Array
+            values.include?(value) || values.include?(value.to_s) || values.include?(value.to_sym)
+          when Regexp
+            values.match?(value.to_s)
+          when Proc
+            values.call(value)
+          else
+            values == value
+          end
+        end
+
+        # Apply transformations to a value
+        def transform_value(value, transformers = {})
+          return value if transform.empty?
+
+          transform.reduce(value) do |val, transformer_name|
+            transformer = transformers[transformer_name]
+            transformer ? transformer.call(val) : val
+          end
+        end
+
+        # Validate a value using custom validation if present
+        def valid_value?(value, transformers = {})
+          transformed_value = transform_value(value, transformers)
+
+          # Apply type validation
+          case type
+          when :integer
+            return false unless transformed_value.is_a?(Integer) || transformed_value.to_s.match?(/^\d+$/)
+          when :string
+            # strings are generally permissive
+          when :symbol
+            # symbols are generally permissive, will be converted
+          end
+
+          # Apply custom validation if present
+          return validate.call(transformed_value) if validate.is_a?(Proc)
+
+          # Apply value restrictions
+          allows_value?(transformed_value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Datadog
+  class Statsd
+    module Schema
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/datadog/statsd/schema.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "datadog/statsd"
+require "active_support/core_ext/module/delegation"
+
+require_relative "schema/version"
+require_relative "schema/errors"
+require_relative "schema/tag_definition"
+require_relative "schema/metric_definition"
+require_relative "schema/namespace"
+require_relative "schema/schema_builder"
+require_relative "emitter"
+
+module Datadog
+  class << self
+    def emitter(...)
+      ::Datadog::Statsd::Emitter.new(...)
+    end
+
+    def schema(...)
+      ::Datadog::Statsd::Schema.new(...)
+    end
+  end
+
+  class Statsd
+    module Schema
+      class Error < StandardError
+      end
+
+      class << self
+        attr_accessor :in_test
+      end
+
+      self.in_test = false
+
+      # Create a new schema definition
+      def self.new(&)
+        builder = SchemaBuilder.new
+        builder.instance_eval(&) if block_given?
+        builder.build
+      end
+
+      # Load schema from a file
+      def self.load_file(path)
+        builder = SchemaBuilder.new
+        builder.instance_eval(File.read(path), path)
+        builder.build
+      end
+
+      # Configure the global schema
+      def self.configure
+        yield configuration
+      end
+
+      def self.configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Configuration class for global settings
+      class Configuration
+        attr_accessor :statsd, :schema, :tags
+
+        def initialize
+          @statsd = nil
+          @schema = nil
+          @tags = {}
+        end
+      end
+    end
+  end
+end