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

# Configuração do AppSignal Ruby

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>;
};

Configuração. Importante, porque sem ela a gem AppSignal para Ruby não
saberá qual aplicação está instrumentando ou em qual ambiente.

Neste tópico vamos explicar como configurar o AppSignal, o que pode ser configurado
na gem Ruby, qual é a configuração mínima necessária e como a
configuração é carregada.

## Configuração mínima necessária

Para que as aplicações reportem dados ao AppSignal a configuração a seguir é necessária. Todas as outras configurações são opcionais.

* Nome da aplicação - [opção name](/ruby/configuration/options#option-name)
* Ambiente da aplicação - [environment](/ruby/configuration/options#option-appsignal_app_env) (detectado automaticamente ou definido via variável de ambiente)
* Push API key da aplicação - [opção push\_api\_key](/ruby/configuration/options#option-push_api_key)
* AppSignal precisa estar ativo - [opção active](/ruby/configuration/options#option-active)

Para apps Rails, você não precisa configurar o nome da aplicação, o AppSignal usará o nome da sua aplicação por padrão.

Se você usa um framework que reconhece ambientes e [é suportado pela gem do AppSignal](/ruby/integrations), o ambiente é detectado automaticamente.

<CodeGroup>
  ```ruby Ruby theme={null}
  # config/appsignal.rb
  Appsignal.configure do |config|
    config.activate_if_environment(:development, :staging, :production)
    config.name = "My app"
    config.push_api_key = "1234-1234-1234"
  end
  ```

  ```bash Bash theme={null}
  # Environment variables
  export APPSIGNAL_APP_NAME="My app"
  export APPSIGNAL_APP_ENV="production"
  export APPSIGNAL_PUSH_API_KEY="1234-1234-1234"
  ```

  ```yaml YAML theme={null}
  # config/appsignal.yml
  # Legacy config method
  production:
    active: true
    name: "My app"
    push_api_key: "1234-1234-1234"
  ```
</CodeGroup>

## Métodos de configuração

Existem vários métodos de configuração diferentes disponíveis na nossa gem Ruby.
Para ver em qual ordem eles são carregados e qual método de configuração sobrescreve valores de outras fontes, veja nossa página de [ordem de carregamento da configuração](/ruby/configuration/load-order).

### Arquivo de configuração Ruby

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

A gem AppSignal para Ruby pode ser configurada usando um arquivo de configuração Ruby. Quando selecionado, o instalador cria automaticamente um arquivo `config/appsignal.rb`. Este arquivo inclui configurações padrão que podem ser personalizadas para atender às necessidades específicas da sua aplicação.

Este arquivo de configuração é lido quando `Appsignal.start` é chamado, o que é chamado automaticamente para a maioria das nossas [integrações](/ruby/integrations). Leia as [instruções de integração do AppSignal](/ruby/instrumentation/integrating-appsignal) se `Appsignal.start` não for chamado automaticamente.

O arquivo de configuração configura nossa gem Ruby usando [o helper `Appsignal.configure`](#appsignalconfigure-helper). Leia a seção [o helper `Appsignal.configure`](#appsignalconfigure-helper) para mais detalhes sobre como usá-lo.

O [arquivo de configuração YAML](#yaml-configuration-file) não será lido quando este arquivo estiver presente.

<CodeGroup>
  ```ruby Ruby theme={null}
  Appsignal.configure do |config|
    # Enable AppSignal for the following environments
    config.activate_if_environment(:development, :staging, :production)

    # Ignore this action for all environments
    config.ignore_actions << "My global action"

    # Ignore this action for only the production environment
    if config.env?(:production)
      config.ignore_actions << "My production action"
    end

    # Ignore this action for only the staging environment
    if config.env?(:staging)
      config.ignore_actions << "My staging action"
    end
  end
  ```
</CodeGroup>

### Helper `Appsignal.configure`

O helper `Appsignal.configure` pode ser usado para configurar o AppSignal usando código Ruby. O [arquivo de configuração Ruby](#ruby-configuration-file) usa este helper e ele também pode ser usado diretamente na sua aplicação.

Se seu app usa `Appsignal.configure` fora do arquivo `config/appsignal.rb`, como em um initializer do Rails, leia [esta seção sobre as diferenças no comportamento](#using-the-appsignalconfigure-helper-in-your-application) que isso tem.

Defina as opções de configuração dentro do bloco `Appsignal.configure` chamando os métodos de escrita no objeto `config`. As [opções de configuração](/ruby/configuration/options) podem ser definidas usando a "Config file key" listada para as opções de configuração. Por exemplo, a [opção `send_params`](/ruby/configuration/options#option-send_params) pode ser definida usando: `config.send_params = false`.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Some examples on how to configure config options
  Appsignal.configure do |config|
    # Enable AppSignal for the following environments
    config.activate_if_environment(:development, :staging, :production)

    # Configure String config options
    config.name = "My app name"
    # Read a value from an environment variable
    config.hostname = ENV.fetch("HOSTNAME", "default hostname value")

    # Append values to Array config options
    config.ignore_actions += ["My ignored action", "My other ignored action"]
    config.request_headers << "MY_HTTP_HEADER"

    # Configure Boolean config options
    config.send_params = true
    config.enable_host_metrics = false
  end
  ```
</CodeGroup>

Leia o restante desta seção para mais detalhes sobre como o helper `Appsignal.configure` funciona e que outros helpers ele possui.

#### Opções de configuração String

Opções de configuração do tipo String podem ser definidas usando tanto Strings quanto Symbols. Quando definidas, converteremos Symbols em Strings.

<CodeGroup>
  ```ruby Ruby theme={null}
  Appsignal.configure do |config|
    config.activejob_report_errors = :discard

    config.activejob_report_errors
    # => "discard"
  end
  ```
</CodeGroup>

#### Opções de configuração Array

Opções de configuração do tipo Array podem ser modificadas como um array normal:

* Use uma atribuição para sobrescrever os padrões e valores previamente lidos das variáveis de ambiente.
  * Por exemplo: `config.array_option = ["value 1", "value 2"]`
  * Valor da opção: `["value 1", "value 2"]`
* Use o *operador de atribuição com adição* `+=` para mesclar um novo array de valores com os padrões e valores previamente lidos das variáveis de ambiente.
  * Por exemplo: `config.array_option += ["value 1", "value 2"]`
  * Valor da opção: `["DUMMY default value", "value 1", "value 2"]`
* Use o *operador append* `<<` para acrescentar um único valor à lista dos padrões e valores previamente lidos das variáveis de ambiente.
  * Por exemplo: `config.array_option << "value 1"`
  * Valor da opção: `["DUMMY default value", "value 1"]`

#### Detecção automática de ambiente

A gem AppSignal para Ruby detecta o ambiente da aplicação automaticamente. Integramos com gems como Rails, Sinatra, Rack e outras para detectar em qual ambiente a aplicação foi iniciada. Por essa razão, não deve ser necessário configurar o ambiente manualmente.

Se precisar configurar o ambiente da aplicação manualmente, passe o nome do ambiente como o primeiro argumento para o helper `Appsignal.configure`. Esse argumento sobrescreverá o [valor da variável de ambiente `APPSIGNAL_APP_ENV`](/ruby/configuration/options#option-appsignal_app_env) e a detecção automática de ambiente.

<CodeGroup>
  ```ruby Ruby theme={null}
  # Configure the application environment explicitly to be "production"
  Appsignal.configure(:production) do |config|
    # Some config
  end
  ```
</CodeGroup>

#### Helper `activate_if_environment`

O helper `Appsignal.configure` tem um helper para configurar quais ambientes devem estar ativos e reportar dados para AppSignal.com.

Chame `activate_if_environment` com uma lista de ambientes (Strings e/ou Symbols).
O AppSignal detecta o ambiente quando o helper `Appsignal.configure` é chamado sem um argumento de ambiente. Em seguida, ele verifica se o ambiente corresponde a algum dos valores fornecidos e, em caso afirmativo, define a [opção de configuração active](/ruby/configuration/options#option-active) como `true`.

<CodeGroup>
  ```ruby Ruby theme={null}
  Appsignal.configure do |config|
    # Enable AppSignal for the following environments
    config.activate_if_environment(:development, :staging, :production)
  end
  ```
</CodeGroup>

O helper `activate_if_environment` é um helper de conveniência para evitar que as aplicações tenham que adicionar suas próprias verificações sobre quando o AppSignal deve estar ativo, como:

<CodeGroup>
  ```ruby Ruby theme={null}
  Appsignal.configure do |config|
    # Example of a manual check for which environments AppSignal should be active
    config.active = Rails.env.development? || Rails.env.staging? || Rails.env.production?
  end
  ```
</CodeGroup>

#### Helper `env?`

O helper `Appsignal.configure` tem um helper para verificar qual ambiente o AppSignal detectou. Use este helper para verificar qual ambiente está ativo e definir as opções de configuração que devem se aplicar apenas a este ambiente.

Chame o helper `env?` com um nome de ambiente (String ou Symbol), e ele retornará `true` se o nome do ambiente corresponder ao ambiente atualmente ativo.

<CodeGroup>
  ```ruby Ruby theme={null}
  Appsignal.configure do |config|
    # Add this configuration only for the staging environment
    if config.env?(:staging)
      config.ignore_actions << "My staging action"
    end
  end
  ```
</CodeGroup>

#### Usando o helper `Appsignal.configure` na sua aplicação

Recomendamos configurar a gem AppSignal para Ruby usando o [arquivo de configuração Ruby](#ruby-configuration-file) em `config/appsignal.rb`. Se um initializer do Rails ou configuração inline for preferido, leia esta seção para entender as mudanças de comportamento que isso traz.

Se o helper `Appsignal.configure` for chamado antes que o arquivo de configuração Ruby `config/appsignal.rb` seja lido quando `Appsignal.start` é chamado, ele não lerá o arquivo de configuração Ruby.

Em apps Rails, certifique-se de [configurar a gem AppSignal para iniciar após o Rails ser inicializado](/ruby/integrations/rails#configure-appsignal-in-an-initializer), caso contrário, a configuração definida com `Appsignal.configure` é ignorada quando chamada em um initializer do Rails, como `config/initializers/appsignal.rb`.

<Warning>
  Na gem Ruby versão 3.12 e posteriores, se um [arquivo de configuração YAML](#yaml-configuration-file) estiver presente, ele será lido quando `Appsignal.configure` for chamado em um initializer do Rails ou inline em uma aplicação. Este comportamento está obsoleto. Por favor, mova toda a configuração para o helper `Appsignal.configure`.

  Removeremos este comportamento na próxima versão major da gem Ruby.
</Warning>

Exemplo de initializer do Rails:

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

  # WARNING: In this example the `config/appsignal.rb` config file is not read!
  Appsignal.configure do |config|
    # Set some config
  end
  ```
</CodeGroup>

Exemplo de configuração inline:

<CodeGroup>
  ```ruby Ruby theme={null}
  # Example file: app.rb
  require "appsignal"
  require "web_framework"

  # WARNING: In this example the `config/appsignal.rb` config file is not read!
  Appsignal.configure do |config|
    # Set some config
  end
  Appsignal.start

  run WebFramework.app
  ```
</CodeGroup>

### Variáveis de ambiente do sistema

O AppSignal também pode ser configurado usando variáveis de ambiente do sistema no host em que a aplicação que o AppSignal está monitorando roda. Isso é comum em plataformas como o Heroku.

Certifique-se de que essas variáveis de ambiente estão configuradas de forma compatível com seu sistema operacional e que os valores sejam carregados antes que seu app com AppSignal seja iniciado.

<CodeGroup>
  ```sh Shell theme={null}
  export APPSIGNAL_APP_NAME="My app"
  ```
</CodeGroup>

### Arquivo de configuração YAML

<Tip>
  Este método de configuração é um método legado e será removido na próxima versão major da gem Ruby.

  Por favor, use o [arquivo de configuração Ruby](#ruby-configuration-file) em vez disso.
</Tip>

A gem AppSignal para Ruby pode ser configurada com um arquivo de configuração YAML. Durante a instalação, a gem Ruby criará um arquivo `config/appsignal.yml`, se selecionado. Nesse arquivo, alguma configuração padrão é fornecida e pode ser modificada para atender às necessidades da sua aplicação. Este arquivo `config/appsignal.yml` suporta tags ERB para que variáveis de ambiente do sistema também possam ser carregadas neste arquivo.

Os exemplos de configuração `config/appsignal.yml` mostrados para as opções de configuração usarão a âncora YAML `default`. O instalador do AppSignal criará um arquivo `config/appsignal.yml` com essa âncora por padrão. Se não estiver presente, certifique-se de adicionar a opção de configuração ao ambiente correto.

<CodeGroup>
  ```yaml YAML theme={null}
  # config/appsignal.yml
  # Define the "defaults" anchor
  default: &defaults
    name: "My app"
    # Supports ERB
    push_api_key: "<%= ENV['APPSIGNAL_PUSH_API_KEY'] %>"

  production:
    # Loads the defaults in the production environment by referencing the anchor
    <<: *defaults
    # production environment specific configuration
    active: true
  ```
</CodeGroup>

#### Múltiplos ambientes do app

Vários ambientes do app podem ser configurados neste arquivo usando chaves no nível raiz.

<CodeGroup>
  ```yaml YAML theme={null}
  # Example: config/appsignal.yml
  development: # Development app environment
    active: true

  production: # Production app environment
    active: true

  test: # Testing app environment
    active: false # Disabled for test environment
  ```
</CodeGroup>

Para evitar ter que repetir a configuração para cada ambiente do app, podemos usar âncoras YAML para estender objetos YAML.

<CodeGroup>
  ```yaml YAML theme={null}
  # Example: config/appsignal.yml
  default: &defaults
    active: true

  development: # Development app environment
    <<: *defaults

  production: # Production app environment
    <<: *defaults

  test: # Testing app environment
    <<: *defaults
    active: false # Overwrites the inherited active config option from "defaults"
  ```
</CodeGroup>

Não é possível configurar apenas uma âncora `defaults` e fazê-la aplicar-se automaticamente a todos os ambientes. Cada ambiente precisa ser configurado no arquivo YAML com uma chave de nível raiz e estender desta âncora `defaults`.

#### Exemplo de arquivo de configuração YAML

Aqui está um exemplo de um arquivo de configuração `appsignal.yml`. Recomendamos
que você adicione apenas a configuração necessária ao seu arquivo de configuração.

Para a lista completa de opções, veja a página de [opções de
configuração](/ruby/configuration/options).

<CodeGroup>
  ```yaml YAML theme={null}
  # config/appsignal.yml
  default: &defaults
    # Your Push API Key, it is possible to set this dynamically using ERB. Required
    push_api_key: "<%= ENV['APPSIGNAL_PUSH_API_KEY'] %>"

    # Your app's name as reported on AppSignal.com. Required
    name: "My App"

    # Your server's hostname. Optional, auto detected
    hostname: "frontend1.myapp.com"

    # Add default instrumentation of net/http. Default: true
    instrument_net_http: true

    # Skip session data, if it contains private information. Default: false
    skip_session_data: true

    # Ignore these errors (Optional)
    ignore_errors:
      - SystemExit

    # Ignore these actions, used by our Loadbalancer. Optional
    ignore_actions:
      - IsUpController#index

    # Enable allocation tracking for memory metrics. Default: true
    enable_allocation_tracking: true

  # Configuration per environment, leave out an environment or set active
  # to false to not push metrics for that environment.
  development:
    <<: *defaults
    active: true
    # Set the severity level of AppSignal's internal logger. Optional
    # Supported values are error, warning, info, debug, trace
    log_level: debug

  staging:
    <<: *defaults
    # Configure AppSignal to be active for this environment. Required
    active: true

  production:
    <<: *defaults
    # Configure AppSignal to be active for this environment. Required
    active: true

    # Set different path for the log file. Optional, auto detected
    log_path: "/home/my_app/app/shared/log"

    # Set AppSignal working dir. Optional, auto detected
    working_directory_path: "/tmp/appsignal"

    # When it's not possible to connect to the outside world without a proxy.
    # Optional
    http_proxy: "proxy.mydomain.com:8080"
  ```
</CodeGroup>