Observability + DX + Testing

How unified events, logging, DX helpers, and offline/stub clients fit together.

This page ties together Observability, DX helpers, and Testing patterns for a cohesive workflow.

Observability recap

• Unified events via ActiveSupport::Notifications: search_engine.search, search_engine.multi_search, search_engine.schema.*, indexer.*, and compile‑time summaries (joins/grouping/selection/facets/highlight/synonyms/geo/vector/hit limits).
• Redaction policy ensures no secrets or raw filter literals are logged. Use params_preview and filter_hash.
• Optional subscribers:
  • LoggingSubscriber (config.logging.mode = :compact|:json)
  • OpenTelemetry adapter (config.opentelemetry.enabled = true)

See: Observability

DX helpers

• to_params_json — redacted JSON, stable keys
• to_curl — one‑liner with redacted API key
• dry_run! — compile only; returns { url:, body:, url_opts: }
• explain — extended overview (grouping, joins, presets/curation, conflicts, predicted events)

See: DX

Testing offline

• Automatic offline mode: SearchEngine.client returns SearchEngine::Test::OfflineClient in test mode (Rails test or RACK_ENV=test)
• Stub client: SearchEngine::Test::StubClient for programmable responses
• Queue responses per verb and assert on captured calls (URL, redaction flags, redacted body)
• Event assertions with RSpec or Minitest helpers
• Use SearchEngine.client to access the configured client instance

See: Testing

Putting it together

rel = SearchEngine::Book.where(active: true).select(:id, :name).per(5)

# DX preview (no I/O)
rel.dry_run!
puts rel.explain

# Observability: subscribe in tests
events = capture_events { rel.to_a }

# Testing: stub and enqueue
SearchEngine.configure do |c|
  c.client = SearchEngine::Test::StubClient.new
end
stub = SearchEngine.client
stub.enqueue_response(:search, { 'hits' => [], 'found' => 0, 'out_of' => 0 })
rel.to_a

Troubleshooting

• Missing events: enable subscriber/logging or OTel and wrap calls
• Redaction gaps: use params_preview, never log raw bodies
• DX helpers performing I/O: re‑check call site; helpers are pure

Backlinks: Observability · DX · Testing