> ## 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 2.x para 3.x

O AppSignal para Ruby 3.0 é uma versão major, pois muda a forma como instrumenta outras gems, remove suporte para versões mais antigas do Ruby, remove a integração JavaScript integrada e remove módulos previamente obsoletos. Siga este guia para tornar o processo de atualização mais tranquilo.

## Atualize para a última série 2.x

Antes de atualizar para a gem AppSignal para Ruby 3.0, primeiro atualize para a última gem da série 2.x. Esta versão registrará e exibirá avisos de descontinuação para itens que serão removidos na versão 3.x da gem. Execute os testes do seu app onde a gem está integrada e corrija quaisquer avisos de descontinuação e erros que possa encontrar. Esta etapa de atualização tornará o processo de upgrade mais fácil.

Primeiro, no `Gemfile` do app, atualize o version lock para `~> 2.0` e execute `bundle update appsignal` em um terminal no mesmo diretório do `Gemfile`.

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

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

Depois que todos os avisos de descontinuação que apareceram durante os testes e a execução do app forem resolvidos, remova o version lock do `Gemfile` e execute `bundle update appsignal` novamente para atualizar para o AppSignal para Ruby 3.0.

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

  gem "appsignal"
  ```
</CodeGroup>

## Suporte ao Ruby 1.9 removido

A série 3.x da gem Ruby não suportará mais o Ruby 1.9 e versões mais antigas. O Ruby 1.9 está em End of Life desde [23 de fevereiro de 2015](https://www.ruby-lang.org/en/news/2015/02/23/support-for-ruby-1-9-3-has-ended/) e não deve mais ser usado em produção. Versões futuras da gem AppSignal para Ruby podem descontinuar outras versões End of Life do Ruby.

Por favor, atualize para uma versão mais recente do Ruby para continuar usando o AppSignal para Ruby daqui pra frente.

## Compatibilidade com outras gems de instrumentação

Na série 3.x, a gem AppSignal para Ruby mudou os internals de todas as suas integrações com outras gems. Em vez de fazer aliasing de métodos para fornecer instrumentação, a série 3.x usa `Module.prepend` (introduzido no Ruby 2.0), um método para incluir Módulos Ruby em classes garantindo que o módulo incluído seja chamado primeiro.

**O que isso significa para seus apps?**

Outras gems de instrumentação podem usar tanto o método de aliasing quanto o `Module.prepend` para fornecer instrumentação. Esses métodos de instrumentação são **incompatíveis** entre si se usados nos mesmos métodos Ruby. Se uma gem usa aliasing de métodos, e outra `Module.prepend`, o app ficará preso em um loop e levantará um [`stack level too deep (SystemStackError)`][module prepend issue].

O ecossistema Ruby parece estar caminhando para o método `Module.prepend` para fornecer instrumentação, então a gem do AppSignal atualizou seu método de instrumentação para ser mais compatível com outras gems.

Se um app começar a encontrar esse problema com a série 3.x do AppSignal para Ruby, atualize outras gems APM e de relatórios de erro no app. Elas podem ter sido atualizadas para instrumentar usando `Module.prepend` também.

Se o problema persistir, entre em contato com os mantenedores das outras gems para atualizar sua implementação para `Module.prepend`, e faça downgrade da gem AppSignal para Ruby para a série 2.x por enquanto. Por favor, também [nos informe][contact], para que possamos manter uma lista de gems compatíveis.

Para mais informações e contexto sobre essa mudança, veja a [issue 603 no rastreador de issues da gem Ruby][module prepend issue].

## Módulos movidos

Alguns módulos na gem foram movidos ou renomeados. A série 2.x da gem imprimirá um aviso se encontrar algum, com a nova localização do módulo chamado. Esse aviso é impresso por um fallback quando o nome do módulo antigo é chamado. Esse aviso não será mais impresso se o novo nome do módulo estiver sendo chamado.

Se um app estendeu ou aplicou monkeypatch em um módulo do AppSignal, o nome do módulo precisa ser atualizado para que o patch funcione novamente. Esteja avisado de que não fornecemos suporte para esses patches. Se um módulo privado foi removido sem substituição, não fornecemos mais a integração ou ela foi mesclada em outro módulo.

## Integração JavaScript removida

A gem AppSignal para Ruby incluía um middleware de rastreamento de exceções JavaScript, que foi removido na série 3.x. Em vez disso, recomendamos que você use nossa [integração dedicada AppSignal para JavaScript front-end](/front-end/).

### Opções removidas

As opções a seguir não afetarão mais a gem AppSignal para Ruby, podem ser removidas dos seus apps.

* `enable_frontend_error_catching` - opção de configuração removida
  * `APPSIGNAL_ENABLE_FRONTEND_ERROR_CATCHING` - opção de configuração via variável de ambiente removida
* `frontend_error_catching_path` - opção de configuração removida
  * `APPSIGNAL_FRONTEND_ERROR_CATCHING_PATH` - opção de configuração via variável de ambiente removida

### Classes removidas

As classes a seguir foram removidas da gem Ruby e chamá-las resultará em um `NameError`.

* `Appsignal::JSExceptionTransaction` - classe de transação JavaScript removida
* `Appsignal::Rack::JSExceptionCatcher` - middleware removido

## Comando `appsignal notify_of_deploy` removido

O comando `appsignal notify_of_deploy` foi removido. Em vez disso, recomendamos usar a opção de configuração [`revision`](/ruby/configuration/options#option-revision) para reportar deploys de forma mais precisa. Para mais informações sobre o tópico de marcadores de deploy, veja nossa [seção de marcadores de deploy](/application/markers/deploy-markers).

Se a opção `revision` não for uma boa substituta para o seu método de deploy, use a [página da API de marcadores de deploy](/api/markers) sobre como enviar a requisição para notificar o AppSignal sobre deploys. E veja nossa [página Push & deploy](https://appsignal.com/redirect-to/app?to=info) para o seu app para um exemplo usando a configuração do seu app.

## Descontinuações removidas

Na série 2.x e versões anteriores do AppSignal para Ruby, alguns comportamentos da gem do AppSignal podem ter sido descontinuados. A maioria dessas descontinuações foi removida na série 3.x.

Na última versão da série 2.x do AppSignal para Ruby, todas essas descontinuações devem imprimir um aviso no STDERR e no [`appsignal.log`](/support/debugging#log-location) quando ainda usadas. Por favor, verifique a saída do app e os logs enquanto estiver na última gem 2.x e corrija todos os avisos de descontinuação antes de atualizar. Cada descontinuação deve imprimir/registrar um aviso com as mudanças necessárias para resolver o aviso.

## Bem-vindo ao 3.x!

Este guia deve cobrir a atualização da maioria das aplicações Ruby para o 3.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

[module prepend issue]: https://github.com/appsignal/appsignal-ruby/issues/603