axn 0.1.0.pre.alpha.2.8.1 → 0.1.0.pre.alpha.4

data/docs/advanced/profiling.md

@@ -0,0 +1,351 @@
+# Profiling
+
+Axn supports performance profiling using [Vernier](https://github.com/Shopify/vernier), a Ruby sampling profiler that provides detailed insights into your action's performance characteristics.
+
+## Overview
+
+Profiling helps you identify performance bottlenecks in your actions by capturing detailed execution traces. Vernier is particularly useful for:
+
+- Identifying slow methods and code paths
+- Understanding memory allocation patterns
+- Analyzing call stacks and execution flow
+- Optimizing performance-critical actions
+
+## Setup
+
+### 1. Install Vernier
+
+Add the Vernier gem to your Gemfile:
+
+```ruby
+# Gemfile
+gem 'vernier', '~> 0.1'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+**Note:** Vernier is not included as a dependency of Axn, so you must explicitly add it to your Gemfile if you want to use profiling features.
+
+### 2. Enable Profiling
+
+No global configuration is needed! Simply use the `:vernier` strategy on the actions you want to profile.
+
+## Basic Usage
+
+Profiling is enabled per-action by using the `:vernier` strategy. This follows the same pattern as other Axn strategies like `:transaction` and `:form`.
+
+### Simple Profiling
+
+Enable profiling on any action:
+
+```ruby
+class UserCreation
+  include Axn
+
+  # Always profile this action
+  use :vernier
+
+  expects :user_params
+
+  def call
+    user = User.create!(user_params)
+    send_welcome_email(user)
+  end
+
+  private
+
+  def send_welcome_email(user)
+    UserMailer.welcome(user).deliver_now
+  end
+end
+```
+
+### Conditional Profiling
+
+Profile only under specific conditions:
+
+```ruby
+class DataProcessing
+  include Axn
+
+  # Profile only when processing large datasets
+  use :vernier, if: -> { record_count > 1000 }
+
+  expects :records, :record_count
+
+  def call
+    records.each { |record| process_record(record) }
+  end
+end
+```
+
+**Alternative using a method:**
+
+```ruby
+class DataProcessing
+  include Axn
+
+  # Profile using a method
+  use :vernier, if: :should_profile?
+
+  expects :records, :record_count, :debug_mode, type: :boolean, default: false
+
+  def should_profile?
+    record_count > 1000 || debug_mode
+  end
+
+  def call
+    records.each { |record| process_record(record) }
+  end
+end
+```
+
+
+## Advanced Usage
+
+### Sampling Rate Control
+
+Adjust the sampling rate per action:
+
+```ruby
+class DevelopmentAction
+  include Axn
+
+  # High sampling rate for development (more detailed data)
+  use :vernier, sample_rate: 0.5 if Rails.env.development?
+
+  def call
+    # Action logic
+  end
+end
+
+class ProductionAction
+  include Axn
+
+  # Low sampling rate for production (minimal overhead)
+  use :vernier, sample_rate: 0.01 if Rails.env.production?
+
+  def call
+    # Action logic
+  end
+end
+```
+
+### Custom Output Directory
+
+Organize profiles by environment or feature:
+
+```ruby
+class MyAction
+  include Axn
+
+  # Custom output directory
+  use :vernier, output_dir: Rails.root.join("tmp", "profiles", Rails.env)
+
+  def call
+    # Action logic
+  end
+end
+```
+
+### Multiple Conditions
+
+Combine multiple profiling conditions:
+
+```ruby
+class ComplexAction
+  include Axn
+
+  # Profile when debug mode is enabled OR when processing admin users
+  use :vernier, if: -> { debug_mode || user.admin? }
+
+  expects :user, :debug_mode, type: :boolean, default: false
+
+  def call
+    # Complex logic
+  end
+end
+```
+
+## Viewing and Analyzing Profiles
+
+### 1. Generate Profile Data
+
+Run your action with profiling enabled:
+
+```ruby
+# This will generate a profile file if conditions are met
+result = UserCreation.call(user_params: { name: "John", email: "john@example.com" })
+```
+
+### 2. Locate Profile Files
+
+Profile files are saved as JSON in your configured output directory:
+
+```bash
+# Default location
+ls tmp/profiles/
+
+# Example output
+axn_UserCreation_1703123456.json
+axn_DataProcessing_1703123457.json
+```
+
+### 3. View in Firefox Profiler
+
+1. Open [profiler.firefox.com](https://profiler.firefox.com/)
+2. Click "Load a profile from file"
+3. Select your generated JSON file
+4. Analyze the performance data
+
+### 4. Understanding the Profile
+
+The Firefox Profiler provides several views:
+
+- **Call Tree**: Shows the complete call stack with timing
+- **Flame Graph**: Visual representation of call stacks
+- **Stack Chart**: Timeline view of function calls
+- **Markers**: Custom markers and events
+
+## Best Practices
+
+### 1. Use Conditional Profiling
+
+Avoid profiling all actions in production:
+
+```ruby
+# Good: Conditional profiling
+use :vernier, if: -> { Rails.env.development? || debug_mode }
+
+# Avoid: Always profiling in production
+use :vernier  # This can impact performance
+```
+
+### 2. Appropriate Sampling Rates
+
+Choose sampling rates based on your environment:
+
+```ruby
+class MyAction
+  include Axn
+
+  # High detail for debugging
+  use :vernier, sample_rate: 0.5 if Rails.env.development?
+
+  # Moderate sampling for staging
+  use :vernier, sample_rate: 0.1 if Rails.env.staging?
+
+  # Minimal overhead for production
+  use :vernier, sample_rate: 0.01 if Rails.env.production?
+
+  def call
+    # Action logic
+  end
+end
+```
+
+### 3. Profile Specific Scenarios
+
+Focus on performance-critical paths:
+
+```ruby
+class OrderProcessing
+  include Axn
+
+  # Profile only expensive operations
+  use :vernier, if: -> { order.total > 1000 }
+
+  expects :order
+
+  def call
+    process_payment
+    send_confirmation
+    update_inventory
+  end
+end
+```
+
+### 4. Clean Up Old Profiles
+
+Implement profile cleanup to avoid disk space issues:
+
+```ruby
+# Add to a rake task or cron job
+namespace :profiles do
+  desc "Clean up old profile files"
+  task cleanup: :environment do
+    profile_dir = Rails.root.join("tmp", "profiles")
+    Dir.glob(File.join(profile_dir, "*.json")).each do |file|
+      File.delete(file) if File.mtime(file) < 7.days.ago
+    end
+  end
+end
+```
+
+## Troubleshooting
+
+### Vernier Not Available
+
+If you see this error:
+
+```
+LoadError: Vernier gem is not loaded. Add `gem 'vernier', '~> 0.1'` to your Gemfile to enable profiling.
+```
+
+Make sure to:
+1. Add `vernier` to your Gemfile
+2. Run `bundle install`
+3. Restart your application
+
+### No Profile Files Generated
+
+If profile files aren't being generated:
+
+1. Verify your action has `use :vernier` enabled
+2. Ensure profiling conditions are met
+3. Check the output directory exists and is writable
+
+### Performance Impact
+
+Profiling adds overhead to your application:
+
+- **Sampling overhead**: ~1-5% depending on sample rate
+- **File I/O**: Profile files are written to disk
+- **Memory usage**: Slight increase due to sampling
+
+Use appropriate sampling rates and conditional profiling to minimize impact.
+
+## Integration with Other Tools
+
+### OpenTelemetry and Datadog Integration
+
+Axn automatically creates OpenTelemetry spans for all actions when OpenTelemetry is available. These spans appear as children of your Rails request traces in APM tools.
+
+You can combine profiling with OpenTelemetry tracing:
+
+```ruby
+class MyAction
+  include Axn
+
+  # Profiling with custom options
+  use :vernier, sample_rate: 0.1
+
+  def call
+    # Action logic
+    # OpenTelemetry spans are automatically created
+  end
+end
+```
+
+For detailed setup instructions on sending traces to Datadog (including the required gems and initialization order), see the [OpenTelemetry Tracing section](/reference/configuration#opentelemetry-tracing) in the Configuration reference.
+
+## Resources
+
+- [Vernier GitHub Repository](https://github.com/Shopify/vernier)
+- [Firefox Profiler](https://profiler.firefox.com/)
+- [Ruby Performance Optimization Guide](https://ruby-doc.org/core-3.2.1/doc/performance_rdoc.html)
+- [Axn Configuration Reference](/reference/configuration)

data/docs/advanced/rough.md

@@ -1,14 +1,33 @@
-::: danger ALPHA
-* TODO: convert rough notes into actual documentation
-:::
+# Internal Notes
 
-## Rough Notes
+This page contains internal implementation notes for contributors and advanced users.
 
-* General note: the inbound/outbound contexts are views into an underlying shared object (passed down through organize calls) -- modifications of one will affect the other (e.g. preprocessing inbound args implicitly transforms them on the underlying context, which is echoed if you also expose it on outbound).
+## Context Sharing
 
-* `context_for_logging` (and decent #inspect support)
+The inbound/outbound contexts are views into an underlying shared object. Modifications to one affect the other:
 
-* Configuring logging (will default to Rails.logger if available, else fall back to basic Logger (but can explicitly set via e.g. `Action.config.logger = Logger.new($stdout`))
+- Preprocessing inbound args implicitly transforms them on the underlying context
+- If you also expose a preprocessed field on outbound, it will reflect the transformed value
 
-    * Note `context_for_logging` is available (filtered to accessible attrs, filtering out sensitive values). Automatically passed into `on_exception` hook.
+## Logging and Debugging
 
+For information about logging configuration, see the [Configuration reference](/reference/configuration):
+
+- **Logger configuration**: [logger](/reference/configuration#logger)
+- **Log levels**: [log_level](/reference/configuration#log-level)
+- **Automatic logging**: [Automatic Logging](/reference/configuration#automatic-logging)
+
+### `context_for_logging`
+
+The `context_for_logging` method returns a hash of the action's context, with:
+- Filtering to accessible attributes
+- Sensitive values removed (fields marked with `sensitive: true`)
+
+This is automatically passed to the `on_exception` hook. See [Adding Additional Context to Exception Logging](/reference/configuration#adding-additional-context-to-exception-logging) for customizing the context.
+
+### `#inspect` Support
+
+Action instances provide a readable `#inspect` output that shows:
+- The action class name
+- Field values (with sensitive values filtered)
+- Current execution state

data/docs/index.md

@@ -22,11 +22,13 @@ hero:
 
 features:
   - title: Declarative interface
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+    details: Clear, explicit contracts for inputs and outputs with `expects` and `exposes`
   - title: Exception swallowing
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+    details: Automatic error handling with user-safe error messages and internal logging
+  - title: Advanced Patterns
+    details: Mountable actions, workflow composition, and background processing capabilities
   - title: Default Observability
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+    details: Built-in logging, timing, and error tracking out of the box
 ---
 
 ::: danger ALPHA RELEASE

data/docs/intro/about.md

@@ -17,7 +17,7 @@ A simple, declarative core API. Concise enough to pick up quickly, but sufficien
   - Consistent return interface (including exception swallowing)
     - Clear distinction between user-facing and internal errors
   - Minimal boilerplate
-  - Easy backgrounding (no need for a separate Worker class just to wrap a service call)
+  - Easy async execution (no need for a separate Worker class just to wrap a service call)
 
 **Additional benefits devs get for free:**
 

data/docs/intro/overview.md

@@ -13,11 +13,11 @@ This library provides a set of conventions for writing business logic in Rails (
 
 ### Minimal example
 
-Your logic goes in a <abbr title="Plain Old Ruby Object">PORO</abbr>. The only requirements are to `include Action` and a `call` method, meaning the basic skeleton looks something like this:
+Your logic goes in a <abbr title="Plain Old Ruby Object">PORO</abbr>. The only requirements are to `include Axn` and define a `call` method, meaning the basic skeleton looks something like this:
 
 ```ruby
 class Foo
-  include Action
+  include Axn
 
   def call
     log "Doesn't do much, but this technically works..."
@@ -31,7 +31,7 @@ Most actions require inputs, and many return values to the caller; no need for a
 
   * `expects :foo` to declare inputs the class expects to receive.
 
-    You pass the `expect`ed keyword arguments to `call`, then reference their values as local `attr_reader`s.
+    You pass the `expect`ed keyword arguments to `call`, then reference their values as local `attr_reader`s. Use `optional: true` for fields that may be missing or blank.
 
   * `exposes :bar` to declare any outputs the class will expose.
 
@@ -52,7 +52,7 @@ If any declared expectations or exposures are _not_ met the action will fail, se
 
 ```ruby
 class Actions::Slack::Post
-  include Action
+  include Axn
   VALID_CHANNELS = [ ... ]
 
   expects :channel, default: VALID_CHANNELS.first, inclusion: { in: VALID_CHANNELS } # [!code focus:4]
@@ -76,7 +76,7 @@ end
 ## Return interface {#return-interface}
 
 
-The return value of an Action call is always an `Action::Result`, which provides a consistent interface:
+The return value of an Axn call is always an `Axn::Result`, which provides a consistent interface:
 
 * `ok?` will return a boolean (false if any errors or exceptions occurred, otherwise true)
   * if OK, `success` will return a string that is _safe to show end users_
@@ -140,7 +140,7 @@ When configuring custom error and success messages, remember to define your stat
 
 ```ruby
 class MyAction
-  include Action
+  include Axn
 
   # Static fallback messages first
   success "Default success message"

data/docs/recipes/formatting-context-for-error-tracking.md

@@ -0,0 +1,186 @@
+# Formatting Context for Error Tracking Systems
+
+The `context` hash passed to the global `on_exception` handler may contain complex objects (like ActiveRecord models, `ActionController::Parameters`, or `Axn::FormObject` instances) that aren't easily serialized by error tracking systems. You can format these values to make them more readable.
+
+## Basic Example
+
+```ruby
+Axn.configure do |c|
+  c.on_exception = proc do |e, action:, context:|
+    formatted_context = format_hash_values(context)
+
+    Honeybadger.notify(e, context: { axn_context: formatted_context })
+  end
+end
+
+def format_hash_values(hash)
+  hash.transform_values do |v|
+    if v.respond_to?(:to_global_id)
+      v.to_global_id.to_s
+    elsif v.is_a?(ActionController::Parameters)
+      v.to_unsafe_h
+    elsif v.is_a?(Axn::FormObject)
+      v.to_h
+    else
+      v
+    end
+  end
+end
+```
+
+## What This Converts
+
+- **ActiveRecord objects** → Their global ID string (via `to_global_id`)
+- **`ActionController::Parameters`** → A plain hash
+- **`Axn::FormObject` instances** → Their hash representation
+- **Other values** → Remain unchanged
+
+This ensures that your error tracking system receives serializable, readable context data instead of complex objects that may not serialize properly.
+
+## Recursive Formatting
+
+If your context contains nested hashes with complex objects, you may want to recursively format the entire structure:
+
+```ruby
+def format_hash_values(hash)
+  hash.transform_values do |v|
+    case v
+    when Hash
+      format_hash_values(v)
+    when Array
+      v.map { |item| item.is_a?(Hash) ? format_hash_values(item) : format_value(item) }
+    else
+      format_value(v)
+    end
+  end
+end
+
+def format_value(v)
+  if v.respond_to?(:to_global_id)
+    v.to_global_id.to_s
+  elsif v.is_a?(ActionController::Parameters)
+    v.to_unsafe_h
+  elsif v.is_a?(Axn::FormObject)
+    v.to_h
+  else
+    v
+  end
+end
+```
+
+## Advanced Example: Production Implementation
+
+Here's a comprehensive example that includes additional context, a retry command generator, and proper handling of ActiveRecord models:
+
+```ruby
+Axn.configure do |c|
+  def format_hash_values(hash)
+    hash.transform_values do |v|
+      if v.respond_to?(:to_global_id)
+        v.to_global_id.to_s
+      elsif v.is_a?(ActionController::Parameters)
+        v.to_unsafe_h
+      elsif v.is_a?(Axn::FormObject)
+        v.to_h
+      else
+        v
+      end
+    end
+  end
+
+  # Format values for retry commands - produces copy-pasteable Ruby code
+  def format_value_for_retry_command(value)
+    # Handle ActiveRecord model instances
+    if value.respond_to?(:to_global_id) && value.respond_to?(:id) && !value.is_a?(Class)
+      begin
+        model_class = value.class.name
+        id = value.id
+        return "#{model_class}.find(#{id.inspect})"
+      rescue StandardError
+        # If accessing id fails, fall through to default behavior
+      end
+    end
+
+    # Handle GlobalID strings (useful for serialized values)
+    if value.is_a?(String) && value.start_with?("gid://")
+      begin
+        gid = GlobalID.parse(value)
+        if gid
+          model_class = gid.model_class.name
+          id = gid.model_id
+          return "#{model_class}.find(#{id.inspect})"
+        end
+      rescue StandardError
+        # If parsing fails, fall through to default behavior
+      end
+    end
+
+    # Default: use inspect for other types
+    value.inspect
+  end
+
+  def retry_command(action:, context:)
+    action_name = action.class.name
+    return nil if action_name.nil?
+
+    expected_fields = action.internal_field_configs.map(&:field)
+
+    return "#{action_name}.call()" if expected_fields.empty?
+
+    args = expected_fields.map do |field|
+      value = context[field]
+      "#{field}: #{format_value_for_retry_command(value)}"
+    end.join(", ")
+
+    "#{action_name}.call(#{args})"
+  end
+
+  c.on_exception = proc do |e, action:, context:|
+    axn_name = action.class.name || "AnonymousClass"
+    message = "[#{axn_name}] Raised #{e.class.name}: #{e.message}"
+
+    hb_context = {
+      axn: axn_name,
+      axn_context: format_hash_values(context),
+      current_attributes: format_hash_values(Current.attributes),
+      retry_command: retry_command(action:, context:),
+      exception: e,
+    }
+
+    fingerprint = [axn_name, e.class.name, e.message].join(" - ")
+    Honeybadger.notify(message, context: hb_context, backtrace: e.backtrace, fingerprint:)
+  rescue StandardError => rep
+    Rails.logger.warn "!! Axn failed to report action failure to honeybadger!\nOriginal exception: #{e}\nReporting exception: #{rep}"
+  end
+end
+```
+
+This example includes:
+
+- **Formatted context**: Uses `format_hash_values` to serialize complex objects for readable error tracking
+- **Smart retry commands**: Generates copy-pasteable Ruby code, converting ActiveRecord models to `Model.find(id)` calls instead of raw inspect output
+- **GlobalID support**: Handles both live model instances and serialized GlobalID strings
+- **Additional context**: Includes `Current.attributes` (if using a Current pattern) for request-level context
+- **Error fingerprinting**: Creates a fingerprint from action name, exception class, and message to group similar errors
+- **Error handling**: Wraps the Honeybadger notification in a rescue block to prevent reporting failures from masking the original exception
+
+### Example Output
+
+For an action like:
+
+```ruby
+class UpdateUser
+  include Axn
+  expects :user, model: User
+  expects :name, type: String
+end
+```
+
+The retry command would generate:
+
+```ruby
+UpdateUser.call(user: User.find(123), name: "Alice")
+```
+
+This can be copied directly from your error tracking system and pasted into a Rails console to reproduce the error.
+