flow_chat 0.8.1 → 0.9.0

data/docs/instrumentation.md

@@ -1,216 +1,327 @@
-# Instrumentation & Monitoring
+# Instrumentation
 
-FlowChat includes a comprehensive instrumentation system for observability, monitoring, and logging.
+FlowChat provides comprehensive instrumentation via ActiveSupport::Notifications, enabling monitoring, logging, metrics collection, and error tracking across all platforms.
 
-## Quick Setup
-
-Enable instrumentation in your Rails application:
+## Quick Start
 
 ```ruby
-# config/initializers/flowchat.rb
-FlowChat.setup_instrumentation!
+# Subscribe to all FlowChat events
+ActiveSupport::Notifications.subscribe(/\.flow_chat$/) do |event|
+  Rails.logger.info "FlowChat: #{event.name} - #{event.payload}"
+end
+
+# Subscribe to specific events
+ActiveSupport::Notifications.subscribe("api.error.flow_chat") do |event|
+  Sentry.capture_message("API Error", extra: event.payload)
+end
 ```
 
-This sets up:
-- 📊 **Metrics Collection** - Performance and usage metrics
-- 📝 **Structured Logging** - Event-driven logs with context
-- 🔍 **Event Tracking** - All framework events instrumented
-- ⚡ **Performance Monitoring** - Execution timing and bottleneck detection
+## Event Reference
+
+All events are namespaced with `.flow_chat` suffix. Use `FlowChat::Instrumentation::Events` constants for consistency.
 
-## Features
+### Core Framework Events
 
-**🎯 Zero Configuration**
-- Works out of the box with Rails applications
-- Automatic ActiveSupport::Notifications integration
-- Thread-safe metrics collection
+| Event | Description | Key Payload |
+|-------|-------------|-------------|
+| `flow.execution.start` | Flow method begins executing | `flow_name`, `action`, `session_id` |
+| `flow.execution.end` | Flow method completes | `flow_name`, `action`, `duration` |
+| `flow.execution.error` | Unhandled error in flow | `flow_name`, `error`, `backtrace` |
+| `context.created` | New request context created | `request_id`, `platform` |
 
-**📈 Comprehensive Metrics**
-- Flow execution counts and timing
-- Session creation/destruction rates
-- WhatsApp/USSD message volumes
-- Cache hit/miss ratios
-- Error tracking by type and flow
+### Session Events
 
-**🔍 Rich Event Tracking**
-- 20+ predefined event types (see [Event Types](#event-types))
-- Automatic context enrichment (session ID, flow name, gateway)
-- Structured event payloads
+| Event | Description | Key Payload |
+|-------|-------------|-------------|
+| `session.created` | New session started | `session_id`, `boundaries` |
+| `session.destroyed` | Session ended/cleared | `session_id` |
+| `session.data.get` | Session data read | `session_id`, `key` |
+| `session.data.set` | Session data written | `session_id`, `key` |
+| `session.cache.hit` | Session found in cache | `session_id` |
+| `session.cache.miss` | Session not in cache | `session_id` |
 
-**📊 Production Ready**
-- Minimal performance overhead
-- Thread-safe operations
-- Graceful error handling
+### Messaging Events
 
-## Event Types
+| Event | Description | Key Payload |
+|-------|-------------|-------------|
+| `message.received` | Inbound message from user | `platform`, `from`, `message_type` |
+| `message.sent` | Outbound message to user | `platform`, `to`, `message_type`, `content_length` |
+| `media.upload` | Media file uploaded (WhatsApp) | `platform`, `filename`, `mime_type`, `size` |
+| `pagination.triggered` | USSD pagination activated | `session_id`, `page`, `total_pages` |
 
-FlowChat instruments the following events:
+### Webhook Events
 
-### Flow Events
-- `flow.execution.start.flow_chat`
-- `flow.execution.end.flow_chat`
-- `flow.execution.error.flow_chat`
+| Event | Description | Key Payload |
+|-------|-------------|-------------|
+| `webhook.verified` | Webhook signature valid (WhatsApp) | `platform`, `gateway` |
+| `webhook.failed` | Webhook validation failed (WhatsApp) | `platform`, `reason` |
 
-### Session Events
-- `session.created.flow_chat`
-- `session.destroyed.flow_chat`
-- `session.data.get.flow_chat`
-- `session.data.set.flow_chat`
-- `session.cache.hit.flow_chat`
-- `session.cache.miss.flow_chat`
+### API Events
 
-### WhatsApp Events
-- `whatsapp.message.received.flow_chat`
-- `whatsapp.message.sent.flow_chat`
-- `whatsapp.webhook.verified.flow_chat`
-- `whatsapp.api.request.flow_chat`
-- `whatsapp.media.upload.flow_chat`
+| Event | Description | Key Payload |
+|-------|-------------|-------------|
+| `api.error` | API call failed | `platform`, `message`, error details |
 
-### USSD Events
-- `ussd.message.received.flow_chat`
-- `ussd.message.sent.flow_chat`
-- `ussd.pagination.triggered.flow_chat`
+### Events for Custom Use
 
-## Usage Examples
+The following event constants are provided for use in your own instrumentation but are not emitted by FlowChat internally:
 
-### Access Metrics
+| Event | Suggested Use | Key Payload |
+|-------|---------------|-------------|
+| `api.request` | Wrap outbound API calls | `platform`, `endpoint` |
+| `middleware.before` | Custom middleware entry | `middleware_class` |
+| `middleware.after` | Custom middleware exit | `middleware_class`, `duration` |
+| `conversation.assigned` | Intercom assignment tracking | `conversation_id`, `admin_id` |
+| `conversation.tagged` | Intercom tag tracking | `conversation_id`, `tag` |
+| `conversation.state_changed` | Intercom state tracking | `conversation_id`, `state` |
 
+## API Error Instrumentation
+
+The `api.error` event provides detailed information when API calls fail. This is useful for monitoring, alerting, and debugging integration issues.
+
+### Event Payload by Platform
+
+**Telegram:**
 ```ruby
-# Get current metrics snapshot
-metrics = FlowChat.metrics.snapshot
-
-# Flow execution metrics
-flow_metrics = FlowChat.metrics.get_category("flows")
-puts flow_metrics["flows.executed"] # Total flows executed
-puts flow_metrics["flows.execution_time"] # Average execution time
-
-# Session metrics  
-session_metrics = FlowChat.metrics.get_category("sessions")
-puts session_metrics["sessions.created"] # Total sessions created
-puts session_metrics["sessions.cache.hits"] # Cache hit count
+{
+  platform: :telegram,
+  message: "Telegram API error: Unauthorized",
+  bot_id: "123456789",
+  api_method: "sendMessage",
+  error_code: 401,
+  error_description: "Unauthorized",
+  chat_id: 987654321
+}
 ```
 
-### Custom Instrumentation in Flows
+**WhatsApp:**
+```ruby
+{
+  platform: :whatsapp,
+  message: "WhatsApp API request failed",
+  phone_number_id: "123456789",
+  recipient: "+1234567890",
+  message_type: "text",
+  response_code: "401",
+  error_type: "OAuthException",
+  error_code: 190,
+  error_subcode: 463,
+  error_message: "Error validating access token"
+}
+```
 
+**Intercom:**
 ```ruby
-class PaymentFlow < FlowChat::Flow
-  def process_payment
-    # Instrument custom events in your flows
-    instrument("payment.started", {
-      amount: payment_amount,
-      currency: "USD",
-      payment_method: "mobile_money"
-    }) do
-      # Payment processing logic
-      result = process_mobile_money_payment
-      
-      # Event automatically includes session_id, flow_name, gateway
-      result
-    end
-  end
-end
+{
+  platform: :intercom,
+  message: "Intercom authentication failed",
+  app_id: "abc123def",
+  conversation_id: "conv_123",
+  admin_id: "admin_456"
+}
 ```
 
-### Event Subscribers
+### Error Handling Behavior
 
-```ruby
-# config/initializers/flowchat_instrumentation.rb
-FlowChat.setup_instrumentation!
+| Error Type | Telegram | WhatsApp | Intercom |
+|------------|----------|----------|----------|
+| Invalid credentials | Returns `{"ok"=>false}` | Returns `nil` | Raises `ConfigurationError` |
+| API error response | Returns error hash | Returns `nil` | Returns `nil` |
+| Network timeout | Re-raises exception | Re-raises exception | Re-raises exception |
+| Connection refused | Returns `{"ok"=>false}` | Returns `nil` | Returns `nil` |
 
-# Subscribe to specific events
-ActiveSupport::Notifications.subscribe("flow.execution.end.flow_chat") do |event|
-  duration = event.duration
-  flow_name = event.payload[:flow_name]
-  
-  # Send to external monitoring service
-  ExternalMonitoring.track_flow_execution(flow_name, duration)
-end
+**Note:** Network timeouts (`Net::OpenTimeout`, `Net::ReadTimeout`) are intentionally re-raised without instrumentation, allowing callers to implement retry logic at a higher level.
 
-# Subscribe to all FlowChat events
-ActiveSupport::Notifications.subscribe(/\.flow_chat$/) do |name, start, finish, id, payload|
-  CustomLogger.log_event(name, payload.merge(duration: finish - start))
+### Example: Error Monitoring
+
+```ruby
+# config/initializers/flow_chat_monitoring.rb
+
+ActiveSupport::Notifications.subscribe("api.error.flow_chat") do |event|
+  payload = event.payload
+
+  # Log with structured data
+  Rails.logger.error({
+    event: "flow_chat.api_error",
+    platform: payload[:platform],
+    message: payload[:message],
+    error_code: payload[:error_code],
+    recipient: payload[:recipient] || payload[:chat_id] || payload[:conversation_id]
+  }.to_json)
+
+  # Send to error tracking service
+  Sentry.capture_message(
+    "FlowChat API Error: #{payload[:message]}",
+    level: :error,
+    extra: payload
+  )
+
+  # Increment metrics
+  StatsD.increment("flow_chat.api_error", tags: ["platform:#{payload[:platform]}"])
 end
 ```
 
-### Integration with Monitoring Services
+### Example: Rails Error Reporting
+
+FlowChat automatically reports errors to `Rails.error` when available (Rails 7+):
 
 ```ruby
-# config/initializers/flowchat_monitoring.rb
-FlowChat.setup_instrumentation!
-
-# Export metrics to Prometheus, StatsD, etc.
-ActiveSupport::Notifications.subscribe("flow.execution.end.flow_chat") do |event|
-  StatsD.increment("flowchat.flows.executed")
-  StatsD.timing("flowchat.flows.duration", event.duration)
-  StatsD.increment("flowchat.flows.#{event.payload[:flow_name]}.executed")
-end
+# Errors are automatically reported with context:
+Rails.error.report(exception, handled: true, context: {
+  platform: :whatsapp,
+  recipient: "+1234567890",
+  message_type: "text"
+})
+```
+
+You can subscribe to these in your error reporting configuration:
+
+```ruby
+# config/initializers/error_reporting.rb
+Rails.error.subscribe(MyErrorReporter.new)
+```
+
+## Custom Instrumentation
+
+### In Flows
 
-# Track error rates
-ActiveSupport::Notifications.subscribe("flow.execution.error.flow_chat") do |event|
-  StatsD.increment("flowchat.flows.errors")
-  StatsD.increment("flowchat.flows.errors.#{event.payload[:error_class]}")
+```ruby
+class PaymentFlow < FlowChat::Flow
+  def process_payment
+    amount = app.screen(:amount) { |p| p.ask "Enter amount:" }
+
+    instrument(Events::API_REQUEST, { endpoint: "payment_gateway" }) do
+      result = PaymentGateway.charge(amount)
+
+      if result.success?
+        app.say "Payment successful!"
+      else
+        instrument(Events::API_ERROR, {
+          message: "Payment failed",
+          error_code: result.error_code
+        })
+        app.say "Payment failed: #{result.error}"
+      end
+    end
+  end
 end
 ```
 
-## Performance Impact
+### In Custom Middleware
 
-The instrumentation system is designed for production use with minimal overhead:
+```ruby
+class MetricsMiddleware
+  include FlowChat::Instrumentation
+
+  def initialize(app)
+    @app = app
+  end
 
-- **Event Publishing**: ~0.1ms per event
-- **Metrics Collection**: Thread-safe atomic operations
-- **Memory Usage**: <1MB for typical applications
-- **Storage**: Events are ephemeral, metrics are kept in memory
+  def call(context)
+    @context = context
 
-## Debugging & Troubleshooting
+    instrument(Events::MIDDLEWARE_BEFORE, { middleware_class: self.class.name })
 
-### Enable Debug Logging
+    start_time = Time.current
+    result = @app.call(context)
+    duration = Time.current - start_time
 
-```ruby
-# config/environments/development.rb
-config.log_level = :debug
+    instrument(Events::MIDDLEWARE_AFTER, {
+      middleware_class: self.class.name,
+      duration: duration
+    })
+
+    result
+  end
+
+  # Required for context enrichment
+  attr_reader :context
+end
 ```
 
-### Reset Metrics
+### Module-Level Instrumentation
 
 ```ruby
-# Clear all metrics (useful for testing)
-FlowChat.metrics.reset!
+# Direct instrumentation without including the module
+FlowChat::Instrumentation.instrument("custom.event", {
+  custom_key: "custom_value"
+})
 ```
 
-### Check Event Subscribers
+## Payload Enrichment
+
+When instrumenting from objects with a `context` accessor, payloads are automatically enriched with:
+
+- `request_id` - Unique request identifier
+- `session_id` - Current session ID
+- `flow_name` - Active flow class name
+- `gateway` - Gateway handling the request
+- `platform` - Platform (`:ussd`, `:whatsapp`, `:telegram`, `:intercom`)
+
+All payloads also include:
+- `timestamp` - Event timestamp (`Time.current`)
+
+## Subscribing to Events
+
+### Pattern Matching
 
 ```ruby
-# See all active subscribers
-ActiveSupport::Notifications.notifier.listeners_for("flow.execution.end.flow_chat")
+# All FlowChat events
+ActiveSupport::Notifications.subscribe(/\.flow_chat$/) { |event| ... }
+
+# All error events
+ActiveSupport::Notifications.subscribe(/error\.flow_chat$/) { |event| ... }
+
+# All session events
+ActiveSupport::Notifications.subscribe(/^session\..*\.flow_chat$/) { |event| ... }
 ```
 
-## Testing Instrumentation
+### Block vs Callable
 
 ```ruby
-# test/test_helper.rb
-class ActiveSupport::TestCase
-  setup do
-    # Reset metrics before each test
-    FlowChat::Instrumentation::Setup.reset! if FlowChat::Instrumentation::Setup.setup?
+# Block form (simple)
+ActiveSupport::Notifications.subscribe("message.sent.flow_chat") do |event|
+  puts event.payload
+end
+
+# Callable form (for complex subscribers)
+class MessageLogger
+  def call(event)
+    # Access timing info
+    puts "Duration: #{event.duration}ms"
+    puts "Payload: #{event.payload}"
   end
 end
 
-# In your tests
+ActiveSupport::Notifications.subscribe("message.sent.flow_chat", MessageLogger.new)
+```
+
+## Testing
+
+```ruby
 class FlowInstrumentationTest < ActiveSupport::TestCase
-  test "flow execution is instrumented" do
+  def test_api_error_instrumentation
     events = []
-    
-    # Capture events
-    ActiveSupport::Notifications.subscribe(/flow_chat$/) do |name, start, finish, id, payload|
-      events << { name: name, payload: payload, duration: (finish - start) * 1000 }
+
+    ActiveSupport::Notifications.subscribe("api.error.flow_chat") do |event|
+      events << event
     end
-    
-    # Execute flow
-    processor.run(WelcomeFlow, :main_page)
-    
-    # Verify events
-    assert_equal 2, events.size
-    assert_equal "flow.execution.start.flow_chat", events[0][:name]
-    assert_equal "flow.execution.end.flow_chat", events[1][:name]
-    assert_equal "welcome_flow", events[0][:payload][:flow_name]
+
+    # Trigger the error condition
+    client.send_message_with_invalid_token
+
+    assert_equal 1, events.size
+    assert_equal :whatsapp, events.first.payload[:platform]
+  ensure
+    ActiveSupport::Notifications.unsubscribe("api.error.flow_chat")
   end
-end 
+end
+```
+
+## Production Recommendations
+
+1. **Subscribe early** - Set up subscriptions in initializers before requests arrive
+2. **Keep handlers fast** - Use async processing for slow operations (logging to external services)
+3. **Filter events** - Only subscribe to events you need to avoid overhead
+4. **Use structured logging** - Log payloads as JSON for easier querying
+5. **Set up alerting** - Configure alerts on `api.error` events for proactive monitoring