datadog-statsd-schema 0.1.0 → 0.1.2

data/lib/datadog/statsd/schema.rb

@@ -11,55 +11,131 @@ require_relative "schema/namespace"
 require_relative "schema/schema_builder"
 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.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Konstantin Gredeskoul
 bindir: exe
 cert_chain: []
-date: 2025-05-31 00:00:00.000000000 Z
+date: 2025-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -135,7 +135,12 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Datadog Schema for Statsd metrics and Tags
+description: This gem is an adapter for the dogstatsd-ruby gem. Unlike the Datadog::Statsd
+  metric sender, this gem supports pre-declaring schemas defining allowed metrics
+  and their types, the tags that apply to them, and tag values that must be validated
+  before streamed to Datadog. This approach allows for a more robust and consistent
+  way to ensure that metrics follow a well-thought-out naming scheme and are validated
+  before being sent to Datadog.
 email:
 - kigster@gmail.com
 executables:
@@ -143,10 +148,12 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".envrc"
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - CHANGELOG.md
+- FUTURE_DIRECTION.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -188,5 +195,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.6
 specification_version: 4
-summary: Datadog Schema for Statsd metrics and Tags
+summary: An adapter or wrapper for Datadog Statsd that allows pre-declaring of metrics,
+  tags and tag values and validating them against the schema.
 test_files: []