> ## Documentation Index
> Fetch the complete documentation index at: https://nikita-shkoda.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Debugging
> Compile-time instrumentation and developer-friendly introspection for relations via explain and events.
Related: Compiler, DX
Add compile-time instrumentation and a developer-friendly introspection helper for relations.
* search\_engine.compile: emitted around AST → Typesense params compilation.
* Relation#explain: prints a concise summary of chainers and compiled params without network calls.
## `search_engine.compile`
Emitted by SearchEngine::Compiler.compile for every AST compilation. Payload fields are minimal and redacted-safe:
* collection: Typesense collection name when resolvable, else nil
* klass: model class name when provided, else nil
* node\_count: total AST node count compiled
* duration\_ms: elapsed time in milliseconds (float)
* source: :ast
Subscribe example:
```ruby theme={null}
ActiveSupport::Notifications.subscribe('search_engine.compile') do |*args|
ev = ActiveSupport::Notifications::Event.new(*args)
# ev.payload => { collection:, klass:, node_count:, duration_ms:, source: :ast }
end
```
See also: DX.
## `Relation#explain`
Summarizes the relation state by compiling params locally. No HTTP requests are performed.
* where: humanized filter\_by with AND/OR/IN/NOT IN tokens
* order: joined sort\_by (comma-separated)
* select: include\_fields
* page/per: shows when present (supports page/per and limit/offset fallback)
Usage:
```ruby theme={null}
rel = Book.all.where(active: true).where(author_id: [1,2]).order(updated_at: :desc).page(2).per(20)
puts rel.explain
```
Sample output:
```text theme={null}
SearchEngine::Book Relation
where: active:=true AND author_id NOT IN [1, 2]
order: updated_at:desc
select: id,name
page/per: 2/20
```
Options:
* to: :stdout — also prints the summary to STDOUT (default: return-only)
Caveats:
* Does not include secrets or full query bodies. q is not shown; API keys are never included.
## Compile timeline
```mermaid theme={null}
sequenceDiagram
participant Rel as Relation
participant Comp as Compiler
participant AS as AS::Notifications
Rel->>Comp: compile(AST, klass)
Comp->>AS: instrument("search_engine.compile", payload)
AS-->>Comp: yield
Comp-->>Rel: filter_by string
Rel-->>Dev: explain() summary
```
Backlinks: Home · DX · Compiler