datadog-statsd-schema 0.1.1 → 0.2.0

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.2.0"
     end
   end
 end

data/lib/datadog/statsd/schema.rb

@@ -9,57 +9,135 @@ require_relative "schema/tag_definition"
 require_relative "schema/metric_definition"
 require_relative "schema/namespace"
 require_relative "schema/schema_builder"
+require_relative "schema/analyzer"
+require_relative "schema/cli"
 require_relative "emitter"
 
+# @author Konstantin Gredeskoul @ https://github.com/kigster
+# @since 0.1.0
+# @see https://github.com/DataDog/dogstatsd-ruby
 module Datadog
-  class << self
-    def emitter(...)
-      ::Datadog::Statsd::Emitter.new(...)
-    end
+  # Main StatsD client class that provides factory methods for creating emitters and schemas
+  # @see Datadog::Statsd::Emitter
+  # @see Datadog::Statsd::Schema
+  class Statsd
+    class << self
+      # Factory method to create a new Emitter instance
+      # @param args [Array] Arguments passed to Emitter.new
+      # @return [Datadog::Statsd::Emitter] A new emitter instance
+      # @see Datadog::Statsd::Emitter#initialize
+      def emitter(...)
+        ::Datadog::Statsd::Emitter.new(...)
+      end
 
-    def schema(...)
-      ::Datadog::Statsd::Schema.new(...)
+      # Factory method to create a new Schema instance
+      # @param block [Proc] Block to define the schema structure
+      # @return [Datadog::Statsd::Schema::Namespace] A new schema namespace
+      # @see Datadog::Statsd::Schema.new
+      def schema(...)
+        ::Datadog::Statsd::Schema.new(...)
+      end
     end
-  end
 
-  class Statsd
+    # Schema definition and validation module for StatsD metrics
+    # Provides a DSL for defining metric schemas with type safety and validation
+    # @example Basic schema definition
+    #   schema = Datadog::Statsd::Schema.new do
+    #     namespace :web do
+    #       tags do
+    #         tag :environment, values: [:production, :staging, :development]
+    #         tag :service, type: :string
+    #       end
+    #
+    #       metrics do
+    #         counter :requests_total, tags: { required: [:environment, :service] }
+    #         gauge :memory_usage, tags: { allowed: [:environment] }
+    #       end
+    #     end
+    #   end
+    # @author Datadog Team
+    # @since 0.1.0
     module Schema
+      # Base error class for all schema-related errors
+      # @see Datadog::Statsd::Schema::SchemaError
       class Error < StandardError
       end
 
       class << self
+        # Controls whether the schema is in test mode
+        # When true, colored output is disabled for test environments
+        # @return [Boolean] Test mode flag
         attr_accessor :in_test
       end
 
       self.in_test = false
 
-      # Create a new schema definition
+      # Create a new schema definition using the provided block
+      # @param block [Proc] Block containing schema definition DSL
+      # @return [Datadog::Statsd::Schema::Namespace] Root namespace of the schema
+      # @example
+      #   schema = Datadog::Statsd::Schema.new do
+      #     namespace :app do
+      #       tags do
+      #         tag :env, values: [:prod, :dev]
+      #       end
+      #       metrics do
+      #         counter :requests
+      #       end
+      #     end
+      #   end
       def self.new(&)
         builder = SchemaBuilder.new
         builder.instance_eval(&) if block_given?
         builder.build
       end
 
-      # Load schema from a file
+      # Load schema definition from a file
+      # @param path [String] Path to the schema definition file
+      # @return [Datadog::Statsd::Schema::Namespace] Root namespace of the loaded schema
+      # @raise [Errno::ENOENT] If the file doesn't exist
+      # @example
+      #   schema = Datadog::Statsd::Schema.load_file("config/metrics_schema.rb")
       def self.load_file(path)
         builder = SchemaBuilder.new
         builder.instance_eval(File.read(path), path)
         builder.build
       end
 
-      # Configure the global schema
+      # Configure global schema settings
+      # @param block [Proc] Configuration block
+      # @yield [Configuration] Configuration object for setting global options
+      # @example
+      #   Datadog::Statsd::Schema.configure do |config|
+      #     config.statsd = Datadog::Statsd.new('localhost', 8125)
+      #     config.tags = { environment: 'production' }
+      #   end
       def self.configure
         yield configuration
       end
 
+      # Get the global configuration object
+      # @return [Datadog::Statsd::Schema::Configuration] Global configuration instance
       def self.configuration
         @configuration ||= Configuration.new
       end
 
-      # Configuration class for global settings
+      # Global configuration class for schema settings
+      # Manages global StatsD client instance, schema, and tags
       class Configuration
-        attr_accessor :statsd, :schema, :tags
+        # Global StatsD client instance
+        # @return [Datadog::Statsd, nil] StatsD client or nil if not configured
+        attr_accessor :statsd
+
+        # Global schema instance
+        # @return [Datadog::Statsd::Schema::Namespace, nil] Schema or nil if not configured
+        attr_accessor :schema
+
+        # Global tags to be applied to all metrics
+        # @return [Hash] Hash of global tags
+        attr_accessor :tags
 
+        # Initialize a new configuration with default values
         def initialize
           @statsd = nil
           @schema = nil

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: datadog-statsd-schema
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
 bindir: exe
 cert_chain: []
-date: 2025-05-31 00:00:00.000000000 Z
+date: 2025-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: dry-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: dry-schema
   requirement: !ruby/object:Gem::Requirement
@@ -144,25 +158,32 @@ description: This gem is an adapter for the dogstatsd-ruby gem. Unlike the Datad
 email:
 - kigster@gmail.com
 executables:
-- datadog-statsd-schema
+- dss
 extensions: []
 extra_rdoc_files: []
 files:
+- ".envrc"
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - CHANGELOG.md
+- FUTURE_DIRECTION.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - examples/README.md
+- examples/schema/example_marathon.rb
 - examples/schema_emitter.png
 - examples/schema_emitter.rb
 - examples/shared.rb
 - examples/simple_emitter.rb
-- exe/datadog-statsd-schema
+- exe/dss
 - lib/datadog/statsd/emitter.rb
 - lib/datadog/statsd/schema.rb
+- lib/datadog/statsd/schema/analyzer.rb
+- lib/datadog/statsd/schema/cli.rb
+- lib/datadog/statsd/schema/commands.rb
+- lib/datadog/statsd/schema/commands/analyze.rb
 - lib/datadog/statsd/schema/errors.rb
 - lib/datadog/statsd/schema/metric_definition.rb
 - lib/datadog/statsd/schema/namespace.rb

data/exe/datadog-statsd-schema

@@ -1,3 +0,0 @@
-#!/usr/bin/env ruby
-
-require "datadog/statsd/schema"