Sentry in Magento 2

technische Store-Observability mit dem Modul Kowal_Sentry

12 Minuten, 0 Sekunden

Sentry in Magento 2

Sentry in Magento 2: technische Store-Observability mit dem Modul Kowal_Sentry

Was Sentry ist und wofür es in der Praxis dient

Sentry wird meist mit Error Tracking verbunden, ist in der Praxis aber eine Observability-Plattform, die mehrere Ebenen der Anwendungsdiagnostik verbindet:

  • Reporting von Exceptions und Runtime-Fehlern,
  • Performance-Tracing und Abhängigkeiten zwischen Operationen,
  • Breadcrumbs, die die Abfolge von Aktionen vor einem Ausfall zeigen,
  • Session Replay auf Browser-Seite,
  • User Feedback vom Endnutzer,
  • Monitoring periodischer Prozesse wie Cron,
  • Release Tracking und die Verknüpfung von Fehlern mit einem konkreten Deployment.

In einem gut implementierten Projekt ist Sentry nicht nur ein Ort, an dem ein Stack Trace landet. Es ist ein Werkzeug, mit dem sich Fragen beantworten lassen wie:

  • was genau kaputtgegangen ist,
  • wo das Problem aufgetreten ist: Backend, Frontend, Checkout, Cron, Integration,
  • seit wann das Problem besteht und mit welchem Release es verknüpft ist,
  • ob der Fehler alle Nutzer, einen bestimmten Shop, eine Zahlungsart oder einen Prozess betrifft,
  • wie der Request-Kontext aussah und was direkt vor dem Fehler passiert ist.

Das ist besonders wichtig in Magento, wo ein Ausfall selten eine isolierte Exception in nur einem Controller ist. Häufig betrifft er den gesamten Ablauf: Storefront, AJAX, Checkout, Payment Provider, einen Cron zur Datensynchronisierung und die spätere Auftragsverarbeitung.

Warum Sentry in Magento-Projekten besonders nützlich ist

Magento 2 ist eine umfangreiche, mehrschichtige und stark integrierte Plattform. Ein typischer Shop arbeitet gleichzeitig als:

  • PHP-Backend-Anwendung,
  • Frontend-Anwendung mit viel JavaScript,
  • Integrationssystem für ERP, PIM, WMS, OMS, Payment Gateways und Versanddienstleister,
  • Multi-Store-Umgebung mit unterschiedlichen Scopes und Konfigurationen pro Website oder Store View,
  • Plattform für kritische Verkaufsprozesse, bei der ein Problem im Checkout oder Cron direkte Auswirkungen auf den Umsatz hat.

In der Praxis bedeutet das: Ein normales Dateilog reicht nicht aus. Ein reiner PHP-Stack-Trace reicht ebenfalls nicht aus. Für die Diagnose wird ein breiteres Beobachtungsmodell benötigt:

  • Backend-Exceptions mit Business-Kontext,
  • JavaScript-Fehler aus einer echten Nutzersitzung,
  • Tracing von Requests und HTTP-Abhängigkeiten,
  • Cron- und CLI-Monitoring,
  • Korrelation mit dem Release nach dem Deployment,
  • Sanitizing von Daten, damit Observability nicht mit Sicherheit kollidiert.

Genau in diesem Bereich passt Sentry gut zu Magento, sofern die Integration bewusst umgesetzt wird und nicht nur als einfacher Wrapper um captureException().

Wie Sentry in Magento 2 eingesetzt werden kann

1. Monitoring von PHP-Backend-Fehlern

Das offensichtlichste Szenario ist das Reporting von PHP-Exceptions aus Storefront-, Admin-, API-, Cron- und CLI-Requests. In Magento liefert das schnellen Zugriff auf:

  • den Stack Trace,
  • Environment und Release,
  • Route Name und Full Action Name,
  • den Store-View-Kontext,
  • verknüpfte Daten zu Kunde, Quote, Bestellung oder Produkt, falls die Integration sie anhängt.

So lässt sich nicht nur sehen, dass ein Fehler aufgetreten ist, sondern auch unterscheiden, ob es sich um ein Checkout-Problem, ein Integrationsproblem oder einen Fehler im Adminpanel handelt.

2. Monitoring des JavaScript-Frontends

Viele kritische Ausfälle in Magento erscheinen nicht in PHP, sondern im Browser:

  • ein RequireJS-Fehler,
  • ein Problem mit einer Knockout-Komponente,
  • fehlgeschlagene XHRs im Checkout,
  • eine unbehandelte Promise rejection,
  • ein Fehler in einem Custom-Widget auf der PDP oder im Warenkorb.

Das Sentry Browser SDK kann dies zusammen mit Breadcrumbs, Netzwerk-Requests, Seiten-URL, Environment und Release erfassen. In der Praxis ergibt das ein deutlich besseres Bild davon, was der Nutzer tatsächlich sieht.

3. Performance Monitoring und Tracing

Sentry kann Transactions und Spans sammeln, sodass sich analysieren lassen:

  • Laufzeit von HTTP-Requests,
  • langsame CLI-Kommandos,
  • lange oder instabile Cronjobs,
  • externe HTTP-Aufrufe aus dem Backend,
  • AJAX- und Fetch-Aufrufe im Browser.

Das ersetzt kein vollständiges APM auf Infrastrukturebene, ist in Magento-Projekten diagnostisch aber sehr wertvoll, weil es Performance mit Anwendungskontext und Release verbindet.

4. Checkout-Monitoring

Der Checkout ist technisch der wichtigste Bereich eines Shops. Genau hier kosten Fehler am meisten. Sentry lässt sich nutzen für:

  • das Erfassen von Fehlern in Checkout-Schritten,
  • das Tagging von Zahlungs- und Versandart,
  • Breadcrumbs für AJAX-Aufrufe aus dem Checkout,
  • die Analyse von Problemen mit placeOrder,
  • Session Replay für Sitzungen, die mit einem Fehler enden.

Das verkürzt direkt die Diagnosezeit bei Problemen, die sich auf die Conversion auswirken.

5. Cron Monitoring und Check-ins

Magento stützt sich stark auf Cron. Darüber laufen viele Prozesse, die der Nutzer nicht direkt sieht:

  • Exporte und Importe,
  • Synchronisationen mit externen Systemen,
  • Generierung von Alerts,
  • Datenbereinigung,
  • Indexierungs- und Wartungsaufgaben.

Sentry ermöglicht das Monitoring von Cron-Check-ins, ihrer Laufzeit und ihres Status. So lässt sich schnell erkennen, dass ein Job nicht mehr läuft, zu lange braucht oder mit einem Fehler endet.

6. Release Tracking und Source Maps

Einer der größten Werte von Sentry ist die Verknüpfung von Fehlern mit einem konkreten Deployment. Wenn das Release für Backend, Frontend und Source Maps konsistent gesetzt ist, kann das Team:

  • einen alten Fehler von einer Regression nach dem letzten Deploy unterscheiden,
  • den Umfang der Änderungen schneller eingrenzen,
  • Stack Traces aus Frontend-Assets korrekt symbolisieren,
  • den Einfluss eines konkreten Releases auf die Stabilität des Shops bewerten.

In Magento-Projekten ist das besonders wichtig, weil ein Deployment oft gleichzeitig Backend, Static Content und Integrationen umfasst.

Was das Modul Kowal_Sentry ist

Kowal_Sentry ist ein produktives Magento-2-Modul, das den Shop im Backend und Frontend mit Sentry integriert. Es wurde als Integrationsschicht im Einklang mit der Magento-Architektur entwickelt:

Das Modul ist hier verfugbar: Kowal_Sentry for Magento 2.

  • ohne Änderungen am Core,
  • unter Verwendung von Dependency Injection,
  • mit Plugins um zentrale Einstiegspunkte der Anwendung,
  • mit Konfiguration über Stores -> Configuration,
  • mit Trennung von Backend und Frontend,
  • mit starkem Fokus auf Datensicherheit.

Es ist kein einzelner Helper zum Senden einer Exception. Es ist ein Bündel von Mechanismen, die PHP SDK, Browser SDK, Release-Strategie, Context Provider, Sanitizing und Monitoring von Magento-Prozessen zusammenführen.

Wie die Integration in unserem Modul genau funktioniert

Bootstrap des PHP-Backends

Das Modul initialisiert das PHP SDK einmal pro Request oder Prozess. Beim Bootstrap setzt es unter anderem:

  • dsn,
  • environment,
  • release,
  • sample_rate,
  • traces_sample_rate,
  • profiles_sample_rate,
  • enable_logs,
  • send_default_pii,
  • Hooks vom Typ before_send,
  • Hooks zum Sanitizing von Breadcrumbs, Transactions, Check-ins, Logs und Metrics.

Das ist wichtig, weil bereits am Einstiegspunkt festgelegt wird, was an Sentry gesendet werden darf und was herausgefiltert oder redigiert werden soll.

Transactions für HTTP-Requests

Das Plugin um Magento\Framework\App\Http kapselt den Request in eine Transaction vom Typ http.server. Die Transaction wird anhand des Magento-Requests benannt und erhält Tags und Daten wie:

  • route_name,
  • full_action_name,
  • Request-Pfad,
  • HTTP-Methode,
  • area_code.

Wenn der Request mit einer Exception endet, meldet das Modul sie an Sentry und schließt die Transaction mit Fehlerstatus.

CLI-Monitoring

Das Plugin um Magento\Framework\Console\Cli startet Transactions vom Typ cli.command für bin/magento-Kommandos. Das schafft Observability für:

  • Reindexierungen,
  • Importe,
  • manuell gestartete Aufgaben,
  • eigene Integrationskommandos.

In der Praxis ist das auf Staging und Produktion sehr nützlich, wo CLI-Probleme nicht immer im Standard-Monitoring der Anwendung sichtbar sind.

Cron-Monitoring und Check-ins

Das Plugin um Magento\Cron\Model\Observer startet eine cron.job-Transaction, meldet die Laufzeit des Jobs und sendet Check-ins an Sentry. Dadurch kann man:

  • alle Crons oder nur ausgewählte job_code-Werte überwachen,
  • ein Timeout pro Job setzen,
  • eine maximal erwartete Laufzeit festlegen,
  • konsistente Monitornamen über ein slug prefix aufbauen,
  • den Monitor optional beim ersten Check-in automatisch registrieren.

Das ist einer der stärkeren Teile der Integration, weil hier technisches Sentry-Monitoring mit dem realen Arbeitsmodell von Magento verbunden wird.

Checkout-Instrumentierung

Das Plugin um Magento\Quote\Model\QuoteManagement::placeOrder() fügt Breadcrumbs hinzu und meldet Exceptions im Zusammenhang mit der Finalisierung der Bestellung. Dadurch kann das Event zusätzlichen Kontext enthalten, zum Beispiel:

  • cart_id,
  • payment_method,
  • Informationen, die für eine schnellere Diagnose von Checkout-Ausfällen nötig sind.

Auf Frontend-Seite kann das Modul zusätzlich Checkout-Breadcrumbs und AJAX-Fehler verfolgen, was zusammen ein stimmigeres Bild des Bestellablaufs ergibt.

Spans und Breadcrumbs für HTTP-Aufrufe über Curl-Client

Das Plugin um Magento\Framework\HTTP\Client\Curl fügt einen Span http.client für Aufrufe von GET, POST, PUT und DELETE hinzu. Erfasst werden unter anderem:

  • URL,
  • Methode,
  • Host,
  • Response-Status,
  • der zum Aufruf passende Breadcrumb.

Das ist hilfreich bei der Diagnose von Integrationen mit externen APIs, bei denen der Fehler nicht aus Magento selbst kommt, sondern von Antwortzeiten, Autorisierungsproblemen oder ungültigen Payloads auf Partnerseite.

Browser SDK für Storefront und Admin

Auf Browser-Seite lädt das Modul das Browser SDK dynamisch über Magento und RequireJS. Die Initialisierung umfasst:

  • dsn,
  • environment,
  • release,
  • tracesSampleRate,
  • Replay,
  • User Feedback,
  • tracePropagationTargets,
  • beforeSend mit Event-Sanitizing.

Zusätzlich:

  • hängt sich das Modul in RequireJS-Fehler ein,
  • ergänzt AJAX-Breadcrumbs,
  • setzt Magento-Tags und -Kontexte,
  • initialisiert die Checkout-Instrumentierung nur auf checkout_index_index,
  • kann im Storefront und optional im Admin laufen.

Release-Strategie

Unser Modul unterstützt vier Release-Strategien:

  • manual,
  • env,
  • file,
  • generated.

In der Praxis bedeutet das, dass die Integration sowohl zu einem einfachen manuellen Deployment als auch zu reifem CI/CD passt. Zusätzlich unterstützt das Modul Umgebungsvariablen wie:

  • KOWAL_SENTRY_RELEASE,
  • SENTRY_RELEASE,
  • RELEASE_NAME,
  • GIT_COMMIT.

Wenn das Release nicht von außen geliefert wird, kann das Modul es anhand der Magento-Version, der Modulversion und des kurzen Commit-Hashes generieren.

Sanitizing und Datenschutz

Eines der wichtigsten Elemente der Integration ist der Event-Sanitizer. In unserem Modul umfasst das Sanitizing:

  • Request-Header,
  • Cookies,
  • POST-Body,
  • Query-Parameter,
  • Kontexte und extra,
  • Tags,
  • user,
  • Breadcrumbs,
  • Logs,
  • Metrics.

Je nach Konfiguration kann das Modul:

  • Authorization blockieren,
  • Cookies blockieren,
  • Request-Bodies entfernen,
  • Kundendaten maskieren,
  • IP-Adressen anonymisieren,
  • zusätzliche sensible Schlüssel wie token, api_key, customer_email redigieren.

Im E-Commerce ist das kein Zusatz. Es ist eine Voraussetzung für eine korrekte Integration.

Umfang der Modulkonfiguration

Die Konfiguration ist im Magento-Backend verfügbar:

Stores -> Configuration -> Kowal -> Sentry

Der Einstellungsumfang wurde bewusst in Bereiche aufgeteilt, die verschiedenen Aspekten der Observability entsprechen.

1. General

Der Basisbereich steuert die Aktivierung des Moduls und gemeinsame Parameter:

  • globales Aktivieren oder Deaktivieren des Moduls,
  • Environment,
  • Release Strategy,
  • Release Name Override,
  • Project Name,
  • Debug Mode,
  • Test-CLI-Kommandos.

Dieser Bereich legt das Fundament der Diagnostik. Ohne korrektes environment und release sind Daten in Sentry weniger wertvoll, weil Umgebungen und Deployments schwerer zu unterscheiden sind.

2. Backend SDK

Hier wird das Monitoring auf PHP-Seite konfiguriert:

  • Backend DSN,
  • Error Sample Rate,
  • Trace Sample Rate,
  • Profile Sample Rate,
  • Enable Logs,
  • Enable Metrics API,
  • Enable Cron Monitoring,
  • Enable CLI Monitoring,
  • Enable Adminhtml Monitoring,
  • Enable API Monitoring.

Genau dieser Bereich entscheidet darüber, ob der Shop Backend-Exceptions und Tracing meldet und wie breit der Beobachtungsbereich für Prozesse außerhalb des Storefronts ist.

Wichtig ist, dass Backend-Metriken in aktuellem sentry/sentry 4.24.x als auslaufend oder no-op behandelt werden. Das Feld Enable Metrics API sollte daher als Kompatibilitätsfassade des Moduls und nicht als vollständige Backend-Metrics-Pipeline verstanden werden.

3. Frontend SDK

Der Frontend-Bereich ist für das Browser SDK zuständig:

  • Frontend DSN,
  • Enable Storefront JS,
  • Enable Admin JS,
  • JS Trace Sample Rate,
  • JS Replay Session Sample Rate,
  • JS Replay On Error Sample Rate,
  • Enable Session Replay,
  • Enable User Feedback Widget,
  • Enable Checkout Instrumentation,
  • Enable Ajax Instrumentation,
  • Browser SDK CDN URL.

Diese Trennung ist sehr wichtig. In vielen Magento-Projekten unterscheiden sich die Observability-Anforderungen von Storefront und Admin, deshalb erlaubt das Modul deren getrennte Steuerung.

4. Privacy / Security

Dieser Bereich definiert die Datensicherheitsrichtlinie:

  • Send Default PII,
  • Anonymize IP,
  • Mask Customer Data,
  • Mask Checkout Fields,
  • Mask Payment Fields,
  • Block Authorization Headers,
  • Block Cookies,
  • Block POST Bodies,
  • Redact Query Params,
  • Additional Redacted Keys,
  • Replay Mask Selectors,
  • Replay Block Selectors,
  • Allowed Domains for Replay Network Details.

Das ist ein kritischer Bereich in jeder produktiven Implementierung. Zu liberale Observability-Einstellungen können dazu führen, dass Daten an Sentry gesendet werden, die dort niemals landen sollten.

5. Filtering

Der Filterbereich hilft, Rauschen zu begrenzen:

  • Regexe zum Ignorieren von Exceptions,
  • Regexe zum Ignorieren von URLs,
  • ignorierte Transactions,
  • Ignorieren von Bots,
  • Ignorieren von Health Checks,
  • Ignorieren eines Teils des Admin-Traffics,
  • Ignorieren eines Teils von Fehlern statischer Assets.

In einem gut gepflegten Projekt ist Filtering nicht optional. Ohne diesen Bereich verliert das Team in Sentry sehr schnell die Signalqualität.

6. Context

Hier definieren wir, wie viel Magento-Business-Kontext an Events angehängt wird:

  • Store-Kontext,
  • Website-Kontext,
  • Kundenkontext,
  • Quote-Kontext,
  • Warenkorbsummen,
  • Bestellkontext,
  • Produktkontext,
  • Kategorienkontext,
  • Zahlungs- und Versandart,
  • Modulversion,
  • Magento-Version,
  • Deployment-Metadaten.

Dieser Bereich ist besonders wertvoll in Projekten mit komplexem Checkout und vielen Integrationen, weil sich damit viel schneller beantworten lässt, wen und was ein Problem betrifft.

7. Source Maps / Release

Der Bereich für Release und Source Maps ordnet die Daten, die für den Frontend-Release-Workflow nötig sind:

  • Flag für die Nutzung von Source Maps,
  • Upload-Modus für Source Maps,
  • Assets Base URL,
  • Release Dist,
  • Organization,
  • Project Slug,
  • Release File Path.

Das Modul selbst lädt Source Maps nicht während der Magento-Runtime hoch. Und das ist gut so. Das sollte die CI/CD-Pipeline übernehmen, zum Beispiel über sentry-cli.

8. User Feedback

Der Feedback-Bereich erlaubt die Steuerung des Widgets im Browser:

  • Widget-Theme,
  • Sprache,
  • automatisches Öffnen bei ausgewählten Fehlern,
  • Präsenz auf der Success Page,
  • Präsenz auf der Contact Page,
  • Trigger im Footer,
  • eigener Trigger-Selektor.

Diese Funktion ist dort nützlich, wo das Team schneller Signale von Endnutzern sammeln möchte, ohne einen separaten technischen Meldeweg zu bauen.

9. Cron Monitoring

Der Cron-Bereich strukturiert das Monitoring von Magento-Jobs:

  • automatische Registrierung von Monitoren,
  • Liste überwachter job_code-Werte,
  • Timeout-Schwelle pro Job,
  • maximale Laufzeit pro Job,
  • Präfix für Monitor-Slugs.

Das ist wichtig, weil in der Praxis nicht alle Cronjobs gleich kritisch sind. Das Modul erlaubt, das Monitoring auf Prozesse zu konzentrieren, die echten Einfluss auf Umsatz, Integrationen und die Betriebsfähigkeit des Shops haben.

Wie ein sinnvoller Implementierungsszenario aussieht

In der Praxis sieht der empfohlene Prozess so aus:

  1. Backend-Monitoring mit restriktiver Datenschutzrichtlinie starten.
  2. Frontend-Monitoring für das Storefront hinzufügen.
  3. Tracing mit moderater Sample Rate aktivieren.
  4. Cron-Monitoring für die wichtigsten Jobs einschalten.
  5. Eine zum Deployment passende Release-Strategie konfigurieren.
  6. Source Maps in CI/CD ergänzen.
  7. Erst danach Replay und Feedback erweitern.

Diese Reihenfolge ist sinnvoll, weil so zunächst ein stabiles und sicheres diagnostisches Signal aufgebaut wird und erst danach der Detaillierungsgrad der Daten steigt.

Was diese Integration dem technischen Team gibt

Aus Sicht des Wartungsteams liefert ein gut konfiguriertes Kowal_Sentry einen sehr konkreten Wert:

  • schnellere Erkennung von Ausfällen nach Deployments,
  • kürzere Diagnosezeit bei Checkout-Fehlern,
  • bessere Sichtbarkeit von Problemen mit HTTP-Integrationen,
  • Monitoring von Cron- und CLI-Prozessen,
  • konsistenten Backend- und Frontend-Kontext,
  • mehr Kontrolle über die Qualität der Daten, die an ein externes Tool gesendet werden.

In Magento-Projekten bedeutet das meist weniger Zeit für das manuelle Nachstellen eines Fehlers und einen schnelleren Weg vom Symptom zur Ursache.

Einschränkungen, die man kennen sollte

Keine Observability-Integration ist völlig voraussetzungslos. Bei unserem Modul sollte man einige Dinge im Blick behalten:

  • Backend-Metriken im aktuellen Sentry-PHP-SDK sollten nicht als vollwertige Metrics-Pipeline betrachtet werden,
  • User Feedback ist in Sentry teilweise als Beta oder experimentell gekennzeichnet,
  • Replay sollte vorsichtig und immer mit starkem Masking eingeführt werden,
  • zu breites Sampling in Produktion erhöht Datenvolumen und Kosten sehr schnell.

Diese Einschränkungen disqualifizieren die Lösung nicht. Sie erfordern lediglich eine bewusste Konfiguration.

Zusammenfassung

Sentry in Magento 2 ergibt dann Sinn, wenn es als vollständige Observability-Schicht implementiert wird und nicht nur als einfacher Mechanismus zum Senden von Exceptions. Genau dafür ist Kowal_Sentry da. Es verbindet PHP-Backend, JavaScript-Frontend, Tracing, Checkout, Cron-Monitoring, Release-Strategie und Datensanitizing in einem konsistenten Magento-Modul.

Dadurch erhält das technische Team ein reales Werkzeug für Wartung und Weiterentwicklung des Shops: mit besserer Sichtbarkeit von Fehlern, schnellerer Diagnose von Regressionen und mehr Kontrolle über die Stabilität des Verkaufsprozesses.

Quellen

  • Sentry for PHP: https://docs.sentry.io/platforms/php/
  • Sentry for JavaScript Browser: https://docs.sentry.io/platforms/javascript/guides/browser/
  • Sentry Session Replay: https://docs.sentry.io/platforms/javascript/session-replay/
  • Sentry User Feedback: https://docs.sentry.io/platforms/javascript/user-feedback/
  • Sentry Crons for PHP: https://docs.sentry.io/platforms/php/crons/
  • Sentry Environments and configuration: https://docs.sentry.io/platforms/javascript/configuration/environments/

Vorherige Nächste