Firebase Crashlytics — o que é, falhas e diagnóstico de erros

O que é Firebase Crashlytics

Firebase Crashlytics é um serviço gratuito do Google para monitorar a estabilidade de aplicativos móveis, adquirido pelo Google em 2017 junto com a empresa Fabric. O Crashlytics coleta automaticamente informações sobre cada falha do aplicativo, agrupa falhas idênticas por assinatura de pilha e as exibe no console do Firebase com priorização pelo número de usuários afetados.

História e evolução

O Crashlytics foi lançado em 2011 como parte da plataforma Fabric e rapidamente se tornou o padrão de facto para relatórios de falhas no iOS. Após sua aquisição pelo Google em 2017 por estimados 2 bilhões de dólares (toda a Fabric), o Crashlytics foi integrado ao SDK do Firebase. A versão 18.0.0 (2021) adicionou suporte ao Kotlin Multiplatform, e a versão 19.0.0 (2024) introduziu a coleta automática de ANR no Android sem configuração adicional. De acordo com o Google (2026), o Crashlytics processa mais de 10 bilhões de falhas mensalmente.

Limites gratuitos do Crashlytics

O Crashlytics é fornecido gratuitamente com um limite de 500 mil sessões por dia por projeto do Firebase. Isso é suficiente para a maioria dos aplicativos — de acordo com o Google (2026), 95% dos projetos não excedem o limite. Quando excedido, a coleta de dados não para, mas os relatórios param de ser atualizados até o dia seguinte. Para projetos de alto tráfego, os planos Spark e Blaze do Firebase estão disponíveis — o Crashlytics permanece gratuito em ambos os planos, e o limite de sessões é contado separadamente.

Como o Crashlytics detecta e coleta falhas

O mecanismo de coleta do Crashlytics é baseado na interceptação de exceções no nível da plataforma e do runtime. No Android, o SDK instala um UncaughtExceptionHandler que captura todas as exceções não tratadas de Kotlin e Java. No iOS, o Crashlytics usa o NSSetUncaughtExceptionHandler para Objective-C/Swift e seu próprio manipulador de exceções Mach para falhas de código nativo.

Tipos de falhas interceptadas

O Crashlytics distingue cinco tipos de falhas: fatal (falhas fatais), non-fatal (exceções não fatais passadas manualmente), ANR (Android — aplicativo não responde), signal (sinais do SO — SIGSEGV, SIGABRT) e OOM (falta de memória no iOS). Cada tipo é tratado por um mecanismo separado e exibido no console com o rótulo correspondente.

Formato do relatório de falha

Cada relatório do Crashlytics contém informações abrangentes: um rastreamento de pilha completo com nomes de classe e números de linha, versão do aplicativo (versionName + versionCode), modelo do dispositivo, versão do SO, memória disponível, orientação da tela e tempo desde a inicialização. Se o Firebase Analytics estiver conectado, o relatório também inclui o caminho dos últimos 50 eventos do usuário antes da falha — isso é fundamental para a reprodução da falha.

class CrashlyticsHelper {
    fun logNonFatal(error: Throwable) {
        FirebaseCrashlytics.getInstance()
            .log("Non-fatal: user action = payment_failed")
        FirebaseCrashlytics.getInstance()
            .recordException(error)
    }

    fun setUserContext(userId: String) {
        FirebaseCrashlytics.getInstance()
            .setUserId(userId)
        FirebaseCrashlytics.getInstance()
            .setCustomKey("subscription", "premium")
    }
}

Integração do Crashlytics em um projeto Android

Conectar o Crashlytics a um aplicativo Android requer adicionar duas dependências no build.gradle e configurar o plugin Google Services. O SDK ativa automaticamente os relatórios de falhas na inicialização do Firebase sem código adicional. Para o funcionamento correto, também são necessários o plugin google-services e o arquivo google-services.json do console do Firebase.

// build.gradle (nível de projeto)
plugins {
    id "com.google.gms.google-services" version "4.4.0"
}

// build.gradle (nível de aplicativo)
plugins {
    id "com.google.firebase.crashlytics"
}

dependencies {
    implementation(platform("com.google.firebase:firebase-bom:33.1.0"))
    implementation("com.google.firebase:firebase-crashlytics-ktx")
    implementation("com.google.firebase:firebase-analytics-ktx")
}

Configuração do plugin Crashlytics

O plugin com.google.firebase.crashlytics realiza duas tarefas: gera um ID de compilação único (build ID) para mapeamento de pilhas ofuscadas e cria automaticamente recursos para o SDK do Crashlytics. Sem o plugin, as falhas serão marcadas como "unmapped" — você verá apenas nomes de classe ofuscados (a.b.c) sem conseguir encontrar o código-fonte. O plugin é adicionado ao build.gradle raiz e ao build.gradle do módulo do aplicativo.

Verificação da integração

Para testar a integração do Crashlytics, é usado o método especial forceCrash(), que gera uma exceção de teste. Este método não está disponível em compilações de produção. Após executar uma falha de teste, o relatório aparece no console do Firebase dentro de 1 a 5 minutos. Se o relatório não aparecer, verifique se o google-services.json corresponde ao pacote do aplicativo e se não há flags no AndroidManifest desativando a coleta de dados.

Análise de falhas e agrupamento de relatórios

O console do Crashlytics fornece dois níveis de visualização: uma lista de todas as falhas (Issues) agrupadas por tipo de falha, e um relatório detalhado de cada Issue com rastreamento, estatísticas e dados personalizados. Cada Issue combina todas as falhas com a mesma assinatura — o mesmo tipo de exceção e rastreamento de pilha correspondente.

Issues e agrupamento

O agrupamento de falhas é um recurso chave do Crashlytics. Em vez de mostrar milhares de falhas individuais, o serviço as combina em Issues com base em uma impressão digital (fingerprint) — uma soma de verificação do rastreamento de pilha. Um Issue pode conter de 1 a vários milhões de falhas. Cada Issue mostra: o número de ocorrências fatais, o número de usuários únicos, a versão do aplicativo em que a falha apareceu e a porcentagem de usuários que encontraram o problema.

De acordo com o Google (2026), em média 20% dos Issues representam 80% de todas as falhas fatais do aplicativo (princípio de Pareto). O Crashlytics classifica automaticamente os Issues por gravidade — quanto mais usuários afetados, maior a prioridade. Isso permite que o desenvolvedor corrija primeiro os problemas mais difundidos.

Estatísticas por versões

O Crashlytics rastreia a estabilidade de cada versão do aplicativo separadamente. O gráfico de usuários sem falhas (crash-free users) mostra a porcentagem de usuários que não encontraram uma falha fatal em cada versão. Se a porcentagem cair abaixo de um limiar (padrão 99%) na atualização, o Crashlytics envia uma notificação por e-mail e no console do Firebase. Isso permite reverter rapidamente uma versão problemática ou lançar um hotfix.

Chaves personalizadas, registros e Breadcrumbs

O Crashlytics fornece três mecanismos para enriquecer os relatórios com contexto: chaves personalizadas (keys) para dados estruturados, registros (logs) para rastreamento textual e Breadcrumbs do Analytics para o caminho do usuário. Todos os três tipos de dados são anexados ao relatório de falha e visíveis em seu cartão de detalhes.

Chaves personalizadas

As Custom Keys são pares chave-valor enviados com cada falha. Máximo de 64 chaves por aplicativo, cada chave é uma string de até 1024 caracteres. As chaves são úteis para marcar o estado do aplicativo: nível de assinatura, status de autenticação, última tela, se a VPN está ativada. Os valores são sobrescritos — uma nova chave com o mesmo nome substitui a anterior.

Registro de eventos

Os Custom Logs são mensagens de texto que o Crashlytics armazena em um buffer circular de 64 KB. Os registros são automaticamente anexados à próxima falha. Se nenhuma falha ocorrer, os registros não são enviados ao servidor (não consomem tráfego). O registro é usado para capturar as etapas do usuário antes da falha: "payment_processing_started", "api_call_initiated", "response_received_200".

class PaymentViewModel {
    fun processPayment(amount: Double) {
        FirebaseCrashlytics.getInstance().log("Payment started: amount=$amount")

        FirebaseCrashlytics.getInstance().setCustomKey("last_screen", "payment_screen")
        FirebaseCrashlytics.getInstance().setCustomKey("subscription_tier", "basic")

        try {
            paymentGateway.charge(amount)
        } catch (e: NetworkException) {
            FirebaseCrashlytics.getInstance().recordException(e)
        }
    }
}

Breadcrumbs do Analytics

Se o Firebase Analytics estiver conectado ao projeto, o Crashlytics recebe automaticamente Breadcrumbs — os últimos 50 eventos de análise antes da falha. Cada breadcrumb contém o nome do evento e seus parâmetros. Isso permite reconstruir a sequência exata de ações que levaram à falha: o usuário abriu a tela → adicionou produto → foi para o pagamento → ocorreu a falha. Os Breadcrumbs são exibidos no cartão do Issue em uma guia separada "Logs".

Melhores práticas para trabalhar com falhas

O Crashlytics é mais eficaz quando o contexto e o processo de tratamento de Issues estão configurados corretamente. A prática mostra que as equipes que implementaram um fluxo de trabalho de gerenciamento de falhas reduzem o tempo de correção de bugs críticos em 60% (dados do Google, 2026).

Priorização de Issues

Nem todas as falhas são igualmente importantes. A priorização por número de usuários e frequência ajuda a focar nos problemas mais críticos. Regra geral: corrigir Issues que afetam mais de 0,1% dos usuários em até 24 horas. Issues com ocorrências únicas (< 0,01%) podem ser adiadas até o próximo lançamento planejado. O Crashlytics marca automaticamente regressões — Issues que foram corrigidas, mas reapareceram em uma nova versão.

Integração com CI/CD

A API do Crashlytics permite integrar relatórios de falhas no pipeline de CI/CD através da API REST ou Firebase CLI. A cada novo lançamento, você pode verificar automaticamente se a porcentagem de usuários sem falhas excede um limiar. Se o limiar for excedido, o CI/CD bloqueia a implantação e envia uma notificação à equipe. O Firebase CLI suporta o comando firebase crashlytics:builds:upload para carregar arquivos de mapeamento ProGuard/R8 — sem eles, as pilhas ficarão ilegíveis.

De acordo com o Google (2026), os aplicativos que usam verificação automática de limiares de usuários sem falhas no CI/CD lançam 40% menos regressões em produção. Limiar recomendado: usuários sem falhas >= 99,5% para lançamentos críticos e >= 99,0% para lançamentos normais.