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

# Tratamento de exceções

Na maioria das aplicações, alguns erros serão levantados que não estão relacionados a
possíveis bugs no seu código; eles simplesmente acontecem quando seu app entra em contato
com o mundo real. Bots podem passar e tentar postar formulários automaticamente,
links desatualizados podem direcionar visitantes a conteúdos que não existem mais,
e por aí vai.

Para evitar que esses erros sejam levantados como problemas no AppSignal, é possível
adicionar tratamento de exceções ao seu código ou até mesmo fazer o AppSignal ignorar
completamente certos erros.

## Ignorar erros

A configuração do AppSignal permite [ignorar
erros](/guides/filter-data/ignore-errors). Ao fornecer uma lista de
erros específicos, o AppSignal não enviará alertas quando esses erros forem levantados.

## Appsignal.set\_error/3

Se você quiser fazer rescue de exceções na sua aplicação para evitar crashes, mas
ainda quiser rastrear a ocorrência, você pode usar
[`Appsignal.set_error/2`][hexdocs-set_error-2] para adicionar a exceção à
transação atual do AppSignal:

<CodeGroup>
  ```elixir Elixir theme={null}
  try do
    raise "Exception!"
  rescue
    exception -> Appsignal.set_error(exception, __STACKTRACE__)
  end
  ```
</CodeGroup>

### Erlang

A integração do AppSignal faz o possível para converter erros levantados do Erlang em exceções Elixir. Por exemplo, um `:badarg`
levantado pelo Erlang é automaticamente convertido em um `ArgumentError`. No entanto, às vezes o melhor que ela consegue fazer é envolver o erro originado do Erlang em um `ErlangError`.

Como esses não fornecem muito insight sobre o problema subjacente, recomendamos adicionar informações de dentro da sua aplicação, capturando o erro, criando uma exceção Elixir você mesmo e adicionando-a ao span atual usando a função `set_error/2`.

<Warning>
  **NOTA:** `Appsignal.set_error/2` foi adicionado no AppSignal for Elixir 2.1.0. Se
  você estiver em uma versão inferior, use `Appsignal.set_error/3` em vez disso.
</Warning>

Em versões anteriores à 2.1.0, use `catch` e `Appsignal.send_error/3`:

<CodeGroup>
  ```elixir Elixir theme={null}
  try do
    raise "Exception!"
  catch
    kind, reason ->
      Appsignal.set_error(kind, reason, __STACKTRACE__)
  end
  ```
</CodeGroup>

A exceção será rastreada pelo AppSignal como qualquer outro erro, e permite
que você forneça tratamento de erro e fallbacks personalizados.

Se você não tiver um objeto de erro ao chamar `send_error`, mas ainda quiser reportar o cenário como um erro, também é possível inicializar uma struct de erro personalizada.

<CodeGroup>
  ```elixir Elixir theme={null}
  defmodule MyCustomError do
    defexception message: "default message" # Personalize se você chamá-lo sem uma mensagem personalizada
  end

  case Worker.do_something() do
    :ok -> IO.puts "yay!"
    {:error, message} ->
      Appsignal.set_error(:error, %MyCustomError{ message: message }, [])
  end
  ```
</CodeGroup>

**Nota:** Esta função só funciona quando há uma transação AppSignal ativa.
Caso contrário, o erro será ignorado.

Consulte
[`Appsignal.send_error/3`](#appsignalsend_error3) para enviar erros
sem uma transação AppSignal.

## Appsignal.send\_error/3

O AppSignal fornece um mecanismo para rastrear erros que ocorrem em código que não está em
um contexto web ou de background job, como Mix tasks. Isso é útil para
instrumentação que não cria automaticamente transações AppSignal para
fazer profile.

Você pode usar a função [`Appsignal.send_error/3`][hexdocs-send_error] para
enviar diretamente uma exceção para o AppSignal a partir de qualquer lugar do seu código sem
iniciar primeiro uma transação AppSignal.

<CodeGroup>
  ```elixir Elixir theme={null}
  try do
    raise "Exception!"
  catch
    kind, reason ->
      Appsignal.send_error(kind, reason, __STACKTRACE__)
  end
  ```
</CodeGroup>

Se você não tiver um objeto de erro ao chamar `send_error`, mas ainda quiser reportar o cenário como um erro, também é possível inicializar uma struct de erro personalizada.

<CodeGroup>
  ```elixir Elixir theme={null}
  defmodule MyCustomError do
    defexception message: "default message" # Personalize se você chamá-lo sem uma mensagem personalizada
  end

  case Worker.do_something() do
    :ok -> IO.puts "yay!"
    {:error, message} ->
      Appsignal.send_error(:error, %MyCustomError{ message: message }, [])
  end
  ```
</CodeGroup>

### Metadados adicionais

Para adicionar metadados ao erro enviado, passe uma função como o quarto argumento para
`Appsignal.send_errror/4`:

<CodeGroup>
  ```elixir Elixir theme={null}
  try do
    raise "Exception!"
  catch
    kind, reason ->
      Appsignal.send_error(kind, reason, __STACKTRACE__, fn span ->
        Appsignal.Span.set_attribute(span, "key", "value")
      end)
  end
  ```
</CodeGroup>

<Warning>
  **NOTA:** `Appsignal.send_error/4` foi adicionado no AppSignal for Elixir 2.1.0.
</Warning>

[hexdocs-set_error-2]: https://hexdocs.pm/appsignal/Appsignal.Instrumentation.html#set_error/2

[hexdocs-send_error]: https://hexdocs.pm/appsignal/Appsignal.Instrumentation.html#send_error/3