observable 0.1.0 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9b28e1e941ebdedee663e71a947dd92ec6e07e849092e7789cac95aa523bd80
-  data.tar.gz: 658d6e07ac41ce13f30c14f61e69d2c9d59f79cc1008fac8d2471e040e7f028e
+  metadata.gz: b257d27b8a651f747109ea43b983befa02c2e10d34d13a49cf025a5f46eb7592
+  data.tar.gz: '068c6c31c24e4473682c9d5072842d995cd43a0fae9dee2ca2749a7313bc69a5'
 SHA512:
-  metadata.gz: 971679e05648c3d2edf158604d1bfdff48afc68f814753b4bd452d38ed2b7fc6f623903c85dda63e65e592498fa4e541449b018b56ae7e42321329f62bd4ecb9
-  data.tar.gz: cd8e357e76207915a044cbb38d541413d06da9548bc8f40ab0d39636f6ee49317f344f2aa95d2f0cfdcd0d37e54b2319e478b671b15767c5296e347a73119499
+  metadata.gz: 3d52b07648bd401f2494aa735e988a067c01bca1a443c1ee4ec609cebf582fc3eb3c59939c0b85a9880f0ad53a72b29495a249cea6bf92ee3dc8a114c674e340
+  data.tar.gz: eeb0349b60211293afe11f445789a3598e8ad2af6d577e53cf08958ec7237aa6c36799e047df11c0cb931ec6a960a085e14c2c96f79c5f504b6e0cf824ae03e2

data/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ruby:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

data/.ruby-version

@@ -0,0 +1 @@
+3.4.1

data/.standard.yml

@@ -1,3 +1,7 @@
 # For available configuration options, see:
 #   https://github.com/testdouble/standard
-ruby_version: 2.6
+ruby_version: 3.4
+fix: true
+parallel: true
+ignore:
+  - Gemfile.lock

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 ## [Unreleased]
 
+
+
+
+
+## [0.1.4] - 2025-09-08
+
+### Changed
+- Update version bumping logic in bump script
+- v0.1.3-beta
+- Update gem build process and release script
+- v0.1.2-beta
+
+
+## [0.1.2-beta] - 2025-09-08
+
+### Changed
+- v0.1.2-beta
+
+
+## [0.1.2-alpha] - 2025-09-08
+
+### Added
+- Add support for bumping alpha and beta pre-releases
+
+### Changed
+- Update version bumping logic for bump gem
+- Delegate all version bumping to bump gem
+- Extract configuration into class
+- Update gemspec and test setup for OTLP exporter
+
+
+## [0.1.2-alpha] - 2025-09-08
+
+### Added
+- Add support for bumping alpha and beta pre-releases
+
+### Fixed
+- Update version to 0.1.2
+
+### Changed
+- Delegate all version bumping to bump gem
+- v0.1.2-alpha
+- Extract configuration into class
+- Update gemspec and test setup for OTLP exporter
+- Add 'ignore' section to configuration file
+
+
+## [0.1.2] - 2025-09-07
+
+### Changed
+- Add Ruby 3.2.x versions to GitHub Actions matrix for better CI coverage
+
 ## [0.1.0] - 2024-04-22
 
 - Initial release

data/CLAUDE.md

@@ -0,0 +1,135 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the Observable gem - a Ruby library that provides OpenTelemetry instrumentation for method calls with configurable serialization, PII filtering, and argument tracking. It automatically captures method invocation details, arguments, return values, and exceptions as OpenTelemetry spans.
+
+## Core Architecture
+
+### Main Components
+
+- **Observable::Instrumenter** (`lib/observable/instrumenter.rb`) - The core instrumentation engine that wraps method calls with OpenTelemetry spans
+- **Observable::Configuration** (`lib/observable/instrumenter.rb`) - Uses Dry::Configurable for flexible configuration management
+- **ArgumentExtractor** (`lib/observable/instrumenter.rb`) - Extracts method arguments from Ruby bindings using introspection
+- **CallerInformation** (`lib/observable/instrumenter.rb`) - Value object containing method metadata (name, namespace, filepath, line number, arguments)
+
+### Key Features
+
+- **Automatic method instrumentation** - Wrap any method call with `instrumenter.instrument(binding) { ... }`
+- **Argument tracking** - Captures method parameters with PII filtering capabilities
+- **Return value serialization** - Configurable tracking of method return values
+- **Exception handling** - Automatically captures and records exceptions in spans
+- **Class/instance method detection** - Distinguishes between static (`.`) and instance (`#`) methods
+- **Configurable serialization** - Supports custom formatters and max depth limits
+
+## Development Commands
+
+### Running Tests
+```bash
+bundle exec rake test
+```
+
+### Running Individual Tests
+```bash
+ruby -Itest test/unit/instrumenter_test.rb
+```
+
+### Linting
+```bash
+bundle exec standardrb
+```
+
+### Dependencies
+```bash
+bundle install
+```
+
+### Interactive Console
+```bash
+bin/console
+```
+
+### Build Gem
+```bash
+bundle exec rake build
+```
+
+### Version Management
+```bash
+# Bump patch version (0.1.1 -> 0.1.2)
+bin/bump
+
+# Bump minor version (0.1.1 -> 0.2.0)
+bin/bump --minor
+
+# Bump major version (0.1.1 -> 1.0.0)
+bin/bump --major
+```
+
+### Release Process
+
+The project uses automated releases via GitHub Actions:
+
+1. **Manual Release**: Use `bin/bump` to increment version, update CHANGELOG.md, then commit and push to `main`
+2. **Automated Release**: When a version change is detected in a push to `main`, GitHub Actions will:
+   - Run tests across multiple Ruby versions
+   - Run linting checks
+   - Build the gem
+   - Create a GitHub release with changelog
+   - Publish to RubyGems (requires `RUBYGEMS_API_KEY` secret)
+
+**Prerequisites for automated release:**
+- Set `RUBYGEMS_API_KEY` secret in GitHub repository settings
+- Ensure CHANGELOG.md is updated with meaningful changes
+
+## Configuration System
+
+The gem uses Dry::Configurable with these key settings:
+
+- `transport` - Transport mechanism (default: `:otel`)
+- `app_namespace` - Application namespace for spans
+- `attribute_namespace` - Attribute namespace prefix
+- `tracer_names` - OpenTelemetry tracer configuration
+- `formatters` - Object serialization methods (default: `:to_h`)
+- `pii_filters` - Regex patterns to filter sensitive data
+- `track_return_values` - Enable/disable return value capture (default: true)
+
+## Usage Pattern
+
+The primary usage pattern involves:
+
+1. Create an instrumenter instance: `Observable::Instrumenter.new`
+2. Wrap method calls: `instrumenter.instrument(binding) { method_logic }`
+3. The instrumenter automatically:
+   - Extracts method name, class, and arguments from `binding`
+   - Creates OpenTelemetry spans with standardized naming (`Class#method` or `Class.method`)
+   - Serializes arguments and return values with PII filtering
+   - Handles exceptions and sets appropriate span status
+
+## Testing Structure
+
+- **Unit tests** in `test/unit/` - Test individual components
+- **Support helpers** in `test/support/` - Test utilities and mocks
+- Uses Minitest framework
+- Custom tracing test helpers for OpenTelemetry span verification
+
+## Dependencies
+
+**Runtime:**
+- `opentelemetry-sdk` ~> 1.5 - OpenTelemetry instrumentation
+- `dry-configurable` >= 0.13.0, < 2.0 - Configuration management
+- `dry-struct` ~> 1.4 - Value objects
+
+**Development:**
+- `minitest` ~> 5.14 - Testing framework
+- `standard` ~> 1.40 - Ruby linting and formatting
+- `rake` ~> 13.0 - Build automation
+
+## Code Style
+
+- Uses Standard Ruby for linting and formatting
+- Ruby version: 3.4+ (configured in `.ruby-version` and `.standard.yml`)
+- Frozen string literals enforced
+- Follows Ruby community conventions for method naming and structure

data/Gemfile

@@ -4,9 +4,3 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in observable.gemspec
 gemspec
-
-gem "rake", "~> 13.0"
-
-gem "minitest", "~> 5.0"
-
-gem "standard", "~> 1.3"

data/Gemfile.lock

@@ -0,0 +1,178 @@
+PATH
+  remote: .
+  specs:
+    observable (0.1.4)
+      dry-configurable (>= 0.13.0, < 2.0)
+      dry-struct (~> 1.4)
+      opentelemetry-sdk (~> 1.5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    attr_extras (7.1.0)
+    bigdecimal (3.2.3)
+    bump (0.10.0)
+    concurrent-ruby (1.3.5)
+    date (3.4.1)
+    debug (1.11.0)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-core (1.1.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-inflector (1.2.0)
+    dry-logic (1.6.0)
+      bigdecimal
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-struct (1.8.0)
+      dry-core (~> 1.1)
+      dry-types (~> 1.8, >= 1.8.2)
+      ice_nine (~> 0.11)
+      zeitwerk (~> 2.6)
+    dry-types (1.8.3)
+      bigdecimal (~> 3.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.0)
+      dry-inflector (~> 1.0)
+      dry-logic (~> 1.4)
+      zeitwerk (~> 2.6)
+    erb (5.0.2)
+    google-protobuf (4.32.0)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.32.0-arm64-darwin)
+      bigdecimal
+      rake (>= 13)
+    googleapis-common-protos-types (1.21.0)
+      google-protobuf (~> 4.26)
+    ice_nine (0.11.2)
+    io-console (0.8.1)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.13.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    m (1.6.2)
+      method_source (>= 0.6.7)
+      rake (>= 0.9.2.2)
+    method_source (1.1.0)
+    minitest (5.25.5)
+    opentelemetry-api (1.6.0)
+    opentelemetry-common (0.22.0)
+      opentelemetry-api (~> 1.0)
+    opentelemetry-exporter-otlp (0.30.0)
+      google-protobuf (>= 3.18)
+      googleapis-common-protos-types (~> 1.3)
+      opentelemetry-api (~> 1.1)
+      opentelemetry-common (~> 0.20)
+      opentelemetry-sdk (~> 1.2)
+      opentelemetry-semantic_conventions
+    opentelemetry-registry (0.4.0)
+      opentelemetry-api (~> 1.1)
+    opentelemetry-sdk (1.8.1)
+      opentelemetry-api (~> 1.1)
+      opentelemetry-common (~> 0.20)
+      opentelemetry-registry (~> 0.2)
+      opentelemetry-semantic_conventions
+    opentelemetry-semantic_conventions (1.11.0)
+      opentelemetry-api (~> 1.0)
+    optimist (3.2.1)
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    patience_diff (1.2.0)
+      optimist (~> 3.0)
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.4.0)
+    psych (5.2.6)
+      date
+      stringio
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    rdoc (6.14.2)
+      erb
+      psych (>= 4.0.0)
+    regexp_parser (2.11.2)
+    reline (0.6.2)
+      io-console (~> 0.5)
+    rubocop (1.75.8)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.46.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.25.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    standard (1.50.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.75.5)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.8.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.25.0)
+    stringio (3.1.7)
+    super_diff (0.16.0)
+      attr_extras (>= 6.2.4)
+      diff-lcs
+      patience_diff
+    unicode-display_width (3.1.5)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    zeitwerk (2.7.3)
+
+PLATFORMS
+  arm64-darwin-23
+  ruby
+
+DEPENDENCIES
+  bump (~> 0.10)
+  debug (~> 1.8)
+  m (~> 1.6)
+  minitest (~> 5.14)
+  observable!
+  opentelemetry-exporter-otlp (~> 0.30)
+  rake (~> 13.0)
+  simplecov (~> 0.22)
+  standard (~> 1.40)
+  super_diff (~> 0.9)
+
+BUNDLED WITH
+   2.6.3

data/README.md

@@ -1,37 +1,168 @@
 # Observable
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/observable`. To experiment with that code, run `bin/console` for an interactive prompt.
+Automatic OpenTelemetry instrumentation for Ruby methods with configurable serialization, PII filtering, and argument tracking.
 
-TODO: Delete this and the text above, and describe your gem
+## Getting Started
 
-## Installation
+```bash
+bundle add observable
+```
 
-Install the gem and add to the application's Gemfile by executing:
+Or
 
-    $ bundle add observable
+```ruby
+# Gemfile
+gem 'observable'
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Basic usage:
 
-    $ gem install observable
+```ruby
+require 'observable'
 
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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/johngallagher/observable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/johngallagher/observable/blob/main/CODE_OF_CONDUCT.md).
+class UserService
+  def initialize
+    @instrumenter = Observable::Instrumenter.new
+  end
+
+  def create_user(name, email)
+    @instrumenter.instrument(binding) do
+      User.create(name: name, email: email)
+    end
+  end
+end
+```
+
+OpenTelemetry spans are automatically created with method names, arguments, return values, and exceptions.
+
+## Configuration
+
+Configure globally or per-instrumenter:
+
+```ruby
+# Global configuration
+Observable::Configuration.configure do |config|
+  config.tracer_name = "my_app"
+  config.transport = :otel
+  config.app_namespace = "my_app"
+  config.attribute_namespace = "my_app"
+  config.track_return_values = true
+  config.serialization_depth = {default: 2, "MyClass" => 3}
+  config.formatters = {default: :to_h, "MyClass" => :to_formatted_h}
+  config.pii_filters = [/password/i, /secret/i]
+end
+
+# Per-instrumenter configuration
+config = Observable::Configuration.new
+config.track_return_values = false
+instrumenter = Observable::Instrumenter.new(config: config)
+```
+
+### Configuration Options
+
+- `tracer_name`: `"observable"` - Name for the OpenTelemetry tracer
+- `transport`: `:otel` - Uses OpenTelemetry SDK
+- `app_namespace`: `"app"` - Namespace for application-specific attributes
+- `attribute_namespace`: `"app"` - Namespace for span attributes
+- `track_return_values`: `true` - Captures method return values in spans
+- `serialization_depth`: `{default: 2}` - Per-class serialization depth limits (Hash or Integer for backward compatibility)
+- `formatters`: `{default: :to_h}` - Object serialization methods by class name
+- `pii_filters`: `[]` - Regex patterns to filter sensitive data from spans
+
+## OpenTelemetry Integration
+
+This library seamlessly integrates with OpenTelemetry, the industry-standard observability framework. Spans are automatically created with standardized naming (`Class#method` or `Class.method`) and include rich metadata about method invocations, making your Ruby applications immediately observable without manual instrumentation.
+
+## Custom Formatters
+
+Control how domain objects are serialized in spans by configuring custom formatters.
+
+```ruby
+Observable::Configuration.configure do |config|
+  config.formatters = {
+    default: :to_h,
+    'YourCustomClass' => :to_formatted_h
+  }
+  config.serialization_depth = {
+    default: 2,
+    'YourCustomClass' => 3
+  }
+end
+```
+
+## Example
+
+A domain object `Customer` has an `Invoice`.
+
+### Objective 
+
+Only send the invoice ID to the trace to save data.
+
+### Background
+
+Imagine domain objects are `Dry::Struct` value objects:
+
+```ruby
+class Customer < Dry::Struct
+  attribute :id, Dry.Types::String
+  attribute :name, Dry.Types::String
+  attribute :Invoice, Invoice
+end
+
+class Invoice < Dry::Struct
+  attribute :id, Dry.Types::String
+  attribute :status, Dry.Types::String
+  attribute :line_items, Dry.Types::Array
+end
+```
+
+### Solution
+
+1. Define custom formatting method - `#to_formatted_h`
+  
+```diff
+ class Customer < Dry::Struct
+   attribute :id, Dry.Types::String
+   attribute :name, Dry.Types::String
+   attribute :Invoice, Invoice
+
++  def to_formatted_h
++    {
++      id: id,
++      name: name,
++      invoice: {
++       id: invoice.id
++      }
++    }
++  end
+ end
+```
+
+2. Configure observable:
+
+```ruby
+Observable::Configuration.configure do |config|
+  config.formatters = {
+    default: :to_h,
+    'Customer' => :to_formatted_h
+  }
+  config.serialization_depth = {
+    default: 2,
+    'Customer' => 3
+  }
+end
+```
+
+The instrumenter tries class-specific formatters first, then falls back to the default formatter, then `to_s`.
+
+## Benefits
+
+Why use this library? Why not write Otel attributes manually?
+
+* **Zero-touch instrumentation** - Wrap any method call without modifying existing code or manually creating spans
+* **Production-ready safety** - Built-in PII filtering, serialization depth limits, and exception handling prevent common observability pitfalls
+* **Standardized telemetry** - Consistent span naming, attribute structure, and OpenTelemetry compliance across your entire application
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the Observable project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/johngallagher/observable/blob/main/CODE_OF_CONDUCT.md).
+MIT License. See LICENSE file for details.

data/Rakefile

@@ -6,9 +6,7 @@ require "rake/testtask"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
+  t.test_files = FileList["test/**/*_test.rb"]
 end
 
-require "standard/rake"
-
-task default: %i[test standard]
+task default: %i[test]

data/example.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+require_relative "lib/observable"
+
+# Configure the instrumenter
+Observable::Configuration.configure do |config|
+  config.app_namespace = "example_app"
+  config.track_return_values = true
+  config.pii_filters = [/password/, /token/, /secret/]
+end
+
+class ExampleService
+  def initialize
+    @instrumenter = Observable::Instrumenter.new
+  end
+
+  def process_order(order_id, customer_email, amount)
+    @instrumenter.instrument(binding) do
+      # Simulate some processing
+      puts "Processing order #{order_id} for #{customer_email}, amount: #{amount}"
+
+      # Return a result hash
+      {
+        order_id: order_id,
+        status: "processed",
+        processed_at: Time.now.to_i,
+        amount: amount
+      }
+    end
+  end
+
+  def self.static_method(data)
+    instrumenter = Observable::Instrumenter.new
+    instrumenter.instrument(binding) do
+      puts "Processing data: #{data.inspect}"
+      data.transform_values(&:upcase) if data.is_a?(Hash)
+    end
+  end
+end
+
+# Example usage
+puts "=== Observable Example ==="
+puts
+
+service = ExampleService.new
+result = service.process_order("ORD-123", "customer@example.com", 99.99)
+puts "Result: #{result}"
+
+puts
+
+static_result = ExampleService.static_method({name: "john", city: "nyc"})
+puts "Static result: #{static_result}"
+
+puts "\n=== Check OpenTelemetry spans were created ==="
+# In a real application, these spans would be exported to your observability platform

data/lib/observable/configuration.rb

@@ -0,0 +1,17 @@
+require "dry/configurable"
+
+module Observable
+  class Configuration
+    extend Dry::Configurable
+
+    setting :tracer_name, default: "observable"
+    setting :transport, default: :otel
+    setting :app_namespace, default: "app"
+    setting :attribute_namespace, default: "app"
+    setting :formatters, default: {default: :to_h}
+    setting :pii_filters, default: []
+    setting :serialization_depth, default: {default: 2}
+    setting :track_return_values, default: true
+    setting :custom_error_converters, default: {}
+  end
+end