datadog-statsd-schema 0.1.1 → 0.2.0

data/lib/datadog/statsd/schema/commands/analyze.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+module Datadog
+  class Statsd
+    module Schema
+      module Commands
+        # @description Analyze a schema file for metrics and validation
+        class Analyze < Dry::CLI::Command
+          class << self
+            attr_accessor :stdout, :stderr
+          end
+
+          self.stdout = $stdout
+          self.stderr = $stderr
+
+          desc "Analyze a schema file for metrics and validation"
+
+          option :file, aliases: %w[-f], type: :string, required: true, desc: "Path to the schema file to analyze"
+          option :color, aliases: %w[-c], type: :boolean, required: false, desc: "Enable/Disable color output"
+
+          # @description Analyze a schema file for metrics and validation
+          # @param options [Hash] The options for the command
+          # @option options [String] :file The path to the schema file to analyze
+          # @option options [Boolean] :color Enable/Disable color output
+          # @return [void]
+          def call(**options)
+            file = options[:file]
+
+            unless file
+              warn "Error: --file option is required"
+              warn "Usage: dss analyze --file <schema.rb>"
+              exit 1
+            end
+
+            warn "Analyzing schema file: #{file}, color: #{options[:color]}"
+            @schema = ::Datadog::Statsd::Schema.load_file(file)
+            ::Datadog::Statsd::Schema::Analyzer.new([@schema],
+                                                    stdout: self.class.stdout,
+                                                    stderr: self.class.stderr,
+                                                    color: options[:color]).analyze
+          end
+
+          def warn(message)
+            self.class.stderr.puts message
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Datadog
+  class Statsd
+    module Schema
+      module Commands
+        # CLI commands will be defined here
+      end
+    end
+  end
+end
+
+# Require all command files
+require_relative "commands/analyze"

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
 

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::Typesa
         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