> ## 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.

# Mise à niveau de la gem AppSignal pour Ruby 3.x vers 4.x

> Un guide pour aider les applications à passer de la gem AppSignal pour Ruby 3 à la version 4.

AppSignal pour Ruby 4.0 est une version majeure qui introduit la prise en charge de plusieurs erreurs, des données d'échantillon modifiables, des changements dans la façon dont elle instrumente les autres gems, le fonctionnement de l'instrumentation personnalisée, et la suppression des modules précédemment dépréciés. Suivez ce guide pour rendre le processus de mise à niveau plus fluide.

## Mise à niveau vers la dernière série 3.x

Avant de passer à la gem AppSignal pour Ruby 4.0, effectuez la mise à niveau vers la dernière gem de la série 3.x. Cette version imprimera et enregistrera des avertissements de dépréciation pour les éléments qui ont été supprimés dans la version 4.x de la gem Ruby. Exécutez les tests de votre application avec laquelle la gem est intégrée et corrigez tous les avertissements et erreurs de dépréciation que vous pourriez rencontrer.

Tout d'abord, dans le `Gemfile` de l'application, mettez à jour le verrou de version vers `~> 3.0` et exécutez `bundle update appsignal` dans un terminal, dans le même répertoire que le `Gemfile`.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Gemfile

  gem "appsignal", "~> 3.0"
  ```
</CodeGroup>

Exécutez vos applications et corrigez tous les avertissements de dépréciation imprimés sur la sortie STDERR de l'application et enregistrés dans `appsignal.log` pendant son fonctionnement.

## Mise à niveau vers la dernière série 4.x

Une fois que tous les avertissements de dépréciation sont résolus à l'aide de la version 3 de la gem Ruby, supprimez le verrou de version du `Gemfile` et exécutez à nouveau `bundle update appsignal` pour mettre à jour AppSignal pour Ruby vers la version 4.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Gemfile

  gem "appsignal"
  ```
</CodeGroup>

## Changements

Vous trouverez ci-dessous tous les changements notables entre la dernière version 3 de la gem Ruby et la nouvelle version 4. Veuillez les parcourir et mettre à jour votre application comme décrit.

### Bibliothèque principale

* La méthode `Appsignal.start_logger` est supprimée. Le logger est désormais démarré automatiquement par `Appsignal.start`. Les applications doivent supprimer l'appel à `Appsignal.start_logger`.
* La configuration de la gem Ruby AppSignal est figée après l'appel à `Appsignal.start`. La configuration ne peut plus être modifiée après le démarrage de la gem Ruby.
* La méthode `Appsignal.start` ne peut être appelée qu'une seule fois. Les appels suivants sont ignorés par la gem Ruby.

### Configuration

* AppSignal ne démarrera pas si le chargement du fichier `config/appsignal.yml` provoque une erreur. Vérifiez la sortie de l'application ou le fichier `appsignal.log` pour tout avertissement.
* Configurez AppSignal en Ruby avec le nouvel [assistant `Appsignal.configure`](/ruby/configuration/load-order#configure-helper). Les applications utilisant le pattern `Appsignal.config = Appsignal::Config.new(...)` doivent mettre à jour leurs applications pour utiliser cette méthode à la place.
* La méthode `Appsignal.config =` est supprimée. Utilisez plutôt l'[assistant `Appsignal.configure`](/ruby/configuration/load-order#configure-helper) pour configurer AppSignal en Ruby.
* L'option `skip_session_data` est supprimée. Utilisez plutôt l'[option `send_session_data`](/ruby/configuration/options#option-send_session_data).
* L'option `debug` est supprimée. Utilisez plutôt l'[option `log_level: debug`](/ruby/configuration/options#option-log_level).
* L'option `transaction_debug_mode` est supprimée. Utilisez plutôt l'[option `log_level: trace`](/ruby/configuration/options#option-log_level).
* L'option `working_dir_path` est supprimée. Utilisez plutôt l'[option `working_directory_path`](/ruby/configuration/options#option-working_directory_path).

### Intégrations

* Le middleware `Appsignal::Rack::EventHandler` est ajouté. Il ajoutera le tag `response_status` aux échantillons et suivra une métrique `response_status` avec le code de statut de réponse de la requête. Consultez [notre documentation sur l'intégration Rack](/ruby/integrations/rack) pour plus d'informations.
* Le middleware `Appsignal::Rack::InstrumentationMiddleware` remplace le middleware `Appsignal::Rack::GenericInstrumentation`. Ce nouveau middleware ne définit pas l'action sur « unknown » par défaut. Il est nécessaire de définir le nom de l'action dans chaque endpoint de l'application avec `Appsignal.set_action` lorsque seul le middleware `InstrumentationMiddleware` est utilisé. Consultez [notre documentation sur l'intégration Rack](/ruby/integrations/rack) pour plus d'informations.
* `Appsignal::Grape::Middleware` est renommé en `Appsignal::Rack::GrapeMiddleware`.
* `Appsignal::Rack::StreamingListener` est remplacé par `Appsignal::Rack::InstrumentationMiddleware`.
* `Appsignal::Hooks::SidekiqPlugin` est supprimé sans remplacement.
* Les intégrations Grape, Hanami, Padrino et Sinatra utilisent désormais le mécanisme `Appsignal.load` pour s'intégrer à ces bibliothèques. Veuillez suivre les guides d'installation pour ces bibliothèques afin de passer au nouveau mécanisme de chargement.
  * [Sinatra](/ruby/integrations/sinatra)
  * [Hanami](/ruby/integrations/hanami)
  * [Grape](/ruby/integrations/grape)
  * [Padrino](/ruby/integrations/padrino)
  * Vous utilisez plusieurs de ces bibliothèques ou les montez sur une application Rails ? [Suivez également ce guide](/ruby/integrations/rack-libraries).
* Les erreurs et problèmes de performance signalés par notre intégration Rake sont désormais signalés sous le namespace « rake ».

### Instrumentation personnalisée

* L'[assistant `Appsignal.report_error`](/ruby/instrumentation/exception-handling) facilite le signalement systématique des erreurs, sans connaître la différence entre les assistants `Appsignal.set_error` et `Appsignal.send_error`.

<CodeGroup>
  ```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
  ```
</CodeGroup>

* Plusieurs erreurs peuvent être signalées sur une seule transaction avec l'[assistant `Appsignal.report_error`](/ruby/instrumentation/exception-handling#reporting-multiple-exceptions).
* Les assistants `Appsignal.monitor_transaction` et `Appsignal.monitor_single_transaction` sont remplacés par les [assistants `Appsignal.monitor` et `Appsignal.monitor_and_stop`](/ruby/instrumentation/background-jobs).
  * Remarque : les versions plus récentes de la gem Ruby ont [déprécié l'assistant `Appsignal.monitor_and_stop`](/ruby/instrumentation/background-jobs#stop-requirement).
* Nouveaux assistants pour ajouter des tags et des données d'échantillon (paramètres, en-têtes de requête, données de session et données personnalisées) aux transactions. Consultez la documentation des [assistants de personnalisation](/guides/custom-data) pour plus d'informations.

<CodeGroup>
  ```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"
    }
  )
  ```
</CodeGroup>

* Les données d'échantillon sont modifiées par défaut. L'ajout de paramètres, d'en-têtes de requête, de données de session et de données personnalisées supplémentaires les fusionnera avec les valeurs précédemment définies. Consultez la documentation des [assistants de personnalisation](/guides/custom-data) pour plus d'informations.
* L'assistant `Appsignal::Transaction::GenericRequest` est supprimé. Utilisez nos [assistants de personnalisation](/guides/custom-data) pour ajouter des métadonnées à la transaction.
* Les clés d'environnement de requête `appsignal.action` et `appsignal.route` sont supprimées. Utilisez plutôt l'assistant `Appsignal.set_action` pour définir le nom de l'action.
* Les arguments `tags` et `namespace` ont été supprimés des assistants `Appsignal.set_error` et `Appsignal.send_error`. Utilisez plutôt la méthode block pour personnaliser la transaction avant qu'elle ne soit envoyée. Consultez [notre guide de gestion des exceptions](/ruby/instrumentation/exception-handling) pour plus d'informations.
* La constante `Appsignal::Minutely` est renommée en `Appsignal::Probes`.
* La méthode `Appsignal::Probes.probes.register` est remplacée par `Appsignal::Probes.register`. Consultez [notre documentation sur les minutely probes](/ruby/instrumentation/minutely-probes) pour plus d'informations.
* Les assistants `Appsignal.set_host_gauge` et `Appsignal.set_process_gauge` sont supprimés sans remplacement. À la place, taguez la métrique avec le nom d'hôte ou l'ID du processus à l'aide de l'[assistant `Appsignal.set_gauge`](/metrics/custom#gauge).
* L'assistant `Appsignal.listen_for_error` est supprimé sans remplacement. À la place, attrapez manuellement les erreurs à l'aide de `rescue => error` et signalez-les avec l'[assistant `Appsignal.report_error`](/ruby/instrumentation/exception-handling#appsignalreport_error).

### Internes de la bibliothèque

Sont répertoriés ici les changements apportés aux composants internes de la bibliothèque qui ont pu être précédemment utilisés dans notre documentation ou nos dossiers de support. Nous vous recommandons de ne plus vous appuyer dessus. Ce sont des composants privés et peuvent changer à tout moment. Les changements importants incluent :

* Les méthodes `Appsignal::Transaction.create` et `Appsignal::Transaction.new` n'acceptent plus les arguments `id`, `request` et `options`. L'ID de transaction est désormais généré automatiquement.
  * Au lieu de créer manuellement un objet Transaction, utilisez plutôt l'[assistant `Appsignal.monitor`](/ruby/instrumentation/background-jobs).
  * Pour définir des métadonnées sur la transaction, utilisez nos [assistants de personnalisation](/guides/custom-data).
* La méthode `Appsignal::Transaction#set_http_or_background_action` est supprimée. Utilisez plutôt l'assistant `Appsignal.set_action`.
* La méthode `Appsignal::Transaction#set_http_or_background_queue_start` est supprimée. Utilisez plutôt l'assistant `Appsignal::Transaction#set_queue_start`.
* L'assistant `AppSignal::Transaction#params=` est supprimé. Utilisez plutôt l'[assistant `Appsignal.add_params`](/guides/custom-data/request-parameters).

## Bienvenue dans la 4.x !

Ce guide devrait couvrir la mise à niveau de la plupart des applications Ruby vers la gem Ruby AppSignal 4.x. Si vous avez des questions, rencontrez des erreurs ou souhaitez de l'aide pour la mise à niveau vers la nouvelle version, n'hésitez pas à [contacter le support][contact].

[contact]: mailto:support@appsignal.com