> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Upgrade von AppSignal für Ruby-Gem 3.x auf 4.x
> Ein Leitfaden, der Anwendungen beim Upgrade vom AppSignal für Ruby-Gem 3 auf Version 4 hilft.
AppSignal für Ruby 4.0 ist ein Major-Release, das Unterstützung für mehrere Fehler, änderbare Sample-Daten, Änderungen daran, wie es andere Gems instrumentiert, wie benutzerdefinierte Instrumentierung funktioniert, sowie die Entfernung zuvor veralteter Module einführt. Folgen Sie diesem Leitfaden, um den Upgrade-Prozess reibungsloser zu gestalten.
## Upgrade auf die neueste 3.x-Serie
Bevor Sie auf das AppSignal für Ruby-Gem 4.0 upgraden, upgraden Sie auf das neueste Gem der 3.x-Serie. Diese Version gibt Verfallswarnungen aus und protokolliert sie für Dinge, die in Version 4.x des Ruby-Gems entfernt wurden. Führen Sie die Tests für Ihre App, in die das Gem integriert ist, aus und beheben Sie alle Verfallswarnungen und Fehler, denen Sie begegnen.
Aktualisieren Sie zunächst im `Gemfile` der App die Versionssperre auf `~> 3.0` und führen Sie `bundle update appsignal` in einem Terminal im selben Verzeichnis wie das `Gemfile` aus.
```ruby Ruby theme={null}
# Gemfile
gem "appsignal", "~> 3.0"
```
Führen Sie Ihre Anwendungen aus und beheben Sie alle Verfallswarnungen, die während des Betriebs an STDERR der Anwendung ausgegeben und in `appsignal.log` protokolliert werden.
## Upgrade auf die neueste 4.x-Serie
Nachdem alle Verfallswarnungen mit Version 3 des Ruby-Gems behoben wurden, entfernen Sie die Versionssperre aus dem `Gemfile` und führen Sie `bundle update appsignal` erneut aus, um AppSignal für Ruby auf Version 4 zu aktualisieren.
```ruby Ruby theme={null}
# Gemfile
gem "appsignal"
```
## Änderungen
Nachstehend finden Sie alle nennenswerten Änderungen zwischen der neuesten Ruby-Gem-Version 3 und der neuen Version 4. Bitte gehen Sie sie durch und aktualisieren Sie Ihre Anwendung wie beschrieben.
### Hauptbibliothek
* Die Methode `Appsignal.start_logger` wurde entfernt. Der Logger wird jetzt automatisch bei `Appsignal.start` gestartet. Anwendungen müssen den Aufruf von `Appsignal.start_logger` entfernen.
* Die Konfiguration des AppSignal Ruby-Gems wird eingefroren, nachdem `Appsignal.start` aufgerufen wurde. Die Konfiguration kann nach dem Start des Ruby-Gems nicht mehr geändert werden.
* Die Methode `Appsignal.start` kann nur einmal aufgerufen werden. Nachfolgende Aufrufe werden vom Ruby-Gem ignoriert.
### Konfiguration
* AppSignal startet nicht, wenn das Laden der `config/appsignal.yml`-Datei einen Fehler verursacht. Prüfen Sie die Ausgabe der Anwendung oder die `appsignal.log`-Datei auf Warnungen.
* Konfigurieren Sie AppSignal in Ruby mit dem neuen [`Appsignal.configure`-Helper](/ruby/configuration/load-order#configure-helper). Apps, die das Muster `Appsignal.config = Appsignal::Config.new(...)` verwenden, müssen ihre Apps aktualisieren, um stattdessen diese Methode zu verwenden.
* Die Methode `Appsignal.config =` wurde entfernt. Verwenden Sie stattdessen den [`Appsignal.configure`-Helper](/ruby/configuration/load-order#configure-helper), um AppSignal in Ruby zu konfigurieren.
* Die Option `skip_session_data` wurde entfernt. Verwenden Sie stattdessen die [`send_session_data`-Option](/ruby/configuration/options#option-send_session_data).
* Die Option `debug` wurde entfernt. Verwenden Sie stattdessen die Option [`log_level: debug`](/ruby/configuration/options#option-log_level).
* Die Option `transaction_debug_mode` wurde entfernt. Verwenden Sie stattdessen die Option [`log_level: trace`](/ruby/configuration/options#option-log_level).
* Die Option `working_dir_path` wurde entfernt. Verwenden Sie stattdessen die [`working_directory_path`-Option](/ruby/configuration/options#option-working_directory_path).
### Integrationen
* Die Middleware `Appsignal::Rack::EventHandler` wurde hinzugefügt. Sie fügt das Tag `response_status` zu Samples hinzu und verfolgt eine `response_status`-Metrik mit dem HTTP-Statuscode der Antwort der Anfrage. Weitere Informationen finden Sie in [unserer Rack-Integrationsdokumentation](/ruby/integrations/rack).
* Die Middleware `Appsignal::Rack::InstrumentationMiddleware` ersetzt die Middleware `Appsignal::Rack::GenericInstrumentation`. Diese neue Middleware setzt die Action standardmäßig nicht auf "unknown". Es ist erforderlich, den Action-Namen in jedem App-Endpunkt mit `Appsignal.set_action` zu setzen, wenn nur die `InstrumentationMiddleware` verwendet wird. Weitere Informationen finden Sie in [unserer Rack-Integrationsdokumentation](/ruby/integrations/rack).
* `Appsignal::Grape::Middleware` wurde in `Appsignal::Rack::GrapeMiddleware` umbenannt.
* `Appsignal::Rack::StreamingListener` wurde durch `Appsignal::Rack::InstrumentationMiddleware` ersetzt.
* `Appsignal::Hooks::SidekiqPlugin` wurde ersatzlos entfernt.
* Die Integrationen für Grape, Hanami, Padrino und Sinatra verwenden jetzt den `Appsignal.load`-Mechanismus, um sich in diese Bibliotheken zu integrieren. Bitte folgen Sie den Installationsanleitungen für diese Bibliotheken, um auf den neuen Lademechanismus umzustellen.
* [Sinatra](/ruby/integrations/sinatra)
* [Hanami](/ruby/integrations/hanami)
* [Grape](/ruby/integrations/grape)
* [Padrino](/ruby/integrations/padrino)
* Verwenden Sie mehr als eine dieser Bibliotheken oder mounten Sie sie auf einer Rails-App? [Folgen Sie auch diesem Leitfaden](/ruby/integrations/rack-libraries).
* Die von unserer Rake-Integration gemeldeten Fehler und Performance-Probleme werden jetzt unter dem Namespace "rake" gemeldet.
### Benutzerdefinierte Instrumentierung
* Der [`Appsignal.report_error`-Helper](/ruby/instrumentation/exception-handling) macht es einfacher, Fehler immer zu melden, ohne den Unterschied zwischen den Helpern `Appsignal.set_error` und `Appsignal.send_error` zu kennen.
```ruby Ruby theme={null}
# Before
Appsignal.set_error(error)
Appsignal.send_error(error, :tag => "value", "custom namespace")
# After
Appsignal.report_error(error)
Appsignal.report_error(error) do
Appsignal.set_namespace("custom namespace")
Appsignal.add_tags(:tag => "value")
end
```
* Mehrere Fehler können in einer Transaktion mit dem [`Appsignal.report_error`-Helper](/ruby/instrumentation/exception-handling#reporting-multiple-exceptions) gemeldet werden.
* Die Helper `Appsignal.monitor_transaction` und `Appsignal.monitor_single_transaction` wurden durch die [Helper `Appsignal.monitor` und `Appsignal.monitor_and_stop`](/ruby/instrumentation/background-jobs) ersetzt.
* Hinweis: In neueren Versionen des Ruby-Gems wurde der [Helper `Appsignal.monitor_and_stop` als veraltet markiert](/ruby/instrumentation/background-jobs#stop-requirement).
* Neue Helper zum Hinzufügen von Tags und Sample-Daten (Parameter, Request-Header, Session-Daten und benutzerdefinierte Daten) zu Transaktionen. Weitere Informationen finden Sie in der Dokumentation zu den [Anpassungs-Helpern](/guides/custom-data).
```ruby Ruby theme={null}
# Before
Appsignal.tag_request(:tag => "value")
Appsignal::Transaction.current.set_sample_data(
"custom_data",
:i18n => {
:locale => "en_GB",
:default_locale => "en_US"
}
)
# After
Appsignal.add_tags(:tag => "value")
Appsignal.add_custom_data(
:i18n => {
:locale => "en_GB",
:default_locale => "en_US"
}
)
```
* Sample-Daten werden standardmäßig ergänzt. Das Hinzufügen weiterer Parameter, Request-Header, Session-Daten und benutzerdefinierter Daten wird mit den zuvor gesetzten Werten zusammengeführt. Weitere Informationen finden Sie in der Dokumentation zu den [Anpassungs-Helpern](/guides/custom-data).
* Der Helper `Appsignal::Transaction::GenericRequest` wurde entfernt. Verwenden Sie unsere [Anpassungs-Helper](/guides/custom-data), um der Transaktion Metadaten hinzuzufügen.
* Die Request-Environment-Schlüssel `appsignal.action` und `appsignal.route` wurden entfernt. Verwenden Sie stattdessen den Helper `Appsignal.set_action`, um den Action-Namen zu setzen.
* Die Argumente `tags` und `namespace` wurden aus den Helpern `Appsignal.set_error` und `Appsignal.send_error` entfernt. Verwenden Sie stattdessen die Block-Methode, um die Transaktion vor dem Senden anzupassen. Weitere Informationen finden Sie in [unserem Leitfaden zur Exception-Handhabung](/ruby/instrumentation/exception-handling).
* Die Konstante `Appsignal::Minutely` wurde in `Appsignal::Probes` umbenannt.
* Die Methode `Appsignal::Probes.probes.register` wurde durch `Appsignal::Probes.register` ersetzt. Weitere Informationen finden Sie in [unserer Dokumentation zu Minutely-Probes](/ruby/instrumentation/minutely-probes).
* Die Helper `Appsignal.set_host_gauge` und `Appsignal.set_process_gauge` wurden ersatzlos entfernt. Taggen Sie die Metrik stattdessen mit dem Hostnamen oder der Prozess-ID mit dem [`Appsignal.set_gauge`-Helper](/metrics/custom#gauge).
* Der Helper `Appsignal.listen_for_error` wurde ersatzlos entfernt. Fangen Sie Fehler stattdessen manuell mit `rescue => error` ab und melden Sie sie mit dem [`Appsignal.report_error`-Helper](/ruby/instrumentation/exception-handling#appsignalreport_error).
### Bibliotheks-Interna
Hier aufgeführt sind Änderungen an Bibliotheks-Interna, die zuvor möglicherweise in unserer Dokumentation oder in Support-Fällen verwendet wurden. Wir empfehlen, sich nicht mehr auf diese zu verlassen. Dies sind private Komponenten und können sich jederzeit ändern. Breaking Changes sind:
* Die Methoden `Appsignal::Transaction.create` und `Appsignal::Transaction.new` akzeptieren die Argumente `id`, `request` und `options` nicht mehr. Die Transaktions-ID wird jetzt automatisch generiert.
* Anstatt ein Transaction-Objekt manuell zu erstellen, verwenden Sie stattdessen den [`Appsignal.monitor`-Helper](/ruby/instrumentation/background-jobs).
* Um Metadaten auf der Transaktion zu setzen, verwenden Sie unsere [Anpassungs-Helper](/guides/custom-data).
* Die Methode `Appsignal::Transaction#set_http_or_background_action` wurde entfernt. Verwenden Sie stattdessen den Helper `Appsignal.set_action`.
* Die Methode `Appsignal::Transaction#set_http_or_background_queue_start` wurde entfernt. Verwenden Sie stattdessen den Helper `Appsignal::Transaction#set_queue_start`.
* Der Helper `AppSignal::Transaction#params=` wurde entfernt. Verwenden Sie stattdessen den [`Appsignal.add_params`-Helper](/guides/custom-data/request-parameters).
## Willkommen bei 4.x!
Dieser Leitfaden sollte das Upgrade der meisten Ruby-Anwendungen auf das AppSignal Ruby-Gem 4.x abdecken. Wenn Sie Fragen haben, auf Fehler gestoßen sind oder Unterstützung beim Upgrade auf die neue Version benötigen, zögern Sie bitte nicht, den [Support zu kontaktieren][contact].
[contact]: mailto:support@appsignal.com