flow_chat 0.9.0 → 0.10.1

data/docs/instrumentation.md

@@ -1,327 +1,136 @@
 # Instrumentation
 
-FlowChat provides comprehensive instrumentation via ActiveSupport::Notifications, enabling monitoring, logging, metrics collection, and error tracking across all platforms.
+FlowChat emits `ActiveSupport::Notifications` events at each stage of a request, so you can feed metrics, traces, and structured logs into your own backend. The events fire whether or not anything subscribes; FlowChat also ships a log subscriber and a metrics collector that subscribe for you.
 
-## Quick Start
+## Event names
 
-```ruby
-# 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
-```
-
-## Event Reference
-
-All events are namespaced with `.flow_chat` suffix. Use `FlowChat::Instrumentation::Events` constants for consistency.
-
-### Core Framework Events
-
-| 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` |
-
-### Session Events
-
-| 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` |
-
-### Messaging Events
-
-| 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` |
-
-### Webhook Events
-
-| Event | Description | Key Payload |
-|-------|-------------|-------------|
-| `webhook.verified` | Webhook signature valid (WhatsApp) | `platform`, `gateway` |
-| `webhook.failed` | Webhook validation failed (WhatsApp) | `platform`, `reason` |
-
-### API Events
-
-| Event | Description | Key Payload |
-|-------|-------------|-------------|
-| `api.error` | API call failed | `platform`, `message`, error details |
+Every FlowChat event is published under its name with a `.flow_chat` suffix. The name in the table is what you pass to `instrument`; the string you subscribe to adds the suffix, for example `flow.execution.end.flow_chat`.
 
-### Events for Custom Use
+| Event | When it fires |
+|---|---|
+| `flow.execution.start` | A flow action begins. |
+| `flow.execution.end` | A flow action finishes (carries `duration`). |
+| `flow.execution.error` | A flow action raised. |
+| `context.created` | A request context is built. |
+| `session.created` | A session is created. |
+| `session.destroyed` | A session is destroyed (flow terminated). |
+| `session.data.get` / `session.data.set` | A session value is read or written. |
+| `session.cache.hit` / `session.cache.miss` | A session cache lookup. |
+| `message.received` | An inbound message arrives (text or an attachment). |
+| `message.sent` | A response is sent to the user. |
+| `message.delivery_failed` | A reply the flow produced that the platform would not take. |
+| `message.status` | A platform's own report of what became of a message we sent. |
+| `webhook.verified` / `webhook.failed` | A gateway verified or rejected a webhook. |
+| `api.request` / `api.error` | An outbound platform API call, or its failure. |
+| `media.upload` | Media is uploaded to a platform. |
+| `pagination.triggered` | A USSD response was split into pages. |
+| `webhook.received` | A verified webhook this gateway does not model, handed on whole. |
 
-The following event constants are provided for use in your own instrumentation but are not emitted by FlowChat internally:
+Payloads are enriched with `request_id`, `session_id`, `flow_name`, `gateway`, and `platform` when the context has them, plus a `timestamp`.
 
-| 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` |
+## Webhooks that are not messaging
 
-## API Error Instrumentation
+FlowChat's job is messaging: the inbound turn, the reply it produces, and what became of that reply. A platform sends a great deal more. WhatsApp alone will report account bans, template approvals, phone number quality, imported chat history, contact address books, and replies a human typed in the WhatsApp Business App, and it adds new fields regularly.
 
-The `api.error` event provides detailed information when API calls fail. This is useful for monitoring, alerting, and debugging integration issues.
+None of that is a customer turn, so **none of it runs a flow**, and none of it is interpreted here. FlowChat verifies the signature, answers the platform, and publishes the change under `webhook.received` with the field that named it. What it means is your application's decision:
 
-### Event Payload by Platform
-
-**Telegram:**
 ```ruby
-{
-  platform: :telegram,
-  message: "Telegram API error: Unauthorized",
-  bot_id: "123456789",
-  api_method: "sendMessage",
-  error_code: 401,
-  error_description: "Unauthorized",
-  chat_id: 987654321
-}
-```
-
-**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
-{
-  platform: :intercom,
-  message: "Intercom authentication failed",
-  app_id: "abc123def",
-  conversation_id: "conv_123",
-  admin_id: "admin_456"
-}
-```
-
-### Error Handling Behavior
-
-| 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` |
-
-**Note:** Network timeouts (`Net::OpenTimeout`, `Net::ReadTimeout`) are intentionally re-raised without instrumentation, allowing callers to implement retry logic at a higher level.
-
-### 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]}"])
+ActiveSupport::Notifications.subscribe("webhook.received.flow_chat") do |*, payload|
+  case payload[:field]
+  when "smb_message_echoes"
+    # A human answered from the WhatsApp Business App. Most applications will want
+    # to stop the bot replying on top of them.
+    MyApp::Echoes.record(payload[:business_phone_number_id], payload[:value]["message_echoes"])
+  when "history"
+    MyApp::HistoryImport.enqueue(payload[:business_phone_number_id], payload[:value]["history"])
+  when "account_update"
+    MyApp::Connections.review(payload[:business_phone_number_id], payload[:value])
+  end
 end
 ```
 
-### Example: Rails Error Reporting
+The payload carries `field`, the whole `value`, and the business phone number when the change names one. Account-level changes do not name one, so expect it to be nil there.
 
-FlowChat automatically reports errors to `Rails.error` when available (Rails 7+):
+Subscribing to a field costs nothing here: an unmodelled field is published whether or not anything listens, and logged at info so a subscription you have not written yet is still visible. Adding support for a new field is a change in your application, not a new release of this gem.
 
-```ruby
-# Errors are automatically reported with context:
-Rails.error.report(exception, handled: true, context: {
-  platform: :whatsapp,
-  recipient: "+1234567890",
-  message_type: "text"
-})
-```
+## Reacting to `api.error`
 
-You can subscribe to these in your error reporting configuration:
+The `message` on an `api.error` payload is prose, written for someone reading
+logs. Do not branch on it: rewording a log line would change your behaviour.
+Read these instead.
 
-```ruby
-# config/initializers/error_reporting.rb
-Rails.error.subscribe(MyErrorReporter.new)
-```
+| key | meaning |
+|---|---|
+| `error_class` | The exception's class, whenever one was raised. |
+| `error_type` | What kind of failure it is, named by the adapter. Intercom reports `authentication`, `resource_not_found` and `server_error`; WhatsApp passes through Meta's own `type`, such as `OAuthException`. |
+| `error_code` | The platform's own code. Telegram's `error_code`, Meta's `code`, Intercom's HTTP status. |
 
-## Custom Instrumentation
+WhatsApp also carries `error_subcode` and `error_message` from Meta, and
+Telegram carries `error_description`. Identify the connection from
+`phone_number_id`, `bot_id` or `app_id` as appropriate.
 
-### In Flows
+Not every failure reports. Network timeouts are re-raised so your own retry
+logic sees them, and an Intercom rate limit raises `RateLimitError` rather than
+reporting, so a subscriber reacting to `api.error` will not mistake either for
+a dead credential.
 
 ```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
+ActiveSupport::Notifications.subscribe("api.error.flow_chat") do |*, payload|
+  next unless payload[:error_type] == "authentication"
+
+  AlertOwner.call(platform: payload[:platform], app_id: payload[:app_id])
 end
 ```
 
-### In Custom Middleware
-
-```ruby
-class MetricsMiddleware
-  include FlowChat::Instrumentation
-
-  def initialize(app)
-    @app = app
-  end
-
-  def call(context)
-    @context = context
+## Delivery callbacks
 
-    instrument(Events::MIDDLEWARE_BEFORE, { middleware_class: self.class.name })
+Events are broadcasts and carry no context, because anyone may subscribe and the context holds the gateway client and the raw inbound body. When the application that owns the turn needs to reach its own records, it uses a callback instead.
 
-    start_time = Time.current
-    result = @app.call(context)
-    duration = Time.current - start_time
+A gateway that delivers out of band (Telegram, WhatsApp, Intercom) sends after the middleware stack has unwound. So a row the application wrote during the turn was written before anything knew whether the send worked, or what the platform would call it. These two callbacks are the only places that know:
 
-    instrument(Events::MIDDLEWARE_AFTER, {
-      middleware_class: self.class.name,
-      duration: duration
-    })
-
-    result
-  end
-
-  # Required for context enrichment
-  attr_reader :context
+```ruby
+FlowChat::Config.on_delivery_success = lambda do |context, result|
+  id = context[FlowChat::Instrumentation::DELIVERED_MESSAGE_ID_KEY]
+  MyApp::Message.find(context["myapp.bot_message_id"]).update!(platform_message_id: id) if id
 end
-```
-
-### Module-Level Instrumentation
 
-```ruby
-# Direct instrumentation without including the module
-FlowChat::Instrumentation.instrument("custom.event", {
-  custom_key: "custom_value"
-})
+FlowChat::Config.on_delivery_failure = lambda do |context, error|
+  MyApp::Message.find(context["myapp.bot_message_id"]).update!(status: :failed, error: error.message)
+end
 ```
 
-## Payload Enrichment
+`DELIVERED_MESSAGE_ID_KEY` is `"delivery.platform_message_id"`, and every out-of-band gateway sets it to whatever its own platform called the message: WhatsApp's `wamid`, Telegram's numeric `message_id`, Intercom's conversation part id. It is nil when a platform names none. Reading one key is the point, so an application does not carry a case statement over platforms.
 
-When instrumenting from objects with a `context` accessor, payloads are automatically enriched with:
+HTTP and USSD set nothing, since their reply travels in the response they are already returning and has no separate delivery to succeed or fail.
 
-- `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`)
+Neither callback may change what happened. `on_delivery_success` cannot alter the send's return value, `on_delivery_failure` cannot replace the delivery error, and an exception raised in either is logged and dropped.
 
-All payloads also include:
-- `timestamp` - Event timestamp (`Time.current`)
+## Subscribing
 
-## Subscribing to Events
-
-### Pattern Matching
-
-```ruby
-# 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| ... }
-```
-
-### Block vs Callable
+Subscribe with `ActiveSupport::Notifications`, remembering the `.flow_chat` suffix:
 
 ```ruby
-# Block form (simple)
-ActiveSupport::Notifications.subscribe("message.sent.flow_chat") do |event|
-  puts event.payload
+ActiveSupport::Notifications.subscribe("flow.execution.end.flow_chat") do |*, payload|
+  StatsD.timing("flow_chat.flow.#{payload[:flow_name]}", payload[:duration])
 end
 
-# Callable form (for complex subscribers)
-class MessageLogger
-  def call(event)
-    # Access timing info
-    puts "Duration: #{event.duration}ms"
-    puts "Payload: #{event.payload}"
-  end
+ActiveSupport::Notifications.subscribe("message.received.flow_chat") do |*, payload|
+  StatsD.increment("flow_chat.message.received.#{payload[:platform]}")
 end
-
-ActiveSupport::Notifications.subscribe("message.sent.flow_chat", MessageLogger.new)
 ```
 
-## Testing
-
-```ruby
-class FlowInstrumentationTest < ActiveSupport::TestCase
-  def test_api_error_instrumentation
-    events = []
-
-    ActiveSupport::Notifications.subscribe("api.error.flow_chat") do |event|
-      events << event
-    end
+## Built-in metrics
 
-    # Trigger the error condition
-    client.send_message_with_invalid_token
+`FlowChat.metrics` returns a metrics collector that subscribes to the events above and keeps running counters and timings (flows executed, errors by class, sessions created by gateway, cache hits, and so on). Read a snapshot:
 
-    assert_equal 1, events.size
-    assert_equal :whatsapp, events.first.payload[:platform]
-  ensure
-    ActiveSupport::Notifications.unsubscribe("api.error.flow_chat")
-  end
-end
+```ruby
+FlowChat.metrics.snapshot                 # => a Hash of counters and timings
+FlowChat.metrics.get_category("flows")    # => just the flows.* metrics
 ```
 
-## Production Recommendations
+FlowChat also ships a `LogSubscriber` that logs the same events through `FlowChat::Config.logger`. Both are wired up by `FlowChat::Instrumentation::Setup`; call `FlowChat.setup_instrumentation!` during boot to enable them, or access `FlowChat.metrics` to start the collector on first use.
+
+## Related
 
-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
+- [Configuration](configuration.md)
+- [Architecture](architecture.md)