Diese Seite ist eine maschinelle Übersetzung der englischen Seite, die maßgeblich ist. Englische Seite lesen
Fehlerberichte
Wie der Server dich über seine eigenen Bugs und Fehler informiert, wo du die Berichte auf jeder Plattform liest und wie du sie an einen Error-Tracker schickst. Metriken sagen dir, dass etwas nicht stimmt; ein Fehlerbericht sagt dir, was fehlgeschlagen ist, samt Stack. Die Konfigurationsreferenz listet jede Einstellung auf.
Drei Dinge geschehen mit jedem Bericht, egal was du konfigurierst:
- Eine
error report-Zeile geht mit dem Stack an die Standardfehlerausgabe (Die Logzeile). - Der Bericht wird in der Datenbank in einer Fehlergruppe gezählt. Die Administrationsoberfläche zeigt die Gruppen, und Personen mit der Berechtigung
manage_errorswerden über neue und wiederkehrende benachrichtigt (Fehlergruppen und Benachrichtigungen). - Wenn du
errors_exportersetzt, geht der Bericht außerdem an einen externen Dienst (Berichte an einen Dienst senden).
Nichts verlässt den Server, solange du errors_exporter nicht setzt.
Was gemeldet wird
Abschnitt betitelt „Was gemeldet wird“| Gemeldet | Nicht gemeldet (die Metriken und die anderen Logzeilen decken es ab) |
|---|---|
| Eine Panic in einem HTTP-Handler, einem Job oder einem Hintergrundtask | 4xx-Antworten (fehlerhafte Eingabe, Autorisierung, Ratenbegrenzungen) und der Wartungsmodus |
| Ein Fehler hinter einer 5xx-Antwort der Client-API, der Admin-API, der Anmeldeseiten, von ActivityPub, OAuth oder Medien | Eine Anfrage, deren Client weg war |
Ein Job, der endgültig fehlgeschlagen ist (dead) |
Ein Job-Retry. Er wird gemeldet, wenn ihm die Wiederholungen ausgehen |
| Ein Fehler beim Start: eine ungültige Konfiguration oder eine Datenbank oder ein Adapter, die sich nicht einrichten lassen | Eine fehlgeschlagene Readiness-Prüfung |
| Ein Fehler, den der Web-Client nicht behandelt hat und den der Browser an den Server schickt | Fehler, die andere Server verursachen: Zustellwiederholungen und Aufgaben, abgelehnte Signaturen, fehlgeschlagene Remote-Abrufe |
| Das eigene Rauschen des Browsers: ein verlorenes Netzwerk, Fehler von Browser-Erweiterungen und Chunks, die ein neues Deployment entfernt hat |
Ein Fehler eines externen Dienstes (Mail, Speicher, Zahlungen, Sprache) wird nur gemeldet, wenn er einen Job endgültig scheitern lässt oder eine Anfrage mit 5xx beantworten lässt. Ein vorübergehender Fehler zeigt sich stattdessen in den my.adapter.*-Metriken (Den Server betreiben).
Eine Panic in einem Hintergrundtask beendet den Prozess, nachdem sie gemeldet wurde, damit der Server nie in einem defekten Zustand weiterläuft. Deine Plattform startet ihn neu.
Die Logzeile
Abschnitt betitelt „Die Logzeile“Die Zeile hat msg = error report und level ERROR (severity ist CRITICAL, wenn der Fehler den Prozess beendet).
Ihre Felder und was das Bereinigen mit ihnen macht, stehen unter Den Server betreiben. Kurz gesagt:
my.error.fingerprintist bei jedem Auftreten desselben Fehlers gleich. Suche oder gruppiere danach.my.error.wheresagt, wo er auftrat, zum Beispielclient_api GET /api/v1/statuses/{id}.request_id,job_id,trace_idundspan_idfinden die anderen Zeilen derselben Anfrage oder desselben Jobs.- Die Zeile eines Fehlers einer Anfrage hat
context.httpRequest: die Methode, die Route als URL (/api/v1/statuses/{id}, nie der Pfad, den der Client angefragt hat) und den beantworteten Status. Error Reporting zeigt sie an der Gruppe an und kann danach filtern. messagesteht zuletzt in der Zeile: der Fehlertyp und die Meldung, ein Zeilenumbruch und der Go-Stack.- Der Stack beginnt dort, wo der Fehler herkam, nicht dort, wo er gemeldet wurde: bei einem Datenbankfehler die Server-Funktion, die die Abfrage ausführte. Fehler von verschiedenen Stellen landen daher in verschiedenen Gruppen, in Error Reporting wie im Administrationsbildschirm.
Keine andere Zeile trägt einen Stack.
Google Cloud (Cloud Run)
Abschnitt betitelt „Google Cloud (Cloud Run)“Cloud Error Reporting liest die Zeile ohne jede Einrichtung und listet die Fehler in der Konsole unter Error Reporting auf. Es ist kostenlos; du zahlst nur für Cloud Logging.
- Es gruppiert Fehler nach dem Typ und den obersten Frames des Stacks. Es kann den Fingerprint des Servers nicht übernehmen, daher kann sich eine Gruppe in Error Reporting von einer Gruppe im Administrationsbildschirm unterscheiden.
- Es behält Gruppen 30 Tage lang und benachrichtigt dich über neue Fehler und über erledigte Fehler, die erneut auftreten, höchstens 20 Benachrichtigungen pro Stunde für das Projekt. Richte seinen Benachrichtigungskanal in der Google-Cloud-Konsole ein.
- Um herauszufinden, was um einen Bericht herum geschah, suche in Cloud Logging nach
jsonPayload."request_id"="<id>"oder nach dem Gleichen mittrace_id.
Mit dem OpenTofu-Modul mycroblog-gcp schickt der Abschnitt observability die Berichte standardmäßig hierher (errors = "error-reporting"): Er aktiviert die Error-Reporting-API und lässt errors_exporter auf none.
CloudWatch Logs liest die Zeile als einfaches JSON.
- Schalte die Log-Anomalieerkennung für die Loggruppe ein. Sie markiert ein Zeilenmuster, das sie noch nie gesehen hat, und kann per SNS Alarm schlagen. Sie liest nur die ersten 1.500 Zeichen einer Zeile, weshalb
messagedas letzte Feld ist. Einen Zustand „erledigt“ führt sie nicht. - Um Berichte zu zählen, lege einen Metrikfilter an, etwa
{ $.msg = "error report" }. Verwende keine Dimension, die ausmy.error.fingerprintstammt: Jeder Wert einer Dimension wird als eigene Metrik abgerechnet.my.error.sourceundmy.error.kindsind unbedenklich. - Den Kontext findest du mit Logs Insights:
filter `request_id` = "<id>".
Mit dem OpenTofu-Modul mycroblog-aws hält der Abschnitt observability die Berichte standardmäßig in CloudWatch Logs (errors = "cloudwatch"), mit errors_exporter auf none. Die Log-Anomalieerkennung bleibt ein Schritt von dir.
Selbst gehostet
Abschnitt betitelt „Selbst gehostet“Lies die Zeile aus dem Container-Log: docker compose logs my | jq -c 'select(.msg == "error report")'.
Mit metrics_exporter = prometheus warnt der Alert MyErrorReportsIncreasing (Alerts und Runbook), wenn die Berichte stark ansteigen; der Zähler dahinter ist my.errors.reported.
Für Benachrichtigungen, die keinen externen Dienst brauchen, nutze die Administrationsoberfläche und die Webhooks unten. Für einen Tracker nutze errors_exporter.
Fehlergruppen und Benachrichtigungen
Abschnitt betitelt „Fehlergruppen und Benachrichtigungen“Der Server zählt die Berichte nach Fingerprint in der Datenbank. Er braucht dafür keine Einstellung und keinen zusätzlichen Dienst und schreibt wenig: Der erste Bericht eines Fingerprints wird sofort geschrieben, die folgenden werden im Speicher addiert und einmal pro Minute geschrieben. Ein harter Abbruch des Prozesses kann die Zählungen der letzten Minute verlieren; die Logzeilen gehen auf diese Weise nicht verloren. Zählungen, die älter als 90 Tage sind, werden täglich gelöscht. Wenn die Datenbank der Grund für den Fehler ist, bleibt der Bericht nur in der Logzeile.
Die Administrationsoberfläche
Abschnitt betitelt „Die Administrationsoberfläche“Personen, deren Rolle manage_errors hat (die eingebaute Rolle admin hat es), sehen „Fehler“ im Administrationsmenü (/admin/errors).
- Die Liste zeigt die Gruppen, standardmäßig die offenen, die zuletzt gesehene zuerst. Filtere nach Zustand (offen, erledigt, stummgeschaltet, jeder Zustand) und nach Quelle (der Server, der Web-Client). Jede Zeile zeigt die erste Zeile der Meldung, wo der Fehler aufgetreten ist, die Zählungen der letzten 24 Stunden und 7 Tage, wann er zuletzt gesehen wurde und seinen Zustand.
- Die Seite einer Gruppe beginnt mit dem, was du in ihrem Zustand tun kannst („Als erledigt markieren“ und „Stummschalten“ bei einer offenen Gruppe, „Stummschalten“ bei einer erledigten, „Stummschaltung aufheben“ bei einer stummgeschalteten). Sie zeigt die Fakten der Gruppe (wo, die Meldung, erster und letzter Zeitpunkt und erste und letzte Version, den Fingerprint), ihre Zählungen der letzten 24 Stunden und 7 Tage, das jüngste Auftreten (Zeit, Version, Prozessrolle, die Typen, die Request-ID und die Trace-ID sowie den Stack), die Vorkommen pro Stunde der letzten 90 Tage, das neueste zuerst, und den Verlauf ihrer Zustandsänderungen. Der Fingerprint, die Request-ID, die Trace-ID und der Stack haben eine Schaltfläche „Kopieren“: Füge die IDs in deine Log-Suche ein.
- „Als erledigt markieren“ ist für einen Fehler gedacht, den du behoben hast. Tritt er in einer anderen Version des Servers erneut auf, öffnet sich die Gruppe wieder und benachrichtigt erneut. Derselbe Fehler in der Version, die erledigt wurde, wird nur gezählt, damit die letzten Anfragen der alten Version ihn nicht wieder öffnen.
- „Stummschalten“ zählt weiter, sendet aber keine Benachrichtigung und kein Webhook-Ereignis. „Stummschaltung aufheben“ öffnet die Gruppe wieder.
Dieselben Aktionen sind als GET /api/v1/admin/error_groups und POST /api/v1/admin/error_groups/{id}/resolve (/mute, /unmute) verfügbar.
Benachrichtigungen und Webhooks
Abschnitt betitelt „Benachrichtigungen und Webhooks“- Personen mit
manage_errorserhalten die Benachrichtigungadmin_error_groupfür eine neue Fehlergruppe und für ein erneutes Auftreten. Für den ganzen Server kommen höchstens 10 pro Stunde an; der Rest der Stunde wird in einer Benachrichtigung zusammengefasst, die sagt, dass weitere Fehler gemeldet wurden. Sie können sie auch per E-Mail erhalten (Moderation). - Die Webhook-Ereignisse
error_group.createdunderror_group.regressedtragen dieselben Gruppen, du kannst sie also an Slack, Discord oder ein Automatisierungswerkzeug schicken (Server-Webhooks, Webhook-Referenz). Der Webhook brauchtmanage_webhooks, und die Ereignisse brauchenmanage_errors. - Eine stummgeschaltete Gruppe benachrichtigt nie.
Fehler aus dem Web-Client
Abschnitt betitelt „Fehler aus dem Web-Client“Der Web-Client schickt die Fehler, die seine Bildschirme nicht behandelt haben, an POST /api/v1/client_errors auf deinem eigenen Server, sodass kein Dritter sie sieht und sich keine Content-Security-Einstellung ändert. Der Server antwortet auf alles mit 204 und verwirft, was er nicht annimmt: einen Body über 16 KiB, einen Stack ohne eine Datei deines eigenen Web-Clients und mehr als 10 Berichte pro Minute von einer IP-Adresse. Derselbe Fehler wird einmal pro Seitenaufruf gesendet, höchstens 20 pro Seitenaufruf.
Ein Bericht ohne angemeldete Sitzung wird gezählt und geloggt, benachrichtigt aber von sich aus niemanden, damit ein anonymes Skript dein Postfach nicht füllen kann. Die Gruppe benachrichtigt, wenn auch der Browser einer angemeldeten Person sie meldet.
Die Stacks stammen aus dem minifizierten Build und werden nicht in den Quellcode zurückübersetzt; lies also zuerst die Route und die Meldung. Das Release ist die Version des Servers, der die Seite ausgeliefert hat. Eine Seite, die offline oder nach 3 Sekunden ohne Antwort geöffnet wurde, stammt aus der Kopie des Browsers, die die Version nennt, aus der der Browser den Web-Client gespeichert hat: eine ältere Version mit demselben Web-Client.
UX-Messungen
Abschnitt betitelt „UX-Messungen“Der Web-Client schickt Stichproben dazu, wie schnell er antwortet, an POST /api/v1/client_measurements auf deinem eigenen Server, auf dieselbe Weise wie seine Fehler: wie lange ein Bildschirm braucht, um zu erscheinen (LCP) und auf einen Druck zu antworten (INP), pro Route, seine langen Frames, jede Navigation nach Art, jede Aktion nach ihrer ID (post.reply) sowie Laufzeit, Jitter und Paketverlust von Sprachanrufen. Eine Stichprobe nennt nur die Route, die Art, die Aktion oder den Transport des Anrufs; sie trägt kein Konto, keine Adresse und keine URL. Der Server antwortet auf alles mit 204 und nimmt höchstens 10 Anfragen pro Minute von einer IP-Adresse an.
Der Server zählt die Stichproben stundenweise in der Datenbank, einmal pro Minute geschrieben, und löscht sie nach 30 Tagen. GET /api/v1/admin/ux_measurements (manage_errors) summiert die letzten 24 Stunden oder hours bis zu 720, mit dem 75. Perzentil jedes Namens; die Metriken my.ux.duration und my.ux.call.packet_loss exportieren dieselben Stichproben (Metriken). Jede Art behält in einem Prozess ihre ersten 200 Namen; die späteren zählen als other.
Sie ist standardmäßig aus; die Instanzeinstellung ux_measurement schaltet sie ein, und solange sie aus ist, nimmt der Server keine Stichprobe (Instanzeinstellungen). Solange sie an ist, sendet nur ein Teil der Browsersitzungen Stichproben, 10 %, sofern ux_measurement_share keinen anderen Wert setzt, jede Sitzung einmal beim Start des Web-Clients ausgelost.
Personen, deren Rolle manage_errors hat, sehen „UX-Messungen“ im Administrationsmenü (/admin/ux-measurements). Wähle die letzten 24 Stunden, 7 Tage oder 30 Tage; jede Metrik mit Stichproben hat eine Tabelle ihrer Namen mit ihren Stichproben und dem 75. Perzentil sowie, für LCP und INP, dem Anteil der guten und der schlechten Stichproben (innerhalb von 2,5 s und über 4 s bei LCP, innerhalb von 200 ms und über 500 ms bei INP), wobei ein 75. Perzentil über der Schwelle für „gut“ markiert ist. „Den Web-Client messen“ unter den Tabellen ist die Einstellung ux_measurement, die dort nur Personen ändern, deren Rolle auch manage_settings hat, mit einem eigenen „Speichern“.
Berichte an einen Dienst senden
Abschnitt betitelt „Berichte an einen Dienst senden“Setze errors_exporter, um jeden Bericht zusätzlich an einen Error-Tracker zu senden. Die Logzeile und die Gruppen in der Datenbank bleiben eingeschaltet. Ein Bericht wird einmal gesendet und nie wiederholt, und nichts wartet auf den Dienst.
| Wert | Sendet an |
|---|---|
none (Standard) |
Nirgendwohin |
sentry |
Jeden Sentry-kompatiblen Dienst unter errors_sentry_dsn |
otlp |
Einen OpenTelemetry-Collector oder ein Backend, als Log-Records |
errors_environment (Standard production) benennt das Deployment in jedem Bericht, etwa staging.
Beide Exporter senden dieselben bereinigten Felder wie die Logzeile, mit dem Fingerprint und den Trace- und Span-IDs, und nichts über den Host: keinen Hostnamen, keine IP-Adresse, keinen Nutzer, keinen Request-Body, keinen Header und kein Cookie.
Der Server begrenzt, was er sendet, damit der Dienst nicht überflutet wird:
- Derselbe Fingerprint geht höchstens einmal pro Minute und Prozess hinaus, und alle Berichte höchstens 60 pro Minute. Der Rest bleibt im Log und in den Gruppen.
- Bis zu 1.000 Berichte warten auf das Senden. Ein Bericht, der die Queue voll vorfindet, wird verworfen. Wenn der Server stoppt, wartet er bis zu 2 Sekunden, bis die Queue leer ist.
- Wenn der Dienst mit
429antwortet oder um Verlangsamung bittet (Retry-After,X-Sentry-Rate-Limits), hört der Server für diese Dauer auf zu senden. - Der Server folgt nie einer Weiterleitung des Dienstes, damit der DSN-Schlüssel und der Bericht nirgendwo anders hingehen: Eine Weiterleitung zählt als
failed. Verwende den DSN, den der Dienst anzeigt und der selbst auf seinen Intake zeigt.
Beobachte den Zähler my.errors.exported: my.outcome ist success, dropped (über einem Limit, die Queue war voll oder der Dienst bat um Verlangsamung) oder failed (der Dienst war nicht erreichbar oder hat den Bericht abgelehnt) (Den Server betreiben).
Sentry, GlitchTip und Datadog
Abschnitt betitelt „Sentry, GlitchTip und Datadog“MY_ERRORS_EXPORTER=sentryMY_ERRORS_SENTRY_DSN_FILE=/run/secrets/sentry_dsn # or MY_ERRORS_SENTRY_DSN; the DSN is a secretLass bei den OpenTofu-Modulen die Fehler des Abschnitts observability bei den Einstellungen, und das Modul legt das Secret des DSN zum Ausfüllen für dich an, das seine Ausgabe secrets_to_fill auflistet:
observability = { errors = "settings" } settings = { errors_exporter = "sentry" } secrets = ["errors_sentry_dsn"]Der Server spricht das Sentry-Protokoll selbst, es ist also kein Sentry-SDK beteiligt, und es wird keine Umgebungsvariable SENTRY_* gelesen. Er setzt den Fingerprint, damit der Dienst danach gruppiert, und die Tags service (my), my.role, my.error.where und error.fingerprint. Das Release ist die Version des Servers und die Umgebung ist errors_environment.
- Sentry (gehostet oder selbst gehostet): Kopiere den DSN aus den Client-Keys des Projekts.
- GlitchTip: Kopiere den DSN des Projekts. Es ist Open Source und läuft auf einem kleinen Server. Prüfe, welche Alert-Regeln deine Version für neue und wiederkehrende Issues anbietet.
- Datadog Error Tracking: Verwende den Sentry-DSN deiner Datadog-Site,
https://<DD_API_KEY>@sentry-intake.<DD_SITE>/1. Datadog verlangt den Tagservice, den der Server immer setzt. Datadog speichert diese Ereignisse als Logs und gruppiert sie in Error Tracking. Wenn du die Logzeile stattdessen mit einem Agent oder Forwarder an Datadog schickst (Error Tracking for Logs), steht der Stack inmessage; ordne ihn mit einer Log-Pipelineerror.stackzu, sonst erkennt Datadog ihn nicht als Stack. Der Exportersentrybraucht keine solche Zuordnung.
OTLP-Backends
Abschnitt betitelt „OTLP-Backends“MY_ERRORS_EXPORTER=otlpOTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 # or OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20...Jeder Bericht ist ein OpenTelemetry-Log-Record namens exception, mit der Severity ERROR (FATAL, wenn er den Prozess beendet), exception.type, exception.message, exception.stacktrace, my.error.fingerprint, my.error.where, my.error.source, my.error.kind und den Trace- und Span-IDs. Er geht per OTLP/HTTP (Protobuf, gzip) mit derselben Resource wie die Metriken und Traces hinaus.
Ob das Backend diese Records in gruppierte Fehler umwandelt, hängt vom Backend ab: Manche bauen ihre Fehleransichten nur aus Trace-Daten, und Datadog braucht error.stack. Verwende für Sentry, GlitchTip und Datadog sentry. Verwende otlp, wenn du die Records neben deinen anderen Logs haben willst.
Was das Scrubbing garantiert und was nicht
Abschnitt betitelt „Was das Scrubbing garantiert und was nicht“Das Scrubbing läuft einmal, wenn der Bericht erstellt wird; die Logzeile, die Datenbank und jeder Exporter erhalten also nur den bereinigten Text.
- In der Meldung werden URLs, E-Mail-Adressen,
@user@host-Handles, IP-Adressen, UUIDs und ULIDs sowie Zahlen mit 10 oder mehr Ziffern durch<url>,<email>,<acct>,<ip>,<id>und<n>ersetzt, und die Meldung wird auf 1 KiB gekürzt. - Im Stack werden die Werte von Funktionsargumenten durch
(...)ersetzt, und der Stack wird auf 16 KiB gekürzt. Dateipositionen bleiben, relativ zum Quellbaum, sodass die Pfade der Build-Maschine nicht erscheinen. - Kein Bericht hat einen Request-Body, Header, Query, Cookie, eine Konto-ID, einen Nutzernamen, eine IP-Adresse oder einen User-Agent.
Das Scrubbing arbeitet mit Mustern und garantiert deshalb nicht, dass eine Meldung keine personenbezogenen Daten enthält. Ein Name, ein Freitext oder eine Zahl mit weniger als 10 Ziffern, die eine Fehlermeldung zitiert, können bleiben. Das Feld error der gewöhnlichen Zeilen http request und job wird nicht auf diese Weise bereinigt. Behandle die Logs und den Error-Tracker als Orte, die Fragmente von Nutzerinhalten enthalten können, und gib ihnen dieselbe Zugriffskontrolle und Aufbewahrung wie dem Rest deiner Logs. Sobald du errors_exporter setzt, gelten für die Berichte der Standort, die Aufbewahrung und die Zugriffsregeln dieses Dienstes.
Für LLMs und Coding-Agenten:llms.txt,llms-full.txt, llms-small.txt