observable 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9b28e1e941ebdedee663e71a947dd92ec6e07e849092e7789cac95aa523bd80
-  data.tar.gz: 658d6e07ac41ce13f30c14f61e69d2c9d59f79cc1008fac8d2471e040e7f028e
+  metadata.gz: '08d7169aa0bffabba61651eb5fd9d5b798f0d17a3adbcc0406471d1138ca84c5'
+  data.tar.gz: e0ab04bad74667894f89368ca2f3bfedb3040a51010d6b62ee91beb63fcb84b4
 SHA512:
-  metadata.gz: 971679e05648c3d2edf158604d1bfdff48afc68f814753b4bd452d38ed2b7fc6f623903c85dda63e65e592498fa4e541449b018b56ae7e42321329f62bd4ecb9
-  data.tar.gz: cd8e357e76207915a044cbb38d541413d06da9548bc8f40ab0d39636f6ee49317f344f2aa95d2f0cfdcd0d37e54b2319e478b671b15767c5296e347a73119499
+  metadata.gz: 244a0c1bf4902d735d38a51c236f0bbde64d63d27b630eb13d8ffe07436b56f4dff651707cd7bd5850bcabc851b024082f6077ee801b714f03a12eea762669bd
+  data.tar.gz: ac2f872738807294c54aa5e36c7c91760939dcf749066406e13bafd5053cf2b8acb74dc5535976556de513da7b2ecfadf9866a56c5bd267d9dfd80ce3a53d157

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,5 @@
 # For available configuration options, see:
 #   https://github.com/testdouble/standard
-ruby_version: 2.6
+ruby_version: 3.4
+fix: true
+parallel: true

data/CLAUDE.md

@@ -0,0 +1,113 @@
+# 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
+```
+
+### Release Process
+```bash
+# Update version in lib/observable/version.rb
+bundle exec rake release
+```
+
+## 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,122 @@
+PATH
+  remote: .
+  specs:
+    observable (0.1.1)
+      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)
+    bigdecimal (3.2.3)
+    concurrent-ruby (1.3.5)
+    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)
+    ice_nine (0.11.2)
+    json (2.13.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (5.25.5)
+    opentelemetry-api (1.6.0)
+    opentelemetry-common (0.22.0)
+      opentelemetry-api (~> 1.0)
+    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)
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.4.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    regexp_parser (2.11.2)
+    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)
+    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
+  minitest (~> 5.14)
+  observable!
+  rake (~> 13.0)
+  simplecov (~> 0.22)
+  standard (~> 1.40)
+
+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/instrumenter.rb

@@ -0,0 +1,388 @@
+require "opentelemetry/sdk"
+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
+  end
+
+  class Instrumenter
+    attr_reader :last_captured_method_name, :last_captured_namespace, :config
+
+    def initialize(tracer: nil, config: nil)
+      @config = config || Configuration.config
+      @tracer = tracer || OpenTelemetry.tracer_provider.tracer(@config.tracer_name)
+    end
+
+    def instrument(caller_binding = nil, &block)
+      @caller_binding = caller_binding
+      caller_info = extract_caller_information
+      create_instrumented_span(caller_info, &block)
+    end
+
+    private
+
+    # Extracts all information about the calling method in one place
+    def extract_caller_information
+      caller_location = find_caller_location
+      namespace = extract_actual_class_name
+      is_class_method = determine_if_class_method
+
+      CallerInformation.new(
+        method_name: caller_location.label,
+        namespace: namespace,
+        filepath: caller_location.path,
+        line_number: caller_location.lineno,
+        arguments: extract_arguments_from_caller(caller_location),
+        is_class_method: is_class_method
+      )
+    end
+
+    def find_caller_location
+      locations = caller_locations(1, 10)
+      raise InstrumentationError, "Unable to determine caller location" if locations.nil? || locations.empty?
+
+      instrumenter_file = __FILE__
+      caller_location = locations.find { |loc| loc.path != instrumenter_file }
+
+      caller_location || locations.first
+    rescue => e
+      raise InstrumentationError, "Error finding caller location: #{e.message}"
+    end
+
+    def extract_namespace_from_path(file_path)
+      return "UnknownClass" if file_path.nil? || file_path.empty?
+
+      file_name = File.basename(file_path, ".*")
+      return "UnknownClass" if file_name.empty?
+
+      file_name.split("_").map(&:capitalize).join
+    rescue
+      "UnknownClass"
+    end
+
+    def extract_actual_class_name
+      if @caller_binding
+        begin
+          caller_self = @caller_binding.eval("self")
+          if caller_self.is_a?(Class)
+            caller_self.name
+          else
+            caller_self.class.name
+          end
+        rescue
+          extract_namespace_from_path(@caller_binding.eval("__FILE__"))
+        end
+      else
+        caller_location = find_caller_location
+        extract_namespace_from_path(caller_location.path)
+      end
+    rescue
+      "UnknownClass"
+    end
+
+    def determine_if_class_method
+      return false unless @caller_binding
+
+      begin
+        caller_self = @caller_binding.eval("self")
+        caller_self.is_a?(Class)
+      rescue
+        false
+      end
+    end
+
+    def create_instrumented_span(caller_info, &block)
+      separator = caller_info.is_class_method ? "." : "#"
+
+      if caller_info.method_name.include?("#") || caller_info.method_name.include?(".")
+        span_name = caller_info.method_name
+        method_name_only = caller_info.method_name.split(/[#.]/).last
+      else
+        span_name = "#{caller_info.namespace}#{separator}#{caller_info.method_name}"
+        method_name_only = caller_info.method_name
+      end
+
+      @last_captured_method_name = method_name_only
+      @last_captured_namespace = caller_info.namespace
+      @tracer.in_span(span_name) do |span|
+        set_span_attributes(span, caller_info)
+
+        begin
+          result = block.call
+          span.set_attribute("error", false)
+          serialize_return_value(span, result)
+          result
+        rescue => e
+          span.set_attribute("error", true)
+          span.set_attribute("error.type", e.class.name)
+          span.set_attribute("error.message", e.message)
+          span.status = OpenTelemetry::Trace::Status.error(e.message)
+          raise
+        end
+      end
+    end
+
+    def set_span_attributes(span, caller_info)
+      span.set_attribute("code.function", caller_info.method_name)
+      span.set_attribute("code.namespace", caller_info.namespace)
+      span.set_attribute("code.filepath", caller_info.filepath)
+      span.set_attribute("code.lineno", caller_info.line_number)
+
+      if @config.app_namespace
+        span.set_attribute("app.namespace", @config.app_namespace)
+      end
+
+      caller_info.arguments.each do |param_index, param_data|
+        if param_data.is_a?(Hash) && param_data.key?(:value) && param_data.key?(:param_name)
+          serialize_argument(span, "code.arguments.#{param_index}", param_data[:value], param_data[:param_name])
+        else
+          serialize_argument(span, "code.arguments.#{param_index}", param_data, param_index)
+        end
+      end
+    end
+
+    def serialize_argument(span, attribute_prefix, value, param_name = nil, depth = 0)
+      if param_name && should_filter_pii?(param_name)
+        span.set_attribute(attribute_prefix, "[FILTERED]")
+        return
+      end
+
+      case value
+      when String, Numeric, TrueClass, FalseClass, NilClass
+        span.set_attribute(attribute_prefix, value)
+      when Hash
+        serialize_hash(span, attribute_prefix, value, depth)
+      when Array
+        serialize_array(span, attribute_prefix, value, depth)
+      else
+        serialize_object(span, attribute_prefix, value, depth)
+      end
+    end
+
+    def serialize_argument_with_custom_depth(span, attribute_prefix, value, custom_max_depth, param_name = nil, depth = 0)
+      if param_name && should_filter_pii?(param_name)
+        span.set_attribute(attribute_prefix, "[FILTERED]")
+        return
+      end
+
+      case value
+      when String, Numeric, TrueClass, FalseClass, NilClass
+        span.set_attribute(attribute_prefix, value)
+      when Hash
+        serialize_hash_with_custom_depth(span, attribute_prefix, value, custom_max_depth, depth)
+      when Array
+        serialize_array_with_custom_depth(span, attribute_prefix, value, custom_max_depth, depth)
+      else
+        serialize_object_with_custom_depth(span, attribute_prefix, value, custom_max_depth, depth)
+      end
+    end
+
+    def serialize_return_value(span, value)
+      return unless @config.track_return_values
+
+      case value
+      when NilClass
+        span.set_attribute("code.return", "nil")
+      when String, Numeric, TrueClass, FalseClass
+        span.set_attribute("code.return", value)
+      when Hash
+        serialize_hash(span, "code.return", value, 2)
+      when Array
+        serialize_array(span, "code.return", value, 2)
+      else
+        serialize_object(span, "code.return", value, 2)
+      end
+    end
+
+    def serialize_hash(span, prefix, hash, depth = 0)
+      max_depth = get_serialization_depth_for_class("Hash")
+      return if depth > max_depth
+
+      hash.each do |key, value|
+        key_str = key.to_s
+        next if should_filter_pii?(key_str)
+        serialize_argument(span, "#{prefix}.#{key_str}", value, nil, depth + 1)
+      end
+    end
+
+    def serialize_hash_with_custom_depth(span, prefix, hash, custom_max_depth, depth = 0)
+      return if depth > custom_max_depth
+
+      hash.each do |key, value|
+        key_str = key.to_s
+        next if should_filter_pii?(key_str)
+        serialize_argument_with_custom_depth(span, "#{prefix}.#{key_str}", value, custom_max_depth, nil, depth + 1)
+      end
+    end
+
+    def serialize_array_with_custom_depth(span, prefix, array, custom_max_depth, depth = 0)
+      return if depth > custom_max_depth
+
+      items_to_process = [array.length, 10].min
+      array.first(items_to_process).each_with_index do |item, index|
+        serialize_argument_with_custom_depth(span, "#{prefix}.#{index}", item, custom_max_depth, nil, depth + 1)
+      end
+    end
+
+    def serialize_object_with_custom_depth(span, prefix, obj, custom_max_depth, depth = 0)
+      if depth >= custom_max_depth
+        span.set_attribute("#{prefix}.class", obj.class.name)
+        span.set_attribute(prefix, obj.to_s)
+        return
+      end
+
+      span.set_attribute("#{prefix}.class", obj.class.name)
+
+      formatter = find_formatter_for_class(obj.class.name)
+
+      if formatter && obj.respond_to?(formatter)
+        result = obj.send(formatter)
+        if result.is_a?(Hash)
+          serialize_hash_with_custom_depth(span, prefix, result, custom_max_depth, depth)
+          return
+        end
+      end
+
+      default_formatter = @config.formatters[:default]
+      if default_formatter && obj.respond_to?(default_formatter)
+        result = obj.send(default_formatter)
+        if result.is_a?(Hash)
+          serialize_hash_with_custom_depth(span, prefix, result, custom_max_depth, depth)
+          return
+        end
+      end
+
+      span.set_attribute(prefix, obj.to_s)
+    end
+
+    def serialize_array(span, prefix, array, depth = 0)
+      max_depth = get_serialization_depth_for_class("Array")
+      return if depth > max_depth
+
+      items_to_process = [array.length, 10].min
+      array.first(items_to_process).each_with_index do |item, index|
+        serialize_argument(span, "#{prefix}.#{index}", item, nil, depth + 1)
+      end
+    end
+
+    def serialize_object(span, prefix, obj, depth = 0)
+      max_depth = get_serialization_depth_for_class(obj.class.name)
+
+      # If we've reached the depth limit for this class, just set the class name
+      if depth >= max_depth
+        span.set_attribute("#{prefix}.class", obj.class.name)
+        span.set_attribute(prefix, obj.to_s)
+        return
+      end
+
+      span.set_attribute("#{prefix}.class", obj.class.name)
+
+      formatter = find_formatter_for_class(obj.class.name)
+
+      if formatter && obj.respond_to?(formatter)
+        result = obj.send(formatter)
+        if result.is_a?(Hash)
+          # When object converts to hash, the hash starts fresh at depth 0
+          # but we need to enforce the object's depth limit
+          serialize_hash_with_custom_depth(span, prefix, result, max_depth, 0)
+          return
+        end
+      end
+
+      default_formatter = @config.formatters[:default]
+      if default_formatter && obj.respond_to?(default_formatter)
+        result = obj.send(default_formatter)
+        if result.is_a?(Hash)
+          # When object converts to hash, the hash starts fresh at depth 0
+          # but we need to enforce the object's depth limit
+          serialize_hash_with_custom_depth(span, prefix, result, max_depth, 0)
+          return
+        end
+      end
+
+      span.set_attribute(prefix, obj.to_s)
+    end
+
+    def find_formatter_for_class(class_name)
+      @config.formatters[class_name]
+    end
+
+    def get_serialization_depth_for_class(class_name)
+      if @config.serialization_depth.is_a?(Integer)
+        return @config.serialization_depth
+      end
+
+      @config.serialization_depth[class_name] || @config.serialization_depth[:default] || @config.serialization_depth["default"] || 2
+    end
+
+    def should_filter_pii?(param_name)
+      return false if @config.pii_filters.empty?
+
+      param_name_str = param_name.to_s.downcase
+      @config.pii_filters.any? { |pattern| pattern.match?(param_name_str) }
+    end
+
+    def extract_arguments_from_caller(caller_location)
+      ArgumentExtractor.new(caller_location, @caller_binding).extract
+    end
+
+    CallerInformation = Struct.new(:method_name, :namespace, :filepath, :line_number, :arguments, :is_class_method, keyword_init: true)
+
+    class ArgumentExtractor
+      def initialize(caller_location, caller_binding = nil)
+        @caller_location = caller_location
+        @caller_binding = caller_binding
+        @method_name = caller_location.label
+      end
+
+      def extract
+        return {} unless @caller_binding
+        extract_from_binding
+      end
+
+      private
+
+      def extract_from_binding
+        @caller_binding.local_variables
+        args = {}
+
+        extract_local_variables_with_numeric_indexing(args)
+
+        args
+      rescue
+        {}
+      end
+
+      def extract_local_variables_with_numeric_indexing(args)
+        local_vars = @caller_binding.local_variables
+        positional_index = 0
+
+        local_vars.each do |var_name|
+          var_name_str = var_name.to_s
+
+          next if var_name_str.start_with?("_") || var_name == :instrumenter
+
+          value = @caller_binding.local_variable_get(var_name)
+
+          args[positional_index.to_s] = {
+            value: value,
+            param_name: var_name_str
+          }
+          positional_index += 1
+        end
+      end
+    end
+
+    class InstrumentationError < StandardError; end
+  end
+end

data/lib/observable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Observable
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/observable.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
 require_relative "observable/version"
+require_relative "observable/instrumenter"
 
 module Observable
   class Error < StandardError; end
-  # Your code goes here...
+
+  # Convenience method to create a new instrumenter instance
+  def self.instrumenter(config: nil)
+    Instrumenter.new(config: config)
+  end
 end

data/observable.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "lib/observable/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "observable"
+  spec.version = Observable::VERSION
+  spec.authors = ["John Gallagher"]
+  spec.email = ["john@synapticmishap.co.uk"]
+
+  spec.summary = "OpenTelemetry instrumentation library for Ruby methods"
+  spec.description = "A Ruby gem that provides automated OpenTelemetry instrumentation for method calls with configurable serialization, PII filtering, and argument tracking"
+  spec.homepage = "https://github.com/JoyfulProgramming/observable"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/JoyfulProgramming/observable"
+  spec.metadata["changelog_uri"] = "https://github.com/JoyfulProgramming/observable/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "opentelemetry-sdk", "~> 1.5"
+  spec.add_dependency "dry-configurable", ">= 0.13.0", "< 2.0"
+  spec.add_dependency "dry-struct", "~> 1.4"
+
+  # Development dependencies
+  spec.add_development_dependency "minitest", "~> 5.14"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "standard", "~> 1.40"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -1,31 +1,142 @@
 --- !ruby/object:Gem::Specification
 name: observable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - John Gallagher
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-22 00:00:00.000000000 Z
-dependencies: []
-description: Observe your app using Open Telemetry
+date: 2025-09-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.40'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.40'
+description: A Ruby gem that provides automated OpenTelemetry instrumentation for
+  method calls with configurable serialization, PII filtering, and argument tracking
 email:
 - john@synapticmishap.co.uk
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/settings.local.json"
+- ".ruby-version"
 - ".standard.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
+- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
+- example.rb
 - lib/observable.rb
+- lib/observable/instrumenter.rb
 - lib/observable/version.rb
+- observable.gemspec
 - sig/observable.rbs
 homepage: https://github.com/JoyfulProgramming/observable
 licenses:
@@ -35,7 +146,6 @@ metadata:
   homepage_uri: https://github.com/JoyfulProgramming/observable
   source_code_uri: https://github.com/JoyfulProgramming/observable
   changelog_uri: https://github.com/JoyfulProgramming/observable/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -43,15 +153,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
-summary: Observe your app using Open Telemetry
+summary: OpenTelemetry instrumentation library for Ruby methods
 test_files: []