> ## 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.
# Atualização da gem AppSignal para Ruby 3.x para 4.x
> Um guia para ajudar aplicações a atualizar da gem AppSignal para Ruby 3 para a versão 4.
O AppSignal para Ruby 4.0 é uma versão major que introduz suporte a múltiplos erros, dados de amostra editáveis, mudanças na forma como instrumenta outras gems, como funciona a instrumentação personalizada e a remoção de módulos previamente obsoletos. Siga este guia para tornar o processo de atualização mais tranquilo.
## Atualize para a última série 3.x
Antes de atualizar para a gem AppSignal para Ruby 4.0, atualize para a última gem da série 3.x. Esta versão imprimirá e registrará avisos de descontinuação para itens que foram removidos na versão 4.x da gem Ruby. Execute os testes do seu app com o qual a gem está integrada e corrija quaisquer avisos de descontinuação e erros que possa encontrar.
Primeiro, no `Gemfile` do app, atualize o version lock para `~> 3.0` e execute `bundle update appsignal` em um terminal no mesmo diretório do `Gemfile`.
```ruby Ruby theme={null}
# Gemfile
gem "appsignal", "~> 3.0"
```
Execute suas aplicações e corrija quaisquer avisos de descontinuação impressos na saída STDERR da aplicação e registrados no `appsignal.log` durante sua operação.
## Atualize para a última série 4.x
Depois que todos os avisos de descontinuação forem resolvidos usando a versão 3 da gem Ruby, remova o version lock do `Gemfile` e execute `bundle update appsignal` novamente para atualizar o AppSignal para Ruby para a versão 4.
```ruby Ruby theme={null}
# Gemfile
gem "appsignal"
```
## Mudanças
Abaixo estão todas as mudanças notáveis entre a última versão 3 da gem Ruby e a nova versão 4. Por favor, revise-as e atualize sua aplicação conforme descrito.
### Biblioteca principal
* O método `Appsignal.start_logger` foi removido. O logger agora é iniciado automaticamente em `Appsignal.start`. As aplicações precisam remover a chamada `Appsignal.start_logger`.
* A configuração da gem AppSignal para Ruby é congelada após `Appsignal.start` ser chamado. A configuração não pode mais ser modificada depois que a gem Ruby foi iniciada.
* O método `Appsignal.start` só pode ser chamado uma vez. Chamadas subsequentes são ignoradas pela gem Ruby.
### Configuração
* O AppSignal não iniciará se o carregamento do arquivo `config/appsignal.yml` causar um erro. Verifique a saída da aplicação ou o arquivo `appsignal.log` para quaisquer avisos.
* Configure o AppSignal em Ruby com o novo [helper `Appsignal.configure`](/ruby/configuration/load-order#configure-helper). Apps que usam o padrão `Appsignal.config = Appsignal::Config.new(...)` devem atualizar seus apps para usar este método.
* O método `Appsignal.config =` foi removido. Em vez disso, use o [helper `Appsignal.configure`](/ruby/configuration/load-order#configure-helper) para configurar o AppSignal em Ruby.
* A opção `skip_session_data` foi removida. Use a [opção `send_session_data`](/ruby/configuration/options#option-send_session_data) em vez disso.
* A opção `debug` foi removida. Use a [opção `log_level: debug`](/ruby/configuration/options#option-log_level) em vez disso.
* A opção `transaction_debug_mode` foi removida. Use a [opção `log_level: trace`](/ruby/configuration/options#option-log_level) em vez disso.
* A opção `working_dir_path` foi removida. Use a [opção `working_directory_path`](/ruby/configuration/options#option-working_directory_path) em vez disso.
### Integrações
* O middleware `Appsignal::Rack::EventHandler` foi adicionado. Ele adicionará a tag `response_status` às amostras e rastreará uma métrica `response_status` com o código de status de resposta da requisição. Veja [a documentação da nossa integração Rack](/ruby/integrations/rack) para mais informações.
* O middleware `Appsignal::Rack::InstrumentationMiddleware` substitui o middleware `Appsignal::Rack::GenericInstrumentation`. Este novo middleware não define a action como "unknown" por padrão. É necessário definir o nome da action em cada endpoint do app com `Appsignal.set_action` ao usar apenas o middleware `InstrumentationMiddleware`. Veja [a documentação da nossa integração Rack](/ruby/integrations/rack) para mais informações.
* `Appsignal::Grape::Middleware` foi renomeado para `Appsignal::Rack::GrapeMiddleware`.
* O `Appsignal::Rack::StreamingListener` foi substituído por `Appsignal::Rack::InstrumentationMiddleware`.
* O `Appsignal::Hooks::SidekiqPlugin` foi removido sem substituição.
* As integrações Grape, Hanami, Padrino e Sinatra agora usam o mecanismo `Appsignal.load` para integrar com essas bibliotecas. Por favor, siga os guias de instalação dessas bibliotecas para atualizar para o novo mecanismo de carregamento.
* [Sinatra](/ruby/integrations/sinatra)
* [Hanami](/ruby/integrations/hanami)
* [Grape](/ruby/integrations/grape)
* [Padrino](/ruby/integrations/padrino)
* Usando mais de uma dessas bibliotecas ou montando-as em um app Rails? [Siga também este guia](/ruby/integrations/rack-libraries).
* Os erros e problemas de desempenho reportados pela nossa integração Rake agora são reportados sob o namespace "rake".
### Instrumentação personalizada
* O [helper `Appsignal.report_error`](/ruby/instrumentation/exception-handling) facilita reportar erros sempre, sem precisar conhecer a diferença entre os helpers `Appsignal.set_error` e `Appsignal.send_error`.
```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
```
* Múltiplos erros podem ser reportados em uma transação com o [helper `Appsignal.report_error`](/ruby/instrumentation/exception-handling#reporting-multiple-exceptions).
* Os helpers `Appsignal.monitor_transaction` e `Appsignal.monitor_single_transaction` são substituídos pelos [helpers `Appsignal.monitor` e `Appsignal.monitor_and_stop`](/ruby/instrumentation/background-jobs).
* Nota: versões mais recentes da gem Ruby [descontinuaram o helper `Appsignal.monitor_and_stop`](/ruby/instrumentation/background-jobs#stop-requirement).
* Novos helpers para adicionar tags e dados de amostra (parâmetros, headers de requisição, dados de sessão e dados personalizados) a transações. Veja a documentação dos [helpers de customização](/guides/custom-data) para mais informações.
```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"
}
)
```
* Os dados de amostra são editados por padrão. Adicionar parâmetros adicionais, headers de requisição, dados de sessão e dados personalizados os mesclará com os valores definidos anteriormente. Veja a documentação dos [helpers de customização](/guides/custom-data) para mais informações.
* O helper `Appsignal::Transaction::GenericRequest` foi removido. Use nossos [helpers de customização](/guides/custom-data) para adicionar metadados à transação.
* As chaves de ambiente de requisição `appsignal.action` e `appsignal.route` foram removidas. Use o helper `Appsignal.set_action` para definir o nome da action.
* Os argumentos `tags` e `namespace` foram removidos dos helpers `Appsignal.set_error` e `Appsignal.send_error`. Use o método de bloco para personalizar a transação antes que ela seja enviada. Veja [nosso guia de tratamento de exceções](/ruby/instrumentation/exception-handling) para mais informações.
* A constante `Appsignal::Minutely` foi renomeada para `Appsignal::Probes`.
* O método `Appsignal::Probes.probes.register` foi substituído por `Appsignal::Probes.register`. Veja [nossa documentação de minutely probes](/ruby/instrumentation/minutely-probes) para mais informações.
* Os helpers `Appsignal.set_host_gauge` e `Appsignal.set_process_gauge` foram removidos sem substituição. Em vez disso, marque a métrica com o hostname ou ID do processo usando o [helper `Appsignal.set_gauge`](/metrics/custom#gauge).
* O helper `Appsignal.listen_for_error` foi removido sem substituição. Em vez disso, capture os erros manualmente usando `rescue => error` e os reporte usando o [helper `Appsignal.report_error`](/ruby/instrumentation/exception-handling#appsignalreport_error).
### Internals da biblioteca
Listadas aqui estão mudanças nos internals da biblioteca que podem ter sido previamente usadas em nossa documentação ou casos de suporte. Recomendamos que você evite continuar dependendo desses recursos. Eles são componentes privados e podem mudar a qualquer momento. Mudanças incompatíveis incluem:
* Os métodos `Appsignal::Transaction.create` e `Appsignal::Transaction.new` não aceitam mais os argumentos `id`, `request` e `options`. O ID da transação agora é gerado automaticamente.
* Em vez de criar manualmente um objeto Transaction, use o [helper `Appsignal.monitor`](/ruby/instrumentation/background-jobs).
* Para definir metadados na transação, use nossos [helpers de customização](/guides/custom-data).
* O método `Appsignal::Transaction#set_http_or_background_action` foi removido. Use o helper `Appsignal.set_action` em vez disso.
* O método `Appsignal::Transaction#set_http_or_background_queue_start` foi removido. Use o helper `Appsignal::Transaction#set_queue_start` em vez disso.
* O helper `AppSignal::Transaction#params=` foi removido. Use o [helper `Appsignal.add_params`](/guides/custom-data/request-parameters) em vez disso.
## Bem-vindo ao 4.x!
Este guia deve cobrir a atualização da maioria das aplicações Ruby para a gem AppSignal para Ruby 4.x. Se você tiver alguma dúvida, encontrar erros ou quiser assistência para atualizar para a nova versão, não hesite em [entrar em contato com o suporte][contact].
[contact]: mailto:support@appsignal.com