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

# Ruby on Rails

export const Compatibility = ({versions = [], label = "Available in"}) => {
  if (!Array.isArray(versions) || versions.length === 0) {
    return null;
  }
  const defaultPillStyle = {
    borderColor: "#d4d4d8",
    background: "#f4f4f5",
    color: "#3f3f46"
  };
  const pillStyles = {
    "AppSignal for Elixir": {
      background: "#f3e8ff",
      borderColor: "#d8b4fe",
      color: "#6b21a8"
    },
    "AppSignal for Front-end": {
      background: "#fef9c3",
      borderColor: "#fde047",
      color: "#854d0e"
    },
    "AppSignal for Go": {
      background: "#ccfbf1",
      borderColor: "#5eead4",
      color: "#115e59"
    },
    "AppSignal for JavaScript": {
      background: "#fef9c3",
      borderColor: "#fde047",
      color: "#854d0e"
    },
    "AppSignal for Node.js": {
      background: "#dcfce7",
      borderColor: "#86efac",
      color: "#166534"
    },
    "AppSignal for Python": {
      background: "#dbeafe",
      borderColor: "#93c5fd",
      color: "#1e40af"
    },
    "AppSignal for Ruby": {
      background: "#fee2e2",
      borderColor: "#fca5a5",
      color: "#991b1b"
    },
    "AppSignal for Rust": {
      background: "#ffedd5",
      borderColor: "#fdba74",
      color: "#9a3412"
    }
  };
  const getPillStyle = name => ({
    ...defaultPillStyle,
    ...pillStyles[name] || ({})
  });
  return <div className="not-prose my-4 rounded-lg border border-zinc-200 bg-zinc-50 px-4 py-3 text-sm dark:border-white/10 dark:bg-white/5">
      <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
        <span className="font-semibold text-zinc-700 dark:text-zinc-200">
          {label}:
        </span>
        {versions.map((v, i) => <span key={`${v.name}-${v.version}-${i}`} className="inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs font-medium" style={getPillStyle(v.name)}>
            <span>{v.name}</span>
            <span className="opacity-70">
              {v.version}
              {v.exact ? "" : "+"}
            </span>
          </span>)}
      </div>
    </div>;
};

[Ruby on Rails](http://rubyonrails.org/) é suportado prontamente pelo AppSignal. Para instalar, siga os passos de instalação no AppSignal, começando por clicar em 'Add app' na [tela de contas](https://appsignal.com/accounts).

A integração do AppSignal para Rails funciona rastreando exceptions e performance em requisições. Quando um erro ocorre em um controller durante uma requisição, o AppSignal o reportará. Os problemas de performance serão baseados na duração de uma requisição e criarão uma linha do tempo de eventos detalhando quais partes da aplicação levaram mais tempo.

## Active Job

<Compatibility versions={[{ name: "AppSignal for Ruby", version: "2.11.0" }]} />

Veja nossa [página do Active Job](/ruby/integrations/active-job) para mais informações sobre como nossa instrumentation do Active Job funciona.

## Action Cable

<Compatibility versions={[{ name: "AppSignal for Ruby", version: "2.3.0" }]} />

Veja nossa [página do Action Cable](/ruby/integrations/action-cable) para mais informações sobre como nossa instrumentation do Action Cable funciona.

## Configurar o AppSignal em um initializer

<Compatibility versions={[{ name: "AppSignal for Ruby", version: "3.12.0" }]} />

Recomendamos usar nosso [arquivo de configuração `config/appsignal.rb`](/ruby/configuration/load-order#appsignal-rb-config-file) ou [variáveis de ambiente](/ruby/configuration/load-order#5-environment-variables) para [configurar o AppSignal](/ruby/configuration).
Por padrão, não é possível configurar o AppSignal a partir de um initializer do Rails, porque o AppSignal carrega antes dos initializers da sua aplicação, para conseguir reportar erros que ocorrem durante a inicialização.

Para configurar o AppSignal em um initializer do Rails, primeiro configure o Rails para iniciar o AppSignal depois que os initializers do app tiverem sido executados.

<CodeGroup>
  ```ruby Ruby theme={null}
  # config/application.rb

  # ...

  module MyApp
    class Application < Rails::Application
      # Adicione esta linha
      config.appsignal.start_at = :after_initialize

      # Outras configurações
    end
  end
  ```
</CodeGroup>

Em seguida, no initializer:

<CodeGroup>
  ```ruby Ruby theme={null}
  # config/initializers/appsignal.rb

  Appsignal.configure do |config|
    config.ignore_actions = ["My action"]
  end
  ```
</CodeGroup>

Não chame `Appsignal.start` nos initializers. A gem Ruby iniciará o AppSignal automaticamente quando o Rails tiver executado todos os initializers.

Quando um app Rails é configurado para iniciar o AppSignal depois que os initializers foram carregados, não é mais possível [reportar erros dos initializers ao inicializar o app Rails](#error-reporting-from-initializers).

## Error reporting dos initializers

Por padrão, o AppSignal reporta erros que ocorrem em controllers, Rake tasks e jobs do Active Job. Ele não reporta erros que ocorrem quando a aplicação está inicializando, antes dos initializers do Rails. Para ser notificado quando esses erros ocorrem, adicione o seguinte ao seu arquivo `config.ru`, em torno da linha que requer o arquivo `environment.rb`.

<CodeGroup>
  ```ruby Ruby theme={null}
  # config.ru
  begin
    require ::File.expand_path("../config/environment",  __FILE__)
  rescue Exception => error
    Appsignal.send_error(error)
    raise
  end
  ```
</CodeGroup>

Os erros que ocorrem aqui não serão agrupados sob um incident com um nome de action.

## Backtrace cleaner

Com a integração Rails, o AppSignal executará o backtrace de cada exception através do [backtrace cleaner do Rails][backtrace cleaner docs]. Este cleaner dá a você a opção de modificar ou filtrar linhas indesejadas do backtrace, removendo desordem e ruído do backtrace.

Você pode adicionar ou remover filters e silencers da configuração padrão.

**Filters** mutarão a linha fornecida. Um exemplo seria remover o prefixo `Rails.root`.

**Silencers** removerão a linha do backtrace se a expressão fornecida retornar `true`. Você pode adicionar essas regras adicionais do backtrace cleaner em um initializer.

Por exemplo:

<CodeGroup>
  ```ruby Ruby theme={null}
  # config/initializers/backtrace_cleaner.rb
  bc = Rails.backtrace_cleaner
  bc.add_filter { |line| line.gsub(Rails.root.to_s, '<root>') }
  bc.add_silencer { |line| line.index('<root>').nil? and line.index('/') == 0 }
  bc.add_silencer { |line| line.index('<root>/vendor/') == 0 }
  ```
</CodeGroup>

Para mais informações sobre o backtrace cleaner, veja a [documentação do BacktraceCleaner do Rails][backtrace cleaner docs].

## Error reporter

<Compatibility versions={[{ name: "AppSignal for Ruby", version: "3.4.1" }]} />

O AppSignal reporta erros gerados via `ActiveSupport::ErrorReporter` por padrão. `ActiveSupport::ErrorReporter` foi introduzido no Rails 7.0 para padronizar o reporte de erros customizado.

Você pode desabilitar essa funcionalidade com a opção de configuração [`enable_rails_error_reporter`](/ruby/configuration/options#option-enable_rails_error_reporter).

Se uma transaction estiver ativa no contexto em que um erro é reportado através do Rails error reporter, ela incluirá os mesmos metadados e dados de sample que a transaction ativa: namespace, nome da action, tags, dados customizados, parâmetros, etc.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Em ambos os cenários, o erro é reportado pelo AppSignal
  Rails.error.handle do
    raise "some error"
  end

  Rails.error.record do
    raise "some error"
  end
  ```
</CodeGroup>

<Warning>
  Na gem AppSignal for Ruby versão 3, alguns comportamentos eram diferentes. Por favor,
  consulte a seção [comportamento legado da gem Ruby 3](#ruby-gem-3-legacy-behavior)
  para mais informações sobre as diferenças.
</Warning>

### Namespace e action a partir da transaction atual

Ao reportar erros, determinamos o namespace e o nome da action em que ele ocorre, como um controller ou background job, em uma base de melhor esforço. O namespace do incident e o nome da action nem sempre serão definidos ou precisos.

Se uma transaction do AppSignal estiver ativa (como em uma requisição web ou background job), o erro reportado com `Rails.error.handle/record` terá o mesmo namespace, nome da action, tags, parâmetros, dados customizados, etc. que a transaction ativa. Se nenhuma transaction do AppSignal estiver ativa, nenhum namespace, nome da action, tags, etc. serão definidos por padrão.

### Namespace e action a partir do contexto

Se você quiser mudar o namespace e o nome da action do erro reportado sem mudá-los na transaction do AppSignal já ativa, você pode personalizar isso na chamada do error reporter.

<CodeGroup>
  ```ruby Ruby theme={null}
  # O erro reportado aqui terá o namespace "custom_namespace"
  # e o nome de action "CustomizedActionName#index"
  Rails.error.handle(:context => { :appsignal => { :namespace => "custom_namespace", :action => "CustomizedActionName#index" } }) do
    raise "some error"
  end
  ```
</CodeGroup>

### Tags da transaction ativa

Por padrão, as tags de transaction da requisição/job são copiadas para a transaction do AppSignal do erro do error reporter a partir da transaction da requisição/job.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Exemplo de controller Rails usando um callback before_action
  class ExamplesController < ApplicationController
    before_action do
      Appsignal.add_tags(:tag1 => "value1", :tag2 => "value2")
    end

    def index
      # O erro reportado aqui terá as mesmas tags definidas
      # como no callback `before_action`
      Rails.error.handle do
        raise "some error"
      end
    end
  end
  ```
</CodeGroup>

### Tags do contexto

Você pode adicionar tags a um erro reportado usando `context` na chamada `Rails.error.handle/record`. Essas tags serão definidas apenas no erro reportado com os métodos `Rails.error.handle/record`.

<CodeGroup>
  ```ruby Ruby theme={null}
  Rails.error.handle(:context => { :tag1 => "value1", :tag2 => "value2" }) do
    raise "some error"
  end
  ```
</CodeGroup>

As mesmas limitações de tagging se aplicam ao usar [`Appsignal.add_tags`](/guides/tagging#ruby).

### Comportamento legado da gem Ruby 3

Na gem AppSignal for Ruby versão 3, o comportamento do reporte de erro é diferente.

* Erros reportados com o método `Rails.error.handle` são reportados ao AppSignal.
* Erros reportados com `Rails.error.record` não são reportados ao AppSignal para evitar reportar o erro duas vezes quando ele estiver sendo reportado pelo nosso middleware de error reporting do Rails.

Todos os erros reportados com o Rails error reporter são reportados como erros separados. Eles nem sempre incluem os mesmos metadados e dados de sample de qualquer transaction ativa do AppSignal. Veja a seção sobre [limitações de herança de contexto](#context-inheritance-limitations) para mais informações.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Reportado pelo AppSignal
  Rails.error.handle do
    raise "some error"
  end

  # NÃO reportado pelo AppSignal
  Rails.error.record do
    raise "some error"
  end
  ```
</CodeGroup>

#### Limitações de herança de contexto

Na gem Ruby 3, a herança de contexto da transaction ativa é limitada. Os metadados e alguns dos dados de sample são copiados apenas se estiverem definidos no momento em que `Rails.error.handle/record` é chamado.

Na prática, isso significa que controllers Rails e jobs do Active Job serão reportados com precisão. Outras bibliotecas como jobs do Sidekiq não terão nome de action definido ao reportar erros com `Rails.error.handle`.

Tags definidas após `Rails.error.handle/record` ser chamado não são reportadas para o erro reportado usando este helper.

## Runners

<Compatibility versions={[{ name: "AppSignal for Ruby", version: "4.0.0" }]} />

O AppSignal reportará automaticamente erros dentro de [Rails runners](https://guides.rubyonrails.org/command_line.html#bin-rails-runner). Alguma configuração manual também é necessária para instrumentar a performance de um runner.

Recomendamos colocar o código do runner em um arquivo separado e envolvê-lo no [helper `Appsignal.monitor`](/ruby/instrumentation/background-jobs), como mostrado no exemplo abaixo.

```bash Bash theme={null}
bin/rails runner path_to_file.rb
```

<CodeGroup>
  ```ruby Ruby theme={null}
  Appsignal.monitor(:namespace => :runner, :action => "Runner name") do
    # Algum código
  end
  ```
</CodeGroup>

Se seu Rails runner roda em um container que é iniciado apenas para executar esta task, certifique-se de que [a opção `enable_at_exit_hook`](/ruby/configuration/options#option-enable_at_exit_hook) esteja definida como `true` (o que deve ser o padrão em containers). Isso garantirá que os dados sejam descarregados para o agent do AppSignal antes do runner ser desligado.

[backtrace cleaner docs]: https://api.rubyonrails.org/classes/ActiveSupport/BacktraceCleaner.html

[error reporter]: https://guides.rubyonrails.org/error_reporting.html