datadog-statsd-schema 0.1.1 → 0.1.2

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

@@ -5,22 +5,58 @@ require "dry-types"
 require_relative "tag_definition"
 require_relative "metric_definition"
 
+# @author Datadog Team
+# @since 0.1.0
 module Datadog
   class Statsd
+    # Schema definition and validation module for StatsD metrics
     module Schema
+      # Represents a namespace in the metric schema hierarchy
+      # Namespaces contain tags, metrics, and nested namespaces, providing organization and scoping
+      # @example Basic namespace
+      #   namespace = Namespace.new(
+      #     name: :web,
+      #     description: "Web application metrics"
+      #   )
+      # @example Namespace with tags and metrics
+      #   namespace = Namespace.new(
+      #     name: :api,
+      #     tags: { controller: tag_def, action: tag_def2 },
+      #     metrics: { requests: metric_def }
+      #   )
+      # @author Datadog Team
+      # @since 0.1.0
       class Namespace < 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
 
+        # The namespace name as a symbol
+        # @return [Symbol] Namespace name
         attribute :name, Types::Strict::Symbol
+
+        # Hash of tag definitions within this namespace
+        # @return [Hash<Symbol, TagDefinition>] Tag name to TagDefinition mapping
         attribute :tags, Types::Hash.map(Types::Symbol, TagDefinition).default({}.freeze)
+
+        # Hash of metric definitions within this namespace
+        # @return [Hash<Symbol, MetricDefinition>] Metric name to MetricDefinition mapping
         attribute :metrics, Types::Hash.map(Types::Symbol, MetricDefinition).default({}.freeze)
+
+        # Hash of nested namespaces within this namespace
+        # @return [Hash<Symbol, Namespace>] Namespace name to Namespace mapping
         attribute :namespaces, Types::Hash.map(Types::Symbol, Namespace).default({}.freeze)
+
+        # Human-readable description of this namespace
+        # @return [String, nil] Description text
         attribute :description, Types::String.optional.default(nil)
 
-        # Get the full path of this namespace
+        # Get the full path of this namespace including parent namespaces
+        # @param parent_path [Array<Symbol>] Array of parent namespace names
+        # @return [Array<Symbol>] Full namespace path
+        # @example
+        #   namespace.full_path([:web, :api])  # => [:web, :api, :request]
         def full_path(parent_path = [])
           return [name] if parent_path.empty?
 
@@ -28,72 +64,109 @@ module Datadog
         end
 
         # Find a metric by name within this namespace
+        # @param metric_name [String, Symbol] Name of the metric to find
+        # @return [MetricDefinition, nil] The metric definition or nil if not found
+        # @example
+        #   namespace.find_metric(:page_views)  # => MetricDefinition instance
         def find_metric(metric_name)
           metric_symbol = metric_name.to_sym
           metrics[metric_symbol]
         end
 
         # Find a tag definition by name within this namespace
+        # @param tag_name [String, Symbol] Name of the tag to find
+        # @return [TagDefinition, nil] The tag definition or nil if not found
+        # @example
+        #   namespace.find_tag(:controller)  # => TagDefinition instance
         def find_tag(tag_name)
           tag_symbol = tag_name.to_sym
           tags[tag_symbol]
         end
 
         # Find a nested namespace by name
+        # @param namespace_name [String, Symbol] Name of the namespace to find
+        # @return [Namespace, nil] The nested namespace or nil if not found
+        # @example
+        #   namespace.find_namespace(:api)  # => Namespace instance
         def find_namespace(namespace_name)
           namespace_symbol = namespace_name.to_sym
           namespaces[namespace_symbol]
         end
 
-        # Add a new metric to this namespace
+        # Add a new metric to this namespace (returns new namespace instance)
+        # @param metric_definition [MetricDefinition] The metric definition to add
+        # @return [Namespace] New namespace instance with the added metric
         def add_metric(metric_definition)
           new(metrics: metrics.merge(metric_definition.name => metric_definition))
         end
 
-        # Add a new tag definition to this namespace
+        # Add a new tag definition to this namespace (returns new namespace instance)
+        # @param tag_definition [TagDefinition] The tag definition to add
+        # @return [Namespace] New namespace instance with the added tag
         def add_tag(tag_definition)
           new(tags: tags.merge(tag_definition.name => tag_definition))
         end
 
-        # Add a nested namespace
+        # Add a nested namespace (returns new namespace instance)
+        # @param namespace [Namespace] The namespace to add
+        # @return [Namespace] New namespace instance with the added namespace
         def add_namespace(namespace)
           new(namespaces: namespaces.merge(namespace.name => namespace))
         end
 
         # Get all metric names in this namespace (not including nested)
+        # @return [Array<Symbol>] Array of metric names
         def metric_names
           metrics.keys
         end
 
         # Get all tag names in this namespace
+        # @return [Array<Symbol>] Array of tag names
         def tag_names
           tags.keys
         end
 
         # Get all nested namespace names
+        # @return [Array<Symbol>] Array of namespace names
         def namespace_names
           namespaces.keys
         end
 
         # Check if this namespace contains a metric
+        # @param metric_name [String, Symbol] Name of the metric to check
+        # @return [Boolean] true if metric exists
         def has_metric?(metric_name)
           metric_symbol = metric_name.to_sym
           metrics.key?(metric_symbol)
         end
 
         # Check if this namespace contains a tag definition
+        # @param tag_name [String, Symbol] Name of the tag to check
+        # @return [Boolean] true if tag exists
         def has_tag?(tag_name)
           tag_symbol = tag_name.to_sym
           tags.key?(tag_symbol)
         end
 
         # Check if this namespace contains a nested namespace
+        # @param namespace_name [String, Symbol] Name of the namespace to check
+        # @return [Boolean] true if namespace exists
         def has_namespace?(namespace_name)
           namespace_symbol = namespace_name.to_sym
           namespaces.key?(namespace_symbol)
         end
 
         # Get all metrics recursively including from nested namespaces
+        # @param path [Array<Symbol>] Current namespace path (used for recursion)
+        # @return [Hash] Hash mapping full metric names to metric info
+        # @example
+        #   {
+        #     "web.page_views" => {
+        #       definition: MetricDefinition,
+        #       namespace_path: [:web],
+        #       namespace: Namespace
+        #     }
+        #   }
         def all_metrics(path = [])
           # Filter out :root from the path to avoid it appearing in metric names
           current_path = path + [name]
@@ -119,11 +192,14 @@ module Datadog
         end
 
         # Get all tag definitions including inherited from parent namespaces
+        # @param parent_tags [Hash] Tag definitions from parent namespaces
+        # @return [Hash<Symbol, TagDefinition>] Combined tag definitions
         def effective_tags(parent_tags = {})
           parent_tags.merge(tags)
         end
 
         # Validate that all tag references in metrics exist
+        # @return [Array<String>] Array of validation error messages
         def validate_tag_references
           errors = []
 
@@ -148,6 +224,10 @@ module Datadog
         end
 
         # Find metric by path (e.g., "request.duration" within web namespace)
+        # @param path [String] Dot-separated path to the metric
+        # @return [MetricDefinition, nil] The metric definition or nil if not found
+        # @example
+        #   namespace.find_metric_by_path("api.requests")  # => MetricDefinition
         def find_metric_by_path(path)
           parts = path.split(".")
 
@@ -167,6 +247,10 @@ module Datadog
         end
 
         # Get namespace by path (e.g., "web.request")
+        # @param path [String] Dot-separated path to the namespace
+        # @return [Namespace, nil] The namespace or nil if not found
+        # @example
+        #   root_namespace.find_namespace_by_path("web.api")  # => Namespace
         def find_namespace_by_path(path)
           return self if path.empty?
 
@@ -186,11 +270,13 @@ module Datadog
         end
 
         # Count total metrics including nested namespaces
+        # @return [Integer] Total number of metrics in this namespace tree
         def total_metrics_count
           metrics.count + namespaces.values.sum(&:total_metrics_count)
         end
 
         # Count total namespaces including nested
+        # @return [Integer] Total number of namespaces in this namespace tree
         def total_namespaces_count
           namespaces.count + namespaces.values.sum(&:total_namespaces_count)
         end

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

@@ -4,18 +4,50 @@ require_relative "namespace"
 require_relative "tag_definition"
 require_relative "metric_definition"
 
+# @author Datadog Team
+# @since 0.1.0
 module Datadog
   class Statsd
+    # Schema definition and validation module for StatsD metrics
     module Schema
+      # Builder class for constructing metric schemas using a DSL
+      # Provides a fluent interface for defining namespaces, tags, and metrics
+      # @example Basic schema building
+      #   builder = SchemaBuilder.new
+      #   builder.namespace :web do
+      #     tags do
+      #       tag :controller, values: %w[users posts]
+      #     end
+      #     metrics do
+      #       counter :page_views, tags: { required: [:controller] }
+      #     end
+      #   end
+      #   schema = builder.build
+      # @author Datadog Team
+      # @since 0.1.0
       class SchemaBuilder
-        attr_reader :transformers, :root_namespace
+        # Hash of transformer functions available for tag transformations
+        # @return [Hash<Symbol, Proc>] Transformer name to proc mapping
+        attr_reader :transformers
 
+        # The root namespace of the schema being built
+        # @return [Namespace] Root namespace instance
+        attr_reader :root_namespace
+
+        # Initialize a new schema builder
         def initialize
           @transformers = {}
           @root_namespace = Namespace.new(name: :root)
         end
 
         # Define transformers that can be used by tag definitions
+        # @yield [TransformerBuilder] Block for defining transformers
+        # @return [Hash<Symbol, Proc>] Hash of defined transformers
+        # @example
+        #   builder.transformers do
+        #     underscore { |value| value.to_s.underscore }
+        #     downcase { |value| value.to_s.downcase }
+        #   end
         def transformers(&)
           return @transformers unless block_given?
 
@@ -23,6 +55,14 @@ module Datadog
         end
 
         # Define a namespace
+        # @param name [Symbol] Name of the namespace
+        # @yield [NamespaceBuilder] Block for defining namespace contents
+        # @return [void]
+        # @example
+        #   builder.namespace :web do
+        #     description "Web application metrics"
+        #     # ... tags and metrics definitions
+        #   end
         def namespace(name, &)
           builder = NamespaceBuilder.new(name, @transformers)
           builder.instance_eval(&) if block_given?
@@ -32,35 +72,76 @@ module Datadog
         end
 
         # Build the final schema (returns the root namespace)
+        # @return [Namespace] The root namespace containing the entire schema
         def build
           @root_namespace
         end
 
         # Validate the schema for consistency
+        # @raise [SchemaError] If schema validation fails
+        # @return [void]
         def validate!
           errors = @root_namespace.validate_tag_references
           raise SchemaError, "Schema validation failed: #{errors.join(", ")}" unless errors.empty?
         end
 
-        # Helper class for building transformers
+        # Helper class for building transformers within the DSL
+        # @api private
         class TransformerBuilder
+          # Initialize with the transformers hash
+          # @param transformers [Hash] Hash to store transformer definitions
           def initialize(transformers)
             @transformers = transformers
           end
 
+          # Dynamic method to define transformers
+          # @param name [Symbol] Name of the transformer
+          # @param proc [Proc] Transformer procedure (alternative to block)
+          # @yield [Object] Value to transform
+          # @return [void]
           def method_missing(name, proc = nil, &block)
             @transformers[name.to_sym] = proc || block
           end
 
+          # Always respond to any method for transformer definition
+          # @param _name [Symbol] Method name
+          # @param _include_private [Boolean] Whether to include private methods
+          # @return [Boolean] Always true
           def respond_to_missing?(_name, _include_private = false)
             true
           end
         end
 
-        # Helper class for building namespaces
+        # Helper class for building namespaces within the DSL
+        # @api private
         class NamespaceBuilder
-          attr_reader :name, :transformers, :tags, :metrics, :namespaces, :description
+          # Name of the namespace being built
+          # @return [Symbol] Namespace name
+          attr_reader :name
+
+          # Available transformers for tags
+          # @return [Hash<Symbol, Proc>] Transformer definitions
+          attr_reader :transformers
+
+          # Tag definitions for this namespace
+          # @return [Hash<Symbol, TagDefinition>] Tag definitions
+          attr_reader :tags
+
+          # Metric definitions for this namespace
+          # @return [Hash<Symbol, MetricDefinition>] Metric definitions
+          attr_reader :metrics
+
+          # Nested namespaces
+          # @return [Hash<Symbol, Namespace>] Nested namespace definitions
+          attr_reader :namespaces
+
+          # Description of this namespace
+          # @return [String, nil] Description text
+          attr_reader :description
 
+          # Initialize a new namespace builder
+          # @param name [Symbol] Name of the namespace
+          # @param transformers [Hash] Available transformer functions
           def initialize(name, transformers = {})
             @name = name.to_sym
             @transformers = transformers
@@ -71,27 +152,48 @@ module Datadog
           end
 
           # Set description for this namespace
+          # @param desc [String] Description text
+          # @return [void]
           def description(desc)
             @description = desc
           end
 
           # Define tags for this namespace
+          # @yield [TagsBuilder] Block for defining tags
+          # @return [void]
+          # @example
+          #   tags do
+          #     tag :controller, values: %w[users posts]
+          #     tag :action, values: %w[index show create]
+          #   end
           def tags(&)
             TagsBuilder.new(@tags, @transformers).instance_eval(&)
           end
 
           # Define metrics for this namespace
+          # @yield [MetricsBuilder] Block for defining metrics
+          # @return [void]
+          # @example
+          #   metrics do
+          #     counter :page_views, tags: { required: [:controller] }
+          #     gauge :memory_usage
+          #   end
           def metrics(&)
             MetricsBuilder.new(@metrics, @transformers).instance_eval(&)
           end
 
           # Define nested namespace
+          # @param name [Symbol] Name of the nested namespace
+          # @yield [NamespaceBuilder] Block for defining nested namespace
+          # @return [void]
           def namespace(name, &)
             builder = NamespaceBuilder.new(name, @transformers)
             builder.instance_eval(&) if block_given?
             @namespaces[name.to_sym] = builder.build
           end
 
+          # Build the namespace instance
+          # @return [Namespace] The constructed namespace
           def build
             Namespace.new(
               name: @name,
@@ -104,12 +206,27 @@ module Datadog
         end
 
         # Helper class for building tags within a namespace
+        # @api private
         class TagsBuilder
+          # Initialize with tags hash and transformers
+          # @param tags [Hash] Hash to store tag definitions
+          # @param transformers [Hash] Available transformer functions
           def initialize(tags, transformers)
             @tags = tags
             @transformers = transformers
           end
 
+          # Define a tag
+          # @param name [Symbol] Name of the tag
+          # @param options [Hash] Tag options
+          # @option options [Array, Regexp, Proc] :values Allowed values
+          # @option options [Symbol] :type Data type (:string, :integer, :symbol)
+          # @option options [Array<Symbol>] :transform Transformation functions to apply
+          # @option options [Proc] :validate Custom validation function
+          # @return [void]
+          # @example
+          #   tag :controller, values: %w[users posts], type: :string
+          #   tag :status_code, type: :integer, validate: ->(code) { (100..599).include?(code) }
           def tag(name, **options)
             tag_def = TagDefinition.new(
               name: name.to_sym,
@@ -124,7 +241,11 @@ module Datadog
         end
 
         # Helper class for building metrics within a namespace
+        # @api private
         class MetricsBuilder
+          # Initialize with metrics hash and transformers
+          # @param metrics [Hash] Hash to store metric definitions
+          # @param transformers [Hash] Available transformer functions
           def initialize(metrics, transformers)
             @metrics = metrics
             @transformers = transformers
@@ -132,6 +253,9 @@ module Datadog
           end
 
           # Define a nested namespace for metrics
+          # @param name [Symbol] Namespace name
+          # @yield Block for defining metrics within the namespace
+          # @return [void]
           def namespace(name, &)
             @current_namespace = name.to_sym
             instance_eval(&)
@@ -140,6 +264,15 @@ module Datadog
 
           # Define individual metric types
           %i[counter gauge histogram distribution timing set].each do |metric_type|
+            # Define a metric of the specified type
+            # @param name [Symbol] Metric name
+            # @param options [Hash] Metric options
+            # @option options [String] :description Human-readable description
+            # @option options [Hash, Array] :tags Tag configuration
+            # @option options [String] :inherit_tags Path to metric to inherit from
+            # @option options [String] :units Unit of measurement
+            # @yield [MetricBuilder] Block for additional metric configuration
+            # @return [void]
             define_method(metric_type) do |name, **options, &block|
               metric_name = @current_namespace ? :"#{@current_namespace}_#{name}" : name.to_sym
 
@@ -166,6 +299,9 @@ module Datadog
 
           private
 
+          # Extract allowed tags from options
+          # @param options [Hash] Metric options
+          # @return [Array<Symbol>] Allowed tag names
           def extract_allowed_tags(options)
             tags_option = options[:tags]
             return [] unless tags_option
@@ -177,6 +313,9 @@ module Datadog
             end
           end
 
+          # Extract required tags from options
+          # @param options [Hash] Metric options
+          # @return [Array<Symbol>] Required tag names
           def extract_required_tags(options)
             tags_option = options[:tags]
             return [] unless tags_option
@@ -190,15 +329,26 @@ module Datadog
         end
 
         # Helper class for building individual metrics with block syntax
+        # @api private
         class MetricBuilder
+          # Initialize with a metric definition
+          # @param metric_def [MetricDefinition] Initial metric definition
           def initialize(metric_def)
             @metric_def = metric_def
           end
 
+          # Set metric description
+          # @param desc [String] Description text
+          # @return [void]
           def description(desc)
             @metric_def = @metric_def.new(description: desc)
           end
 
+          # Configure metric tags
+          # @param options [Hash] Tag configuration
+          # @option options [Array] :allowed Allowed tag names
+          # @option options [Array] :required Required tag names
+          # @return [void]
           def tags(**options)
             allowed = Array(options[:allowed] || []).map(&:to_sym)
             required = Array(options[:required] || []).map(&:to_sym)
@@ -209,14 +359,22 @@ module Datadog
             )
           end
 
+          # Set metric units
+          # @param unit_name [String] Unit description
+          # @return [void]
           def units(unit_name)
             @metric_def = @metric_def.new(units: unit_name)
           end
 
+          # Set metric inheritance
+          # @param metric_path [String] Path to parent metric
+          # @return [void]
           def inherit_tags(metric_path)
             @metric_def = @metric_def.new(inherit_tags: metric_path)
           end
 
+          # Build the final metric definition
+          # @return [MetricDefinition] The constructed metric definition
           def build
             @metric_def
           end

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

@@ -3,23 +3,65 @@
 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 tag definition within a schema namespace
+      # Defines validation rules, allowed values, transformations, and type constraints for tags
+      # @example Basic tag definition
+      #   tag_def = TagDefinition.new(
+      #     name: :environment,
+      #     values: [:production, :staging, :development],
+      #     type: :symbol
+      #   )
+      # @example Tag with custom validation
+      #   tag_def = TagDefinition.new(
+      #     name: :user_id,
+      #     type: :integer,
+      #     validate: ->(value) { value > 0 }
+      #   )
+      # @author Datadog Team
+      # @since 0.1.0
       class TagDefinition < 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
 
+        # The tag name as a symbol
+        # @return [Symbol] Tag name
         attribute :name, Types::Strict::Symbol
-        attribute :values, Types::Any.optional.default(nil) # Allow any type: Array, Regexp, Proc, or single value
+
+        # Allowed values for this tag (can be Array, Regexp, Proc, or single value)
+        # @return [Array, Regexp, Proc, Object, nil] Allowed values constraint
+        attribute :values, Types::Any.optional.default(nil)
+
+        # The expected data type for tag values
+        # @return [Symbol] Type constraint (:string, :integer, :symbol)
         attribute :type, Types::Strict::Symbol.default(:string)
+
+        # Array of transformation functions to apply to values
+        # @return [Array<Symbol>] Transformation function names
         attribute :transform, Types::Array.of(Types::Symbol).default([].freeze)
-        attribute :validate, Types::Any.optional.default(nil) # Proc for custom validation
+
+        # Custom validation procedure for tag values
+        # @return [Proc, nil] Custom validation function
+        attribute :validate, Types::Any.optional.default(nil)
+
+        # The namespace this tag belongs to
+        # @return [Symbol, nil] Namespace name
         attribute :namespace, Types::Strict::Symbol.optional.default(nil)
 
-        # Check if a value is allowed for this tag
+        # Check if a value is allowed for this tag according to the values constraint
+        # @param value [Object] The value to check
+        # @return [Boolean] true if the value is allowed
+        # @example
+        #   tag_def = TagDefinition.new(name: :env, values: [:prod, :dev])
+        #   tag_def.allows_value?(:prod)  # => true
+        #   tag_def.allows_value?(:test)  # => false
         def allows_value?(value)
           return true if values.nil? # No restrictions
 
@@ -35,7 +77,14 @@ module Datadog
           end
         end
 
-        # Apply transformations to a value
+        # Apply transformations to a value using the provided transformer functions
+        # @param value [Object] The value to transform
+        # @param transformers [Hash<Symbol, Proc>] Hash of transformer name to proc mappings
+        # @return [Object] The transformed value
+        # @example
+        #   tag_def = TagDefinition.new(name: :service, transform: [:downcase])
+        #   transformers = { downcase: ->(val) { val.to_s.downcase } }
+        #   tag_def.transform_value("WEB-SERVICE", transformers)  # => "web-service"
         def transform_value(value, transformers = {})
           return value if transform.empty?
 
@@ -45,7 +94,18 @@ module Datadog
           end
         end
 
-        # Validate a value using custom validation if present
+        # Validate a value using type checking, transformations, and custom validation
+        # @param value [Object] The value to validate
+        # @param transformers [Hash<Symbol, Proc>] Hash of transformer name to proc mappings
+        # @return [Boolean] true if the value is valid
+        # @example
+        #   tag_def = TagDefinition.new(
+        #     name: :port,
+        #     type: :integer,
+        #     validate: ->(val) { val > 0 && val < 65536 }
+        #   )
+        #   tag_def.valid_value?(8080)   # => true
+        #   tag_def.valid_value?(-1)     # => false
         def valid_value?(value, transformers = {})
           transformed_value = transform_value(value, transformers)
 

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

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
+# @author Datadog Team
+# @since 0.1.0
 module Datadog
   class Statsd
+    # Schema definition and validation module for StatsD metrics
     module Schema
-      VERSION = "0.1.1"
+      # Current version of the datadog-statsd-schema gem
+      # @return [String] The semantic version string
+      VERSION = "0.1.2"
     end
   end
 end