Such-Debugging in Magento: eine systematische Methodik

1. Warum Such-Debugging ohne Methodik scheitert

"Die Suche findet das Produkt nicht" ist eine der haeufigsten und gleichzeitig am schwersten zu greifenden Supportmeldungen in einem Magento-Projekt. Ohne systematisches Such-Debugging beginnt die Fehlersuche meist im Frontend: Entwickler tippen denselben Suchbegriff mehrfach ein, aendern Filter, pruefen die Produktsichtbarkeit im Admin, und irgendwann findet sich zufaellig eine Erklaerung. Dieser Ansatz ist zeitintensiv und liefert keine belastbare Diagnose, weil er nie wirklich zeigt, was Magento tatsaechlich an Elasticsearch geschickt hat.

Der Kern des Problems ist eine unklare Schichtentrennung. Eine Magento-Suche durchlaeuft mehrere Schichten: die PHP-seitige Query-Erstellung, die Uebertragung an Elasticsearch, die Analyse und Bewertung im Cluster, und schliesslich die Aufbereitung der Ergebnisse fuer das Frontend. Ein Fehler kann in jeder dieser Schichten entstehen, aber ohne eine Methodik, die diese Schichten sauber trennt, wird jede Fehlerursache zur Vermutung. Systematisches Such-Debugging loest dieses Problem, indem es die Magento-Ebene und die Elasticsearch-Ebene unabhaengig voneinander testbar macht.

Dieser Artikel stellt eine wiederholbare Methodik vor: Debug-Logging aktivieren, die reale Query extrahieren, sie isoliert gegen Elasticsearch ausfuehren und anhand des Ergebnisses entscheiden, in welcher Schicht das eigentliche Problem liegt. Diese Methodik funktioniert unabhaengig davon, ob es um fehlende Treffer, falsche Relevanz-Sortierung oder unerwartete Zero-Result-Seiten geht.

2. Debug-Logging in Magento aktivieren

Der erste Schritt jedes gruendlichen Such-Debuggings ist, Magento dazu zu bringen, die tatsaechlich gesendete Query sichtbar zu machen. Unter Stores > Configuration > Catalog > Catalog Search laesst sich im Bereich der Elasticsearch-Konfiguration die Option "Enable Elasticsearch Debug Logging" aktivieren. Ist diese Option gesetzt, schreibt Magento fuer jede an Elasticsearch gesendete Anfrage einen vollstaendigen Log-Eintrag inklusive Request-Body und Response nach var/log/es_queries.log.

Diese Einstellung sollte in Produktionsumgebungen nur temporaer aktiviert werden, weil sie bei hohem Suchaufkommen spuerbare I/O-Last erzeugt und potenziell sensible Suchbegriffe protokolliert. Fuer gezieltes Such-Debugging reicht es, das Debug-Logging kurz zu aktivieren, den problematischen Suchvorgang im Frontend auszufuehren, und die Option danach sofort wieder zu deaktivieren. In Staging-Umgebungen kann die Option dauerhaft aktiv bleiben, ohne Betriebsrisiko.

# Enable Elasticsearch debug logging via CLI (store-scoped config path)
bin/magento config:set catalog/search/engine elasticsearch7
bin/magento config:set catalog/search/elasticsearch7_server_hostname localhost
bin/magento config:set dev/query_logging/enabled 1

# Reproduce the problematic search in the storefront now

# Tail the query log while the search runs
bin/log es_queries.log

# Disable again once the query has been captured
bin/magento config:set dev/query_logging/enabled 0

3. Die echte Query aus dem Log extrahieren

Das Log es_queries.log enthaelt fuer jede Suchanfrage einen Block mit der vollstaendigen JSON-Query, so wie sie an den _search-Endpunkt des jeweiligen Store-Index gesendet wurde. Diese Query ist deutlich komplexer als das, was ein Entwickler intuitiv erwarten wuerde: Magento kombiniert eine bool-Query mit must- und should-Klauseln fuer die Fulltext-Suche, Filtern fuer Sichtbarkeit und Store, sowie haeufig einer function_score-Komponente fuer die Relevanz-Gewichtung von Attributen wie Name gegenueber Beschreibung.

Fuer effizientes Such-Debugging lohnt es sich, die extrahierte Query in ein separates JSON-File zu kopieren und dort zu formatieren, statt sie direkt aus dem oft unformatierten Logtext zu lesen. Ein haeufiger Fehler an dieser Stelle: Entwickler kopieren nur einen Teil der Query, etwa ohne die _source-Filterung oder ohne die Sortierparameter, und wundern sich dann, warum der isolierte Test ein anderes Ergebnis liefert als das Frontend. Die komplette Query, inklusive aller Header-Parameter, ist die Grundvoraussetzung fuer einen validen Replay.

{
  "query": {
    "bool": {
      "must": [
        {
          "bool": {
            "should": [
              { "match": { "name": { "query": "laufschuh", "boost": 3 } } },
              { "match": { "sku": { "query": "laufschuh", "boost": 5 } } },
              { "match": { "description": { "query": "laufschuh", "boost": 1 } } }
            ],
            "minimum_should_match": 1
          }
        }
      ],
      "filter": [
        { "term": { "visibility": 4 } },
        { "term": { "store_id": 1 } }
      ]
    }
  },
  "sort": [ { "_score": "desc" } ],
  "size": 24,
  "from": 0
}

4. Die Query direkt gegen Elasticsearch replayen

Sobald die vollstaendige Query vorliegt, laesst sie sich mit curl oder Kibana Dev Tools direkt gegen den Elasticsearch-Cluster ausfuehren, komplett unabhaengig von Magento. Dieser Schritt ist der Kern des Such-Debuggings, weil er die Antwort von Elasticsearch ohne jede Verarbeitung durch die Magento-Applikationsschicht zeigt. Liefert der direkte Replay dieselben, aus Sicht des Nutzers fehlerhaften Ergebnisse wie das Frontend, liegt das Problem mit hoher Wahrscheinlichkeit im Index selbst oder in der Query-Logik. Liefert der Replay dagegen andere, korrekte Ergebnisse, muss der Fehler zwischen Query-Erstellung und Ergebnisdarstellung in der Magento-Applikationsschicht liegen.

Wichtig fuer einen sauberen Replay ist, denselben Index-Alias zu verwenden, den auch Magento fuer den jeweiligen Store nutzt. Store-spezifische Indizes tragen Namen wie magento2_default_catalogsearch_fulltext_1, wobei die abschliessende Zahl die Store-ID ist. Ein Replay gegen den falschen Store-Index fuehrt zu scheinbar widerspruechlichen Ergebnissen, die nichts mit dem eigentlichen Problem zu tun haben, sondern lediglich unterschiedliche Analyzer-Konfigurationen oder Synonymgruppen zwischen Stores widerspiegeln.

# Replay the extracted query directly against the store's Elasticsearch index
curl -s -X POST "localhost:9200/magento2_default_catalogsearch_fulltext_1/_search" \
  -H "Content-Type: application/json" \
  -d @extracted_query.json | jq '.hits.total, .hits.hits[]._source.sku'

# Compare hit count with what the storefront actually shows
# If counts match: the problem is likely in the ES layer (mapping, analyzer, data)
# If counts differ: the problem is likely in the Magento layer (query building, result mapping)

5. Magento-Layer vs. Elasticsearch-Layer isolieren

Die eigentliche Staerke dieser Methodik liegt in der klaren Trennung der Verantwortlichkeiten. Wenn der isolierte Replay dieselben unerwarteten Ergebnisse liefert wie das Frontend, ist die Magento-Applikationsschicht als Fehlerquelle weitgehend ausgeschlossen, und das Such-Debugging kann sich vollstaendig auf Elasticsearch konzentrieren: Mapping pruefen, Analyzer testen, Dokumentinhalte im Index verifizieren. Diese Fokussierung spart enorm viel Zeit, weil sie verhindert, in der PHP-Codebasis nach einem Fehler zu suchen, der dort gar nicht existiert.

Zeigt der Replay dagegen korrekte Ergebnisse, waehrend das Frontend falsche liefert, verlagert sich der Fokus auf die Magento-Seite: Wird die Query korrekt aus dem Response geparst? Greifen zusaetzliche Filter im ViewModel oder Block, die nicht Teil der eigentlichen Elasticsearch-Query sind, etwa eine nachtraegliche Preisfilterung mit einem veralteten Preis-Cache? Wird das Ergebnis durch ein Plugin oder eine Erweiterung nachtraeglich manipuliert? Diese Trennung macht aus einem diffusen "die Suche ist kaputt" ein klar eingegrenztes technisches Problem.

6. Typische Fehlerursachen auf Magento-Seite

Auf Magento-Seite entstehen Suchfehler haeufig durch zusaetzliche, nach der Elasticsearch-Anfrage angewendete Filterlogik. Ein klassisches Beispiel ist eine benutzerdefinierte Preisfilterung, die auf einem separaten, veralteten Preis-Cache basiert und Produkte nachtraeglich ausblendet, obwohl Elasticsearch sie korrekt zurueckgeliefert hat. Ein weiteres haeufiges Muster ist eine fehlerhafte Pagination-Logik, die zwar die richtige Gesamtzahl an Treffern erhaelt, aber beim Rendern der aktuellen Seite falsch offsettet und dadurch Produkte scheinbar verschwinden laesst.

Auch Layout-XML-Konfigurationen koennen zur Fehlerquelle werden: Ein Block, der zusaetzliche Attribute in die Suchergebnis-Anzeige einblendet, kann bei fehlenden Attributdaten eine Exception werfen, die im schlimmsten Fall stillschweigend abgefangen wird und ein leeres Ergebnis vortaeuscht. Solche Faelle sind mit reinem Such-Debugging auf Elasticsearch-Seite nicht zu finden, weshalb die Layer-Trennung aus Abschnitt 5 so entscheidend ist, um die Suche in der richtigen Codebasis zu untersuchen.

7. Typische Fehlerursachen auf Elasticsearch-Seite

Auf Elasticsearch-Seite ist die haeufigste Ursache eine Diskrepanz zwischen dem erwarteten und dem tatsaechlichen Feld-Mapping. Wird ein Attribut nachtraeglich von text auf keyword umgestellt, ohne den Index neu aufzubauen, verhaelt sich die Suche auf diesem Feld inkonsistent, weil alte Dokumente noch mit dem alten Mapping indexiert wurden. Ein weiteres haeufiges Problem sind Analyzer-Diskrepanzen: Wird ein Custom-Analyzer nur fuer Produktnamen, nicht aber fuer Beschreibungen konfiguriert, entstehen fuer denselben Suchbegriff unterschiedliche Trefferquoten je nach durchsuchtem Feld, was fuer Endanwender vollkommen unerklaerlich wirkt.

Auch veraltete Indexdaten sind eine haeufige Ursache: Ein Produkt wurde im Admin geaendert, aber der zugehoerige Elasticsearch-Dokument-Eintrag spiegelt noch den alten Stand wider, weil der Partial Reindex fehlgeschlagen ist oder der Changelog-Eintrag nie erzeugt wurde. Ein direkter GET-Aufruf auf das Dokument ueber seine ID zeigt sofort, ob die im Index gespeicherten Daten mit den aktuellen Produktdaten in der Datenbank uebereinstimmen.

# Fetch the raw indexed document for a specific product by its entity ID
curl -s "localhost:9200/magento2_default_catalogsearch_fulltext_1/_doc/10231?pretty"

# Compare relevant fields against the current database state
bin/mysql magento -e "
  SELECT sku, value AS name
  FROM catalog_product_entity_varchar v
  JOIN eav_attribute a ON a.attribute_id = v.attribute_id AND a.attribute_code = 'name'
  JOIN catalog_product_entity e ON e.entity_id = v.entity_id
  WHERE e.entity_id = 10231;
"
# If name differs between the two outputs, the index entry is stale

8. Werkzeuge fuer Relevanz-Debugging: Validate und Explain

Neben dem reinen Query-Replay bietet Elasticsearch zwei spezialisierte APIs, die Such-Debugging erheblich beschleunigen. Die _validate/query-API mit dem Parameter explain=true prueft, ob eine Query syntaktisch und semantisch gueltig ist, und liefert bei Fehlern eine praezise Fehlermeldung, ohne die Query tatsaechlich auszufuehren. Das ist besonders hilfreich, wenn eine von Magento generierte Query aufgrund einer fehlerhaften Custom-Erweiterung ungueltig wird und im Frontend nur ein generischer Fehler ohne Details erscheint.

Die _explain-API dagegen zeigt fuer ein einzelnes Dokument, wie dessen Relevanz-Score fuer eine gegebene Query zustande gekommen ist, inklusive jedes einzelnen Boost-Faktors und jeder Teilbewertung. Wenn ein Kunde sich beschwert, dass ein irrelevantes Produkt vor einem offensichtlich passenderen Produkt angezeigt wird, liefert die Explain API den exakten Grund: etwa ein zu hoher Boost auf ein Attribut, das im konkreten Fall in die falsche Richtung wirkt. Ohne diese API bliebe die Ursache einer falschen Relevanz-Reihenfolge reine Spekulation.

9. Ein wiederverwendbares Debug-Runbook

Damit Such-Debugging nicht bei jedem neuen Fall improvisiert werden muss, lohnt sich ein dokumentiertes Runbook mit festen Schritten: Debug-Logging aktivieren, Suchvorgang reproduzieren, Query aus dem Log extrahieren, Query gegen den korrekten Store-Index replayen, Ergebnis mit dem Frontend vergleichen, basierend auf dem Vergleich die Layer bestimmen, und je nach Layer mit Mapping-Pruefung oder Codebasis-Analyse fortfahren. Ein solches Runbook reduziert die Einarbeitungszeit fuer neue Teammitglieder erheblich und stellt sicher, dass jeder Suchfehler nach demselben, nachvollziehbaren Schema untersucht wird.

Fuer wiederkehrende Faelle lohnt sich zusaetzlich ein kleines Skript, das die haeufigsten Schritte automatisiert: Debug-Logging per CLI aktivieren, nach einer definierten Wartezeit die letzte Query aus dem Log extrahieren, sie automatisch gegen den passenden Store-Index replayen und Treffer-Anzahl sowie Top-Ergebnisse direkt im Terminal ausgeben. Das verkuerzt die Zeit vom ersten Support-Ticket bis zur ersten belastbaren Diagnose von Stunden auf wenige Minuten.

#!/usr/bin/env bash
# debug-search.sh - minimal automated search debugging runbook
set -euo pipefail

STORE_INDEX="magento2_default_catalogsearch_fulltext_1"

# Step 1: extract the most recent query block from the debug log
last_query=$(tac var/log/es_queries.log | grep -m1 -A 30 '"query"' | tac)

# Step 2: replay it against the correct store index
echo "$last_query" > /tmp/last_query.json
curl -s -X POST "localhost:9200/${STORE_INDEX}/_search" \
  -H "Content-Type: application/json" \
  -d @/tmp/last_query.json > /tmp/replay_result.json

# Step 3: print total hits and top 5 SKUs for quick comparison
jq '.hits.total.value, [.hits.hits[:5][]._source.sku]' /tmp/replay_result.json

10. Zusammenfassung

Erfolgreiches Such-Debugging in Magento beginnt nie im Frontend, sondern beim Mitschnitt der tatsaechlichen Elasticsearch-Query ueber es_queries.log. Diese Query direkt gegen den korrekten Store-Index zu replayen, unabhaengig von der Magento-Applikationsschicht, ist der entscheidende Schritt, um zu bestimmen, ob ein Suchfehler in der PHP-Codebasis oder im Elasticsearch-Index selbst entsteht. Diese Layer-Trennung verwandelt eine diffuse Fehlermeldung in ein klar eingegrenztes technisches Problem.

Zusaetzliche Werkzeuge wie die _validate/query- und _explain-APIs liefern praezise Antworten auf Fragen, die sonst reine Spekulation blieben: Ist eine Query gueltig, und warum hat ein bestimmtes Dokument genau diesen Relevanz-Score erhalten. Wer diese Methodik in einem dokumentierten Runbook festhaelt, reduziert die Zeit vom ersten Suchfehler-Ticket bis zur belastbaren Diagnose drastisch und macht Such-Debugging zu einem wiederholbaren Prozess statt einer Kunstform.

11. FAQ: Such-Debugging in Magento