datadog-statsd-schema 0.1.1 → 0.2.0

data/README.md

@@ -1,359 +1,410 @@
 [![RSpec and Rubocop](https://github.com/kigster/datadog-statsd-schema/actions/workflows/ruby.yml/badge.svg)](https://github.com/kigster/datadog-statsd-schema/actions/workflows/ruby.yml)
 
-# Datadog::Statsd::Schema
+# Datadog StatsD Schema
 
-This is a wrapper around  [dogstatsd-ruby](https://github.com/DataDog/dogstatsd-ruby) gem that sends custom metrics via StatsD, with additional layer of validation based on a configurable schemas. Schemas can validate allowed metric names, associated tag and tag values. This approach can guide an organization towards a clear declarative approach to metrics and their tags, and then emitting them from within the application with the insurance that any invalid value would raise an exception. 
+A Ruby gem that provides comprehensive schema definition, validation, and cost analysis for Datadog StatsD metrics. This library helps teams prevent metric explosion, control costs, and maintain consistent metric naming conventions.
 
-We invite you to explore some of the provided [examples](./examples/README.md) which can be run from project's root, and are described in the linked README.
+## Features
 
-## Introduction
+- **Schema Definition**: Define metric schemas with type safety and validation
+- **Tag Management**: Centralized tag definitions with inheritance and validation
+- **Cost Analysis**: Analyze potential custom metric costs before deployment
+- **Metric Validation**: Runtime validation of metrics against defined schemas
+- **CLI Tools**: Command-line interface for schema analysis and validation
+- **Global Configuration**: Centralized configuration for tags and StatsD clients
 
-This is an extension to gem [dogstatsd-ruby](https://github.com/DataDog/dogstatsd-ruby) which enhances the original with a robust schema definition for both the custom metrics being sent, and the tags allowed (or required) to attach to the metric. 
+## Installation
 
-There are several interfaces to `Datadog::Statsd` instance — you can use the class methods of `Datadog::Statsd::Emitter`, and pass the typical statsd methods. But you can also use an instance of this class, which adds a number of features and powerful shortcuts. 
+Add this line to your application's Gemfile:
 
-If you do not pass the schema argument to the emitter, it will act as a wrapper around `Datadog::Statsd` instance: it will merge the global and local tags together, it will concatenate metric names together, so it's quite useful on it' on.
+```ruby
+gem 'datadog-statsd-schema'
+```
 
-But the real power comes from defining a Schema of metrics and tags, and providing the schema to the Emitter as a constructor argument. In that case every metric send will be validated against the schema.
- 
-## Metric Types
+And then execute:
 
-> For more information about the metrics, please see the [Datadog Documentation](https://docs.datadoghq.com/metrics/custom_metrics/dogstatsd_metrics_submission/?tab=ruby).
+```bash
+bundle install
+```
 
-There are 5 total metric types you can send with Statsd, and it's important to understand the differences:
+Or install it yourself as:
 
-* `COUNT` (eg, `Datadog::Statsd::Emitter.increment('emails.sent', by: 2)`)
-* `GAUGE` (eg, `Datadog::Statsd::Emitter.gauge('users.on.site', 100)`)
-* `HISTOGRAM` (eg, `Datadog::Statsd::Emitter.histogram('page.load.time', 100)`)
-* `DISTRIBUTION` (eg,`Datadog::Statsd::Emitter.distribution('page.load.time', 100)`)
-* `SET` (eg, `Datadog::Statsd::Emitter.set('users.unique', '12345')`)
+```bash
+gem install datadog-statsd-schema
+```
 
-NOTE: that `HISTOGRAM` converts your metric into FIVE separate metrics (with suffixes .`max`, .`median`, `avg`, .`count`, `p95`), while `DISTRIBUTION` explodes into TEN separate metrics (see the documentation). Do NOT use SET unless you know what you are doing.
+## Quick Start
 
-You can send metrics via class methods of `Datadog::Statsd::Emitter`, or by instantiating the class.
+### Basic Schema Definition
 
-## Sending Metrics 
+```ruby
+require 'datadog/statsd/schema'
+
+# Define your metrics schema
+schema = Datadog::Statsd::Schema.new do
+  namespace :web do
+    tags do
+      tag :environment, values: %w[production staging development]
+      tag :service, values: %w[api web worker]
+      tag :region, values: %w[us-east-1 us-west-2]
+    end
 
-### Class Methods
+    metrics do
+      counter :requests_total do
+        description "Total HTTP requests"
+        tags required: [:environment, :service], allowed: [:region]
+      end
 
-This is the most straightforward way of using this gem. You can just pass your metric names and tags to the standard operations on Statsd, just like so:
+      gauge :memory_usage do
+        description "Memory usage in bytes"
+        tags required: [:environment], allowed: [:service, :region]
+      end
 
-```ruby
-  require 'datadog/statsd'
-  require 'datadog/statsd/schema'
-
-  Datadog::Statsd::Emitter.increment(
-    'marathon.started.total', 
-    by: 7, 
-    tags: { 
-        course: "sf-marathon", 
-        length: 26.212, 
-        units: "miles" 
-    },
-    schema: ....
-  )
+      distribution :request_duration do
+        description "Request processing time in milliseconds"
+        tags required: [:environment, :service]
+      end
+    end
+  end
+end
 ```
 
-As you can see, the API is identical to `Datadog::Statsd`. The main difference is that, if you provide a schema argument, the metric `marathon.started.total` must be pre-declared using the schema DSL language. In addition, the metric type ("count") and all of the tags and their possible values must be predeclared in the schema. Schema does support opening up a tag to any number of values, but that is not recommended.
+### Using the Emitter with Schema Validation
 
-So let's look at a more elaborate use case.
+```ruby
+# Configure global settings
+Datadog::Statsd::Schema.configure do |config|
+  config.statsd = Datadog::Statsd.new('localhost', 8125)
+  config.schema = schema
+  config.tags = { environment: 'production' }
+end
+
+# Create an emitter with validation
+emitter = Datadog::Statsd::Emitter.new(
+  schema: schema,
+  validation_mode: :strict  # :strict, :warn, or :disabled
+)
 
-### Defining Schema 
+# Send metrics with automatic validation
+emitter.increment('web.requests_total', tags: { service: 'api', region: 'us-east-1' })
+emitter.gauge('web.memory_usage', 512_000_000, tags: { service: 'api' })
+emitter.distribution('web.request_duration', 45.2, tags: { service: 'api' })
+```
 
-Below is an example of configuring the gem by creating a schema using the provided DSL. This can be a single global schema or assigned to a specific Statsd Sender, although you can have any number of Senders of type `Datadog::Statsd::Emitter` that map to a new connection and new defaults.
+## CLI Usage
 
-```ruby
-  require 'etc'
-  require 'git'
+The gem provides a command-line interface for analyzing schemas and understanding their cost implications.
 
-  require 'datadog/statsd'
-  require 'datadog/statsd/schema'
+### Installation
 
-  # Define the global statsd instance that we'll use to send data through
-  $statsd = ::Datadog::Statsd.new(
-    'localhost', 8125, 
-    delay_serialization: true
-  )
+After installing the gem, the `dss` (Datadog StatsD Schema) command will be available:
 
-  # Configure the schema with global tags and the above-created Statsd instance
-  Datadog::Statsd::Schema.configure do |config|
-    # This configures the global tags that will be attached to all methods
-    config.tags = { 
-      env: "development",
-      arch: Etc.uname[:machine],
-      version: Git.open('.').object('HEAD').sha
-    }
-    
-    config.statsd = $statsd
-  end
+```bash
+dss --help
+```
 
-  # Now we'll create a Schema using the provided Schema DSL:
-  schema = Datadog.schema do
-    # Transformers can be attached to the tags, and applied before the tags are submitted
-    # or validated.
-    transformers do
-      underscore: ->(text) { text.underscore },
-      downcase: ->(text) { text.downcase }
-    end
+### Schema Analysis
 
-    namespace :marathon do
-      tags do
-        tag :course, 
-            values: ["san francisco", "boston", "new york"],         
-            transform: %i[downcase underscore],
+Create a schema file (e.g., `metrics_schema.rb`):
 
-        tag :marathon_type, values: %w[half full]
-        tag :status, values: %w[finished no-show incomplete]
-        tag :sponsorship, values: %w[nike cocacola redbull]
+```ruby
+namespace :web do
+  tags do
+    tag :environment, values: %w[production staging development]
+    tag :service, values: %w[api web worker]
+    tag :region, values: %w[us-east-1 us-west-2 eu-west-1]
+  end
+
+  namespace :requests do
+    metrics do
+      counter :total do
+        description "Total HTTP requests"
+        tags required: [:environment, :service], allowed: [:region]
       end
 
-      metrics do 
-        # This defines a single metric "marathon.started.total"
-        namespace :started do
-          counter :total do
-            description "Incrementing - the total number of people who were registered for this marathon"
-            tags required: %i[ course marathon_type ],
-                  allowed:  %i[ sponsorship ]
-          end
-        end
-
-        # defines two metrics: a counter metric named "marathon.finished.total" and
-        # a distribution metric "marathon.finished.duration"
-        namespace :finished do
-          counter :total, inherit_tags: "marathon.started.total",
-            description "The number of people who finished a given marathon"
-            tags required: %i[ status ]
-          end
-
-          distribution :duration, units: "minutes", inherit_tags: "marathon.finished.count" do
-            description "The distribution of all finish times registered."
-          end
-        end   
+      distribution :duration do
+        description "Request processing time in milliseconds"
+        inherit_tags "web.requests.total"
       end
     end
   end
 
-  my_sender = Datadog.emitter(
-    metric: 'marathon',
-    schema: schema,
-    validation_mode: :strict,
-    tags: { marathon_type: :full, course: "san-francisco" }
-  )
-
-  my_sender.increment('started.total', by: 43579) # register all participants at start
-  # time passes, first runners start to arrive
-  my_sender.increment('finished.total') # register one at a time
-  my_sender.distribution('finished.duration', 33.21, tags: { sponsorship: 'nike' })
-  ... 
-  my_sender.increment('finished.total')
-  my_sender.distribution('finished.duration', 35.09, tags: { sponsorship: "redbull" })
+  metrics do
+    gauge :memory_usage do
+      description "Memory usage in bytes"
+      tags required: [:environment], allowed: [:service]
+    end
+  end
+end
 ```
 
-In this case, the schema will validate that the metrics are named `marathon.finished.total` and `marathon.finished.duration`, and that their tags are appropriately defined.
+Analyze the schema to understand metric costs:
 
-```ruby
-  finish_sender = Datadog.emitter(
-    schema: schema,
-    validation_mode: :warn,
-    metric: "marathon.finished", 
-    tags: { marathon_type: :full, course: "san-francisco" }
-  )
-  finish.increment("total")
-  finish.distribution("duration", 34)
+```bash
+dss analyze --file metrics_schema.rb
 ```
 
-The above code will transmit the following metric, with the following tags:
-
-```ruby
-$statsd.increment(
-  "marathon.finished.total", 
-  tags: { marathon_type: :full, course: "san-francisco" }
-)
-
-$statsd.distribution(
-  "marathon.finished.duration", 
-  tags: { marathon_type: :full, course: "san-francisco" }
-)
+**Output:**
+```
+┌──────────────────────────────────────────────────────────────────────────────────────────────┐
+│ Detailed Metric Analysis:                                                                    │
+└──────────────────────────────────────────────────────────────────────────────────────────────┘
+
+  • gauge('web.memory_usage')
+    Expanded names:
+      • web.memory_usage.count
+      • web.memory_usage.min
+      • web.memory_usage.max
+      • web.memory_usage.sum
+      • web.memory_usage.avg
+
+                              Unique tags:   2
+                         Total tag values:   6
+                    Possible combinations:  45
+
+ ──────────────────────────────────────────────────────────────────────────────────────────────
+
+  • counter('web.requests.total')
+
+                              Unique tags:   3
+                         Total tag values:   9
+                    Possible combinations:  27
+
+ ──────────────────────────────────────────────────────────────────────────────────────────────
+
+  • distribution('web.requests.duration')
+    Expanded names:
+      • web.requests.duration.count
+      • web.requests.duration.min
+      • web.requests.duration.max
+      • web.requests.duration.sum
+      • web.requests.duration.avg
+      • web.requests.duration.p50
+      • web.requests.duration.p75
+      • web.requests.duration.p90
+      • web.requests.duration.p95
+      • web.requests.duration.p99
+
+                              Unique tags:   3
+                         Total tag values:   9
+                    Possible combinations: 270
+
+ ──────────────────────────────────────────────────────────────────────────────────────────────
+┌──────────────────────────────────────────────────────────────────────────────────────────────┐
+│ Schema Analysis Results:                                                                     │
+│                                        SUMMARY                                               │
+└──────────────────────────────────────────────────────────────────────────────────────────────┘
+
+                     Total unique metrics:  16
+Total possible custom metric combinations: 342
 ```
 
-### Validation Mode
+This analysis shows that your schema will generate **342 custom metrics** across **16 unique metric names**. Understanding this before deployment helps prevent unexpected Datadog billing surprises.
 
-There are four validation modes you can pass to an emitter to accompany a schema:
+## Advanced Features
 
-1. `:strict` — raise an exception when anything is out of the ordinary is passed
-2. `:warn` — print to stderr and continue 
-3. `:drop` — drop this metric
-4. `:off` — no validation, as if schema was not even passed.
+### Tag Inheritance
 
-### An Example Tracking Web Performance
+Metrics can inherit tag configurations from other metrics to reduce duplication:
 
 ```ruby
- Datadog::Statsd::Schema.configure do |config|
-    config.statsd = $statsd
-    config.schema = Datadog::Statsd::Schema.new do
-      namespace "web" do
-        namespace "request" do
-          tags do
-            tag :uri,
-                values: %r{.*}
-
-            tag :logged_in,
-                values: %w[logged_in logged_out]
-
-            tag :billing_plan,
-                values: %w[premium trial free]
-
-            tag :controller, 
-                values: %r{[a-z.]*}, 
-                transform: [ :underscore, :downcase ]
-
-            tag :action, 
-                values: %r{[a-z.]*}, 
-                transform: [ :underscore, :downcase ]
-
-            tag :method, 
-                values: %i[get post put patch delete head options trace connect], 
-                transform: [ :downcase ]
-
-            tag :status_code, 
-                type: :integer, 
-                validate: ->(code) { (100..599).include?(code) }
-          end
-          
-          metrics do
-            # This distribution allows tracking of the latency of the request.
-            distribution :duration do
-              description "HTTP request processing time in milliseconds"
-              tags allowed: %w[controller action method status_code region]
-                  required: %w[controller]
-            end
-          
-            # This counter allows tracking the frequency of each controller/action
-            counter :total, inherit_tags: :duration do
-              description "Total number of requests received"
-            end
-          end
-        end
-      end
+namespace :api do
+  metrics do
+    counter :requests_total do
+      tags required: [:environment, :service], allowed: [:region]
+    end
+
+    # Inherits environment, service (required) and region (allowed) from requests_total
+    distribution :request_duration do
+      inherit_tags "api.requests_total"
+      tags required: [:endpoint]  # Adds endpoint as additional required tag
     end
   end
+end
 ```
 
+### Nested Namespaces
 
-Let's say this monitor only tracks requests from logged in premium users,  then you can provide those tags here, and they will be sent together with individual invocations:
+Organize metrics hierarchically with nested namespaces:
 
 ```ruby
-  # We'll use the shorthand version to create this Emitter.
-  # It's equivalent to *Datadog::Statsd::Emitter.new*
-  traffic_monitor = Datadog.emitter(
-    self,
-    metric: "web.request", 
-    tags: { billing_plan: :premium, logged_in: :logged_in }
-  )
-
-  my_sender.increment('total', tags: { uri: '/home/settings', method: :get } ) 
-  my_sender.distribution('duration', tags: { uri: '/home/settings', method: :get } ) 
+namespace :application do
+  tags do
+    tag :environment, values: %w[prod staging dev]
+  end
 
-  my_sender.increment('total', tags: { uri: '/app/calendar', method: :post} )
-  my_sender.distribution('duration', tags: { uri: '/app/calendar', method: :post } )
-```
-      
-The above code will send two metrics: `web.request.total` as a counter, tagged with: `{ billing_plan: :premium, logged_in: :logged_in, uri: '/home/settings' }` and the second time for the `uri: '/app/calendar'`. 
+  namespace :database do
+    tags do
+      tag :table_name, values: %w[users orders products]
+    end
 
-### Emitter
+    metrics do
+      counter :queries_total
+      distribution :query_duration
+    end
+  end
 
-You can create instances of this class and use the instance to emit custom metrics. You may want to do this, instead of using the class methods directly, for two reasons:
+  namespace :cache do
+    tags do
+      tag :cache_type, values: %w[redis memcached]
+    end
 
- 1. You want to send metrics from several places in the codebase, but have them share the "emitter" tag (which i.e. defines the source, a class, or object)emitting the metric, or any other tags for that matter.
+    metrics do
+      counter :hits_total
+      counter :misses_total
+    end
+  end
+end
+```
 
- 2. You want to send metrics with a different sample rate than the defaults.
+### Validation Modes
 
-In both cases, you can create an instance of this class and use it to emit metrics.
+Control how validation errors are handled:
 
-#### Naming Metrics
+```ruby
+# Strict mode: Raises exceptions on validation failures
+emitter = Datadog::Statsd::Emitter.new(schema: schema, validation_mode: :strict)
 
-Please remember that naming *IS* important. Good naming is self-documenting, easy to slice the data by, and easy to understand and analyze. Keep the number of unique metric names down, number of tags down, and the number of possible tag values should always be finite. If in doubt, set a tag, instead of creating a new metric.
+# Warn mode: Logs warnings but continues execution
+emitter = Datadog::Statsd::Emitter.new(schema: schema, validation_mode: :warn)
 
-#### Example — Tracking email delivery 
+# Disabled: No validation (production default)
+emitter = Datadog::Statsd::Emitter.new(schema: schema, validation_mode: :disabled)
+```
 
-Imagine that we want to track email delivery. But we have many types of emails that we send. Instead of creating new metric for each new email type, use the tag "email_type" to specify what type of email it is.
+### Global Configuration
 
-Keep metric name list short, eg: "emails.queued", "emails.sent", "emails.delivered" are good metrics as they define a distinctly unique events. However, should you want to differentiate between different types of emails, you could theoretically do the following: (BAD EXAMPLE, DO NOT FOLLOW) — "emails.sent.welcome", "emails.sent.payment". But this example conflates two distinct events into a single metric. Instead, we should use tags to set event properties, such as what type of email that is.
+Set up global defaults for your application:
 
 ```ruby
+Datadog::Statsd::Schema.configure do |config|
+  config.statsd = Datadog::Statsd.new(
+    ENV['DATADOG_AGENT_HOST'] || 'localhost',
+    ENV['DATADOG_AGENT_PORT'] || 8125
+  )
+  config.schema = schema
+  config.tags = {
+    environment: ENV['RAILS_ENV'],
+    service: 'my-application',
+    version: ENV['APP_VERSION']
+  }
+end
+
+# These global tags are automatically added to all metrics
+emitter = Datadog::Statsd::Emitter.new
+emitter.increment('user.signup')  # Automatically includes global tags
+```
 
-    emails_emitter = Datadog.emitter(
-      self,
-      metric: 'emails'
-    )
+## Cost Control and Best Practices
 
-    emails_emitter.increment('queued.total')
-    emails_emitter.increment('delivered.total', by: count)
-    emails_emitter.gauge('queue.size', EmailQueue.size)
-```
+### Understanding Metric Expansion
 
-#### What's the Emitter Constructor Arguments?
+Different metric types create different numbers of time series:
 
-The first argument to the `Emitter.new()` or `Datadog.emitter()` (those are equivalent) is an object or a string or a class that's converted to a tag called `emitter`. This is the source class or object that sent the metric. The same mwtric may come from various places in your code, and `emitter` tag allows you to differentiate between them.
+- **Counter/Set**: 1 time series per unique tag combination
+- **Gauge**: 5 time series (count, min, max, sum, avg)
+- **Distribution/Histogram**: 10 time series (count, min, max, sum, avg, p50, p75, p90, p95, p99)
 
-Subsequent arguments are hash arguments. 
+### Tag Value Limits
 
- * `metric` — The (optional) name of the metric to track. If set to, eg. `emails`, then any subsequent method sending metric will prepend `emails.` to it, for example:
+Be mindful of tag cardinality:
 
 ```ruby
-emitter.increment('sent.total', by: 3)
+# High cardinality - avoid
+tag :user_id, type: :string  # Could be millions of values
+
+# Better approach - use bucketing
+tag :user_tier, values: %w[free premium enterprise]
+tag :user_cohort, values: %w[new_user returning_user power_user]
 ```
 
-Will actually increment the metric `emails.sent.total`.
+### Schema Validation
 
-#### Other Examples
+Always validate your schema before deployment:
 
 ```ruby
+# Check for common issues
+errors = schema.validate
+if errors.any?
+  puts "Schema validation errors:"
+  errors.each { |error| puts "  - #{error}" }
+end
+```
 
-  Datadog.emitter(self)
-    .increment('emails.sent', by: 2)
+## Integration Examples
 
-  Datadog.emitter(ab_test: { 'login_test_2025' => 'control' })
-    .increment('users.logged_in')
-  # => tags: { ab_test_name: 'login_test_2025', 
-  #            ab_test_group: 'control' } 
+### Rails Integration
 
-  Datadog.emitter(SessionsController, metric: 'users')
-     .gauge('logged_in', 100)
+```ruby
+# config/initializers/datadog_statsd.rb
+schema = Datadog::Statsd::Schema.load_file(Rails.root.join('config/metrics_schema.rb'))
+
+Datadog::Statsd::Schema.configure do |config|
+  config.statsd = Datadog::Statsd.new
+  config.schema = schema
+  config.tags = {
+    environment: Rails.env,
+    service: 'my-rails-app'
+  }
+end
+
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  before_action :setup_metrics
+
+  private
+
+  def setup_metrics
+    @metrics = Datadog::Statsd::Emitter.new(
+      validation_mode: Rails.env.production? ? :disabled : :warn
+    )
+  end
+end
+```
 
-  sessions = Datadog.emitter(SessionsController, metric: 'users')
-  # => tags: { emitter: "sessions_controller" }
-  sessions.gauge('active', 100)
-  sessions.distribution('active.total', 114)
+### Background Job Monitoring
+
+```ruby
+class OrderProcessingJob
+  def perform(order_id)
+    metrics = Datadog::Statsd::Emitter.new
+    
+    start_time = Time.current
+    
+    begin
+      process_order(order_id)
+      metrics.increment('jobs.order_processing.success', tags: { queue: 'orders' })
+    rescue => error
+      metrics.increment('jobs.order_processing.failure', 
+                       tags: { queue: 'orders', error_type: error.class.name })
+      raise
+    ensure
+      duration = Time.current - start_time
+      metrics.distribution('jobs.order_processing.duration', duration * 1000,
+                          tags: { queue: 'orders' })
+    end
+  end
+end
 ```
 
-## Installation
+## Development
 
+After checking out the repo, run:
 
 ```bash
-bundle add datadog-statsd-schema
+bin/setup     # Install dependencies
+bundle exec rake spec  # Run tests
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+To install this gem onto your local machine:
 
 ```bash
-gem install datadog-statsd-schema
+bundle exec rake install
 ```
 
-## Usage
-
-1. Define your metrics and tagging schema
-2. Create as many "emitters" as necessary and start sending!
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at [https://github.com/kigster/datadog-statsd-schema](https://github.com/kigster/datadog-statsd-schema)
+Bug reports and pull requests are welcome on GitHub at https://github.com/kigster/datadog-statsd-schema.
 
 ## License