Skip to main content
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