Observable

Automatic OpenTelemetry instrumentation for Ruby methods with configurable serialization, PII filtering, and argument tracking.

bundle add observable

Or

# Gemfile
gem 'observable'

Basic usage:

require 'observable'

class UserService
  def create_user(name, email)
    Observable.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.

Configure globally or per-instrumenter:

# 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)

• 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

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.

Control how domain objects are serialized in spans by configuring custom formatters.

Observable::Configuration.configure do |config|
  config.formatters = {
    default: :to_h,
    'YourCustomClass' => :to_formatted_h
  }
  config.serialization_depth = {
    default: 2,
    'YourCustomClass' => 3
  }
end

A domain object Customer has an Invoice.

Send data from related domain objects when a method is called.

Imagine domain objects are Dry::Struct value objects:

class Customer < Dry::Struct
  attribute :id, Dry.Types::String
  attribute :name, Dry.Types::String
  attribute :status, Dry.Type::Symbol
  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

1. Define custom formatting method - #to_formatted_h

 class Customer < Dry::Struct
   attribute :id, Dry.Types::String
   attribute :name, Dry.Types::String
   attribute :status, Dry.Type::Symbol
   attribute :Invoice, Invoice

+  def to_formatted_h
+    {
+      id: id,
+      name: name,
+      status: status,
+      invoice: {
+       id: invoice.id
+      }
+    }
+  end
 end

2. Configure

Observable::Configuration.configure do |config|
  config.formatters = {
    default: :to_h,
    'Customer' => :to_formatted_h
  }
end

3. Instrument

Let's say we have a use case object that marks the customer as active: MarkCustomerAsActive#call.

How can we observe the behaviour of this use case?

Instrument it like so:

 class MarkCustomerAsActive
   def call(customer)
+    Observable.instrument(binding) do
       customer.activate!
       # ... more code ...
       customer # return customer object
+    end
   end
 end

4. Use

Deploy. Then behold the beauty of domain object attributes in your logs:

Why use this library? Why not write Otel attributes manually?

• Two line 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
• Domain objects - Support for your own custom domain objects to express business terms in your observability data, bringing you closer to the people who pay your salary.

MIT License. See LICENSE file for details.