axn 0.1.0.pre.alpha.3 → 0.1.0.pre.alpha.4

data/docs/reference/class.md

@@ -149,39 +149,67 @@ def build_error_message(exception:)
 end
 ```
 
-::: warning Message Ordering
-**Important**: Static success/error messages (those without conditions) should be defined **first** in your action class. If you define conditional messages before static ones, the conditional messages will never be reached because the static message will always match first.
+## Message Matching Order {#message-matching-order}
+
+::: danger Important: Understanding Handler Evaluation Order
+Message handlers are stored in **last-defined-first** order and evaluated in that order until a match is found. This has critical implications for how you structure your message declarations.
+:::
+
+### How It Works
+
+1. Handlers are registered in reverse definition order (last defined = first evaluated)
+2. The system evaluates handlers one by one until finding one that matches
+3. Static handlers (no `if:` or `unless:` condition) **always match**
+4. Once a match is found, evaluation stops
+
+### Correct Pattern: Static Fallbacks First
+
+Because static handlers always match, they must be defined **first** (so they're evaluated **last**):
 
-**Correct order:**
 ```ruby
 class MyAction
   include Axn
 
-  # Define static fallback first
-  success "Default success message"
-  error "Default error message"
+  # 1. Define static fallback FIRST (evaluated last, catches anything unmatched)
+  error "Something went wrong"
 
-  # Then define conditional messages
-  success "Special success", if: :special_condition?
-  error "Special error", if: ArgumentError
+  # 2. Define conditional handlers AFTER (evaluated first, catch specific cases)
+  error "Invalid input provided", if: ArgumentError
+  error "Record not found", if: ActiveRecord::RecordNotFound
 end
 ```
 
-**Incorrect order (conditional messages will be shadowed):**
+### Incorrect Pattern: Conditional Messages Shadowed
+
+If you define static handlers last, they match first and conditional handlers are never reached:
+
 ```ruby
 class MyAction
   include Axn
 
-  # These conditional messages will never be reached!
-  success "Special success", if: :special_condition?
-  error "Special error", if: ArgumentError
+  # These will NEVER be reached!
+  error "Invalid input provided", if: ArgumentError
+  error "Record not found", if: ActiveRecord::RecordNotFound
 
-  # Static messages defined last will always match first
-  success "Default success message"
-  error "Default error message"
+  # This static handler is evaluated FIRST and always matches
+  error "Something went wrong"
+end
+```
+
+### With Inheritance
+
+Child class handlers are evaluated before parent class handlers:
+
+```ruby
+class ParentAction
+  include Axn
+  error "Parent error"  # Evaluated last
+end
+
+class ChildAction < ParentAction
+  error "Child error"   # Evaluated first
 end
 ```
-:::
 
 ## Conditional messages
 
@@ -251,6 +279,10 @@ The `from:` parameter allows you to customize error messages when an action call
 
 When using `from:`, the error handler receives the exception from the child action, and you can access the child's error message via `e.message` (which contains the `result.error` from the child action).
 
+### Basic usage
+
+You can use `from:` with a single child action class. The prefix and custom handler are optional:
+
 ```ruby
 class InnerAction
   include Axn
@@ -265,7 +297,10 @@ end
 class OuterAction
   include Axn
 
-  # Customize error messages from InnerAction
+  # Simply inherit child's error message (no prefix or custom handler needed)
+  error from: InnerAction
+
+  # Or customize the message
   error from: InnerAction do |e|
     "Outer action failed: #{e.message}"
   end
@@ -279,7 +314,58 @@ end
 In this example:
 - When `InnerAction` fails, `OuterAction` will catch the exception
 - The `e.message` contains the error message from `InnerAction`'s result
-- The final error message will be "Outer action failed: Something went wrong in the inner action"
+- With no handler: the error message will be "Something went wrong in the inner action" (inherited directly)
+- With custom handler: the error message will be "Outer action failed: Something went wrong in the inner action"
+
+### Matching multiple child actions
+
+You can pass an array of child action classes to match multiple children:
+
+```ruby
+class OuterAction
+  include Axn
+
+  # Match errors from multiple child actions
+  error from: [FirstChildAction, SecondChildAction]
+
+  # Or with custom handler
+  error from: [FirstChildAction, SecondChildAction] do |e|
+    "Parent caught: #{e.message}"
+  end
+
+  def call
+    # Calls one of the child actions
+  end
+end
+```
+
+You can also mix class references and string class names:
+
+```ruby
+error from: [FirstChildAction, "SecondChildAction"]
+```
+
+### Matching any child action
+
+Use `from: true` to match errors from any child action without listing them explicitly:
+
+```ruby
+class OuterAction
+  include Axn
+
+  # Match errors from any child action
+  error from: true
+
+  # Or with custom handler
+  error from: true do |e|
+    "Any child failed: #{e.message}"
+  end
+
+  def call
+    # Can call any child action
+  end
+end
+```
 
 This pattern is especially useful for:
 - Adding context to error messages from sub-actions
@@ -312,46 +398,23 @@ This results in:
 - With custom message: "API Error: Request failed: Something went wrong in the inner action"
 - With prefix only: "API Error: Something went wrong in the inner action"
 
-### Message ordering and inheritance
+### Message ordering with `from:`
 
-Messages are evaluated in **last-defined-first** order, meaning the most recently defined message that matches its conditions will be used. This applies to both success and error messages:
+When using `from:` with inheritance, the same [message matching order](#message-matching-order) applies. Define your `from:` handlers after your static fallback:
 
 ```ruby
-class ParentAction
-  include Axn
-
-  success "Parent success message"
-  error "Parent error message"
-end
-
-class ChildAction < ParentAction
-  success "Child success message"  # This will be used when action succeeds
-  error "Child error message"      # This will be used when action fails
-end
-```
-
-Within a single class, later definitions override earlier ones:
-
-```ruby
-class MyAction
+class OuterAction
   include Axn
 
-  success "First success message"           # Ignored
-  success "Second success message"          # Ignored
-  success "Final success message"           # This will be used
+  # Static fallback first
+  error "Something went wrong"
 
-  error "First error message"               # Ignored
-  error "Second error message"              # Ignored
-  error "Final error message"               # This will be used
+  # Then from: handlers for specific child actions
+  error from: InnerAction, prefix: "Inner failed: "
+  error from: AnotherAction, prefix: "Another failed: "
 end
 ```
 
-::: tip Message Evaluation Order
-The system evaluates handlers in the order they were defined until it finds one that matches and doesn't raise an exception. If a handler raises an exception, it falls back to the next matching handler, then to static messages, and finally to the default message.
-
-**Key point**: Static messages (without conditions) are evaluated **first** in the order they were defined. This means you should define your static fallback messages at the top of your class, before any conditional messages, to ensure proper fallback behavior.
-:::
-
 ## `.async`
 
 Configures the async execution behavior for the action. This determines how the action will be executed when `call_async` is called.

data/docs/reference/configuration.md

@@ -53,38 +53,198 @@ A couple notes:
   * `context` will contain the arguments passed to the `action`, _but_ any marked as sensitive (e.g. `expects :foo, sensitive: true`) will be filtered out in the logs.
   * If your handler raises, the failure will _also_ be swallowed and logged
   * This handler is global across _all_ Axns.  You can also specify per-Action handlers via [the class-level declaration](/reference/class#on-exception).
+  * The `context` hash may contain complex objects (like ActiveRecord models, `ActionController::Parameters`, or `Axn::FormObject` instances) that aren't easily serialized by error tracking systems. See [Formatting Context for Error Tracking Systems](/recipes/formatting-context-for-error-tracking) for a recipe to convert these to readable formats.
 
-## `wrap_with_trace` and `emit_metrics`
+### Adding Additional Context to Exception Logging
 
-If you're using an APM provider, observability can be greatly enhanced by adding automatic _tracing_ of Axn calls and/or emitting count metrics after each call completes.
+When processing records in a loop or performing batch operations, you may want to include additional context (like which record is being processed) in exception logs. You can do this in two ways:
 
-The framework provides two distinct hooks for observability:
+**Option 1: Explicit setter** - Call `set_logging_context` during execution:
 
-- **`wrap_with_trace`**: An around hook that wraps the entire action execution. You MUST call the provided block to execute the action.
-- **`emit_metrics`**: A post-execution hook that receives the action result. Do NOT call any blocks.
+```ruby
+class ProcessPendingRecords
+  include Axn
+
+  def call
+    pending_records.each do |record|
+      set_logging_context(current_record_id: record.id, batch_index: @index)
+      # ... process record ...
+    end
+  end
+end
+```
 
-For example, to wire up Datadog:
+**Option 2: Hook method** - Define a private `additional_logging_context` method that returns a hash:
 
 ```ruby
-  Axn.configure do |c|
-    c.wrap_with_trace = proc do |resource, &action|
-      Datadog::Tracing.trace("Action", resource:) do
-        action.call
-      end
+class ProcessPendingRecords
+  include Axn
+
+  def call
+    pending_records.each do |record|
+      @current_record = record
+      # ... process record ...
     end
+  end
+
+  private
+
+  def additional_logging_context
+    return {} unless @current_record
+
+    {
+      current_record_id: @current_record.id,
+      record_type: @current_record.class.name
+    }
+  end
+end
+```
+
+Both approaches can be used together - they will be merged. The additional context is **only** included in exception logging (not in normal pre/post execution logs), and is evaluated lazily (the hook method is only called when an exception occurs).
+
+Action-specific `on_exception` handlers can also access this context by calling `context_for_logging` directly:
+
+```ruby
+class ProcessPendingRecords
+  include Axn
+
+  on_exception do |exception:|
+    log "Failed with this extra context: #{context_for_logging}"
+    # ... handle exception with context ...
+  end
+end
+```
+
+## `raise_piping_errors_in_dev`
+
+By default, errors that occur in framework code (e.g., in logging hooks, exception handlers, validators, or other user-provided callbacks) are swallowed and logged to prevent them from interfering with the main action execution. In development, you can opt-in to have these errors raised instead of logged:
+
+```ruby
+Axn.configure do |c|
+  c.raise_piping_errors_in_dev = true
+end
+```
+
+**Important notes:**
+- This setting only applies in the development environment—errors are always swallowed in test and production
+- Test and production environments behave identically (errors swallowed), ensuring tests verify actual production behavior
+- When enabled in development, errors in framework code (like logging hooks, exception handlers, validators) will be raised instead of logged, putting issues front and center during manual testing
+
+## OpenTelemetry Tracing
+
+Axn automatically creates OpenTelemetry spans for all action executions when OpenTelemetry is available. The framework creates a span named `"axn.call"` with the following attributes:
+
+- `axn.resource`: The action class name (e.g., `"UserManagement::CreateUser"`)
+- `axn.outcome`: The execution outcome (`"success"`, `"failure"`, or `"exception"`)
+
+When an action fails or raises an exception, the span is marked as an error with the exception details recorded.
+
+### Basic Setup
+
+If you just want OpenTelemetry spans (without sending to an APM provider), install the API gem:
+
+```ruby
+# Gemfile
+gem "opentelemetry-api"
+```
+
+Then configure a tracer provider:
+
+```ruby
+# config/initializers/opentelemetry.rb
+require "opentelemetry-sdk"
+
+OpenTelemetry::SDK.configure do |c|
+  c.service_name = "my-app"
+end
+```
+
+### Datadog Integration
+
+To send OpenTelemetry spans to Datadog APM, you need both the OpenTelemetry SDK and the Datadog bridge. The bridge intercepts `OpenTelemetry::SDK.configure` and routes spans to Datadog's tracer.
+
+**1. Add the required gems:**
+
+```ruby
+# Gemfile
+gem "datadog"           # Datadog APM
+gem "opentelemetry-api" # OpenTelemetry API
+gem "opentelemetry-sdk" # OpenTelemetry SDK (required for Datadog bridge)
+```
+
+**2. Configure Datadog first, then OpenTelemetry:**
+
+The order matters — Datadog must be configured before loading the OpenTelemetry bridge, and `OpenTelemetry::SDK.configure` must be called after the bridge is loaded.
+
+```ruby
+# config/initializers/datadog.rb (use a filename that loads early, e.g., 00_datadog.rb)
+
+# 1. Configure Datadog first
+Datadog.configure do |c|
+  c.env = Rails.env
+  c.service = "my-app"
+  c.tracing.enabled = Rails.env.production? || Rails.env.staging?
+  c.tracing.instrument :rails
+end
+
+# 2. Load the OpenTelemetry SDK and Datadog bridge
+require "opentelemetry-api"
+require "opentelemetry-sdk"
+require "datadog/opentelemetry"
+
+# 3. Configure OpenTelemetry SDK (Datadog intercepts this)
+OpenTelemetry::SDK.configure do |c|
+  c.service_name = "my-app"
+end
+```
+
+::: warning Important
+The `opentelemetry-sdk` gem is required — not just `opentelemetry-api`. The Datadog bridge only activates when `OpenTelemetry::SDK` is defined and `OpenTelemetry::SDK.configure` is called.
+:::
+
+With this setup, all Axn actions will automatically create spans that appear in Datadog APM as children of your Rails request traces.
+
+## `emit_metrics`
 
-    c.emit_metrics = proc do |resource, result|
+If you're using a metrics provider, you can emit custom metrics after each action completes using the `emit_metrics` hook. This is a post-execution hook that receives the action result—do NOT call any blocks.
+
+The hook only receives the keyword arguments it explicitly expects (e.g., if you only define `resource:`, you won't receive `result:`).
+
+For example, to wire up Datadog metrics:
+
+```ruby
+  Axn.configure do |c|
+    c.emit_metrics = proc do |resource:, result:|
       TS::Metrics.increment("action.#{resource.underscore}", tags: { outcome: result.outcome.to_s, resource: })
       TS::Metrics.histogram("action.duration", result.elapsed_time, tags: { resource: })
     end
   end
 ```
 
+You can also define `emit_metrics` to only receive the arguments you need:
+
+```ruby
+  # Only receive resource (if you don't need the result)
+  c.emit_metrics = proc do |resource:|
+    TS::Metrics.increment("action.#{resource.underscore}")
+  end
+
+  # Only receive result (if you don't need the resource)
+  c.emit_metrics = proc do |result:|
+    TS::Metrics.increment("action.call", tags: { outcome: result.outcome.to_s })
+  end
+
+  # Accept any keyword arguments (receives both)
+  c.emit_metrics = proc do |**kwargs|
+    # kwargs will contain both :resource and :result
+  end
+```
+
+**Important:** When using `result:` in your `emit_metrics` hook, be careful about cardinality. Avoid creating metrics with unbounded tag values from the result (e.g., user IDs, email addresses, or other high-cardinality data). Instead, use bounded values like `result.outcome.to_s` or aggregate data. High-cardinality metrics can cause performance issues and increased costs with metrics providers.
+
 A couple notes:
 
-  * `Datadog::Tracing` is provided by [the datadog gem](https://rubygems.org/gems/datadog)
   * `TS::Metrics` is a custom implementation to set a Datadog count metric, but the relevant part to note is that the result object provides access to the outcome (`result.outcome.success?`, `result.outcome.failure?`, `result.outcome.exception?`) and elapsed time of the action.
-  * The `wrap_with_trace` hook is an around hook - you must call the provided block to execute the action
   * The `emit_metrics` hook is called after execution with the result - do not call any blocks
 
 ## `logger`
@@ -109,7 +269,7 @@ This ensures that:
 
 ## `additional_includes`
 
-This is much less critical than the preceding options, but on the off chance you want to add additional customization to _all_ your actions you can set additional modules to be included alongside `include Action`.
+This is much less critical than the preceding options, but on the off chance you want to add additional customization to _all_ your actions you can set additional modules to be included alongside `include Axn`.
 
 For example:
 
@@ -127,7 +287,35 @@ Sets the log level used when you call `log "Some message"` in your Action.  Note
 
 ## `env`
 
-Automatically detects the environment from `RACK_ENV` or `RAILS_ENV`, defaulting to `"development"`. This is used internally for conditional behavior (e.g., more verbose logging in non-production environments).
+Automatically detects the environment from `RACK_ENV` or `RAILS_ENV`, defaulting to `"development"`. Returns an `ActiveSupport::StringInquirer`, allowing you to use predicate methods like `env.production?` or `env.development?`.
+
+```ruby
+Axn.config.env.production?   # => true/false
+Axn.config.env.development?  # => true/false
+Axn.config.env.test?         # => true/false
+```
+
+### Environment-Dependent Behavior
+
+Several Axn behaviors change based on the detected environment:
+
+| Behavior | Production | Test | Development |
+| -------- | ---------- | ---- | ----------- |
+| Log separators in async calls | Hidden | Visible (`------`) | Visible (`------`) |
+| `raise_piping_errors_in_dev` | Always swallowed | Always swallowed | Configurable |
+| Error message verbosity | Minimal | More detailed | More detailed |
+
+### Overriding the Environment
+
+You can explicitly set the environment if auto-detection doesn't work for your setup:
+
+```ruby
+Axn.configure do |c|
+  c.env = "staging"
+end
+
+Axn.config.env.staging?  # => true
+```
 
 ## `set_default_async`
 
@@ -237,7 +425,7 @@ By default, every `action.call` will emit log lines when it is called and after
     [YourCustomAction] Execution completed (with outcome: success) in 0.957 milliseconds
   ```
 
-Automatic logging will log at `Axn.config.log_level` by default, but can be overridden or disabled using the declarative `auto_log` method:
+Automatic logging will log at `Axn.config.log_level` by default, but can be overridden or disabled using the declarative `log_calls` method:
 
 ```ruby
 # Set default for all actions (affects both explicit logging and automatic logging)
@@ -247,79 +435,46 @@ end
 
 # Override for specific actions
 class MyAction
-  auto_log :warn  # Use warn level for this action
+  log_calls :warn  # Use warn level for this action
 end
 
 class SilentAction
-  auto_log false  # Disable automatic logging for this action
+  log_calls false  # Disable automatic logging for this action
 end
 
-# Use default level (no auto_log call needed)
+# Use default level (no log_calls call needed)
 class DefaultAction
   # Uses Axn.config.log_level
 end
 ```
 
-The `auto_log` method supports inheritance, so subclasses will inherit the setting from their parent class unless explicitly overridden.
-
-## Profiling
-
-Axn supports performance profiling using [Vernier](https://github.com/Shopify/vernier), a Ruby sampling profiler. Profiling is enabled per-action by calling the `profile` method.
+The `log_calls` method supports inheritance, so subclasses will inherit the setting from their parent class unless explicitly overridden.
 
-### Usage
+### Error-Only Logging
 
-Enable profiling on specific actions using the `profile` method:
+For actions where you only want to log when something goes wrong, use `log_errors` instead of `log_calls`. This will:
+- **Not** log before execution
+- **Only** log after execution if `result.ok?` is false (i.e., on failures or exceptions)
 
 ```ruby
 class MyAction
-  include Axn
-
-  # Profile conditionally (only one profile call per action)
-  profile if: -> { debug_mode }
-
-  expects :name, :debug_mode
-
-  def call
-    "Hello, #{name}!"
-  end
+  log_calls false   # Disable full logging
+  log_errors :warn  # Only log failures/exceptions at warn level
 end
-```
 
-### Configuration Options
-
-The `profile` method accepts several options:
-
-```ruby
-class MyAction
-  include Axn
-
-  # Profile with custom options
-  profile(
-    if: -> { debug_mode },
-    sample_rate: 0.1,  # Sampling rate (0.0 to 1.0, default: 0.1)
-    output_dir: "tmp/profiles"  # Output directory (default: Rails.root/tmp/profiles or tmp/profiles)
-  )
+class SilentOnErrorsAction
+  log_calls false
+  log_errors false  # Disable error logging for this action
+end
 
-  def call
-    # Action logic
-  end
+# Use default level
+class DefaultErrorLoggingAction
+  log_calls false
+  log_errors Axn.config.log_level  # Uses default log level
 end
 ```
 
-**Important**:
-- You can only call `profile` **once per action** - subsequent calls will override the previous one
-- This prevents accidental profiling of all actions and ensures you only profile what you intend to analyze
-
-### Viewing Profiles
-
-Profiles are saved as JSON files that can be viewed in the [Firefox Profiler](https://profiler.firefox.com/):
-
-1. Run your action with profiling enabled
-2. Find the generated profile file in your `profiling_output_dir`
-3. Upload the JSON file to [profiler.firefox.com](https://profiler.firefox.com/)
-4. Analyze the performance data
-
-For more detailed information, see the [Profiling guide](/advanced/profiling).
+The `log_errors` method supports inheritance, just like `log_calls`. If both `log_calls` and `log_errors` are set, `log_calls` takes precedence (it will log before and after for all outcomes). To use `log_errors` exclusively, you must first disable `log_calls` with `log_calls false`.
 
 ## Complete Configuration Example
 
@@ -339,13 +494,9 @@ Axn.configure do |c|
   end
 
   # Observability
-  c.wrap_with_trace = proc do |resource, &action|
-    Datadog::Tracing.trace("Action", resource:) do
-      action.call
-    end
-  end
+  # OpenTelemetry tracing is automatic when OpenTelemetry is available
 
-  c.emit_metrics = proc do |resource, result|
+  c.emit_metrics = proc do |resource:, result:|
     Datadog::Metrics.increment("action.#{resource.underscore}", tags: { outcome: result.outcome.to_s })
     Datadog::Metrics.histogram("action.duration", result.elapsed_time, tags: { resource: })
   end