Acesso antecipadoSó por convite, e os SDKs ainda não foram publicados.Pedir um convite
Ir para o conteúdo
Docs

Android

Logs estruturados do seu app Android, em Kotlin ou Java. Sem dependências além da biblioteca padrão do Kotlin.

Celulares e tablets, em Kotlin ou Java

O SDK de Android requer Android 7.0 (API 24) ou posterior. Ele é escrito em Kotlin, não tem dependências além da biblioteca padrão do Kotlin (nada de OkHttp, coroutines ou AndroidX), e todas as funções também podem ser chamadas a partir de Java.

Prévia interna: este pacote ainda não foi publicado. Até lá, o Gradle não consegue baixar com.lyrelog:lyrelog-android: ele não está no Maven Central, e o repositório é privado e ainda não tem nenhuma release.

Instalação

A partir do Maven Central, no build.gradle.kts do módulo do seu app:

dependencies {
    implementation("com.lyrelog:lyrelog-android:0.1.0")
}

A biblioteca adiciona a permissão INTERNET ao manifest do seu app.

Primeiros passos

Inicie uma única vez, o mais cedo possível, no onCreate da sua Application. Uma segunda chamada enquanto ele está rodando é ignorada. Eventos registrados antes de start também são ignorados, mas setUser e setConsent chamados antes de start são guardados e aplicados quando ele roda.

import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Lyrelog

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Lyrelog.start(this, Configuration(
            apiKey = "lyr_ing_...",          // ingest-only: it can append events, never read them
        ))
    }
}

Declare a classe no manifest (<application android:name=".MyApp" ...>) se o seu app ainda não tiver uma Application.

Os eventos vão para https://ingest.lyrelog.com. Passe endpoint só para enviá-los para outro lugar. Ele é a URL base (um caminho .../v1/events:batch colado é removido) e precisa ser https; http simples só funciona para localhost, 127.0.0.1 ou ::1, e, no emulador, para 10.0.2.2 (veja Em desenvolvimento e testes). Com qualquer outro endpoint, nada é enviado e os eventos ficam no dispositivo.

Registrar eventos

Uma função por nível: trace, debug, info, notice, warning, error, critical, ou log(level, message, ...) com um Level.

Lyrelog.info("checkout_done", attrs = mapOf("items" to 3, "latency_ms" to ms))
Lyrelog.error("payment_declined", category = "checkout",
              attrs = mapOf("code" to 51), payload = mapOf("response" to raw))

Os atributos são um Map<String, Any?>: strings, números, booleanos, null, listas (com os itens enviados como strings) e maps aninhados em até 4 níveis. O payload é qualquer map, lista ou valor, para o detalhe que você só lê quando abre um evento.

Loggers para cada área

Um logger marca a sua category em todo evento, como uma tag de log do Android. Ele tem todos os níveis, além de log e captureError. É barato de criar e de manter, e registra no SDK que estiver rodando no momento da chamada.

val sync = Lyrelog.logger("sync")
sync.warning("sync_conflict", mapOf("records" to 2))

Usuários

Lyrelog.setUser(playerId)   // attached to every following event
Lyrelog.setUser(null)       // on sign-out

Lyrelog.sessionId traz o id da sessão atual, por exemplo para mostrar em uma tela de suporte.

O id do usuário não é salvo entre uma inicialização e outra: chame setUser de novo a cada inicialização, assim que souber quem é a pessoa.

Telas

Diga onde a pessoa está. O Lyrelog registra screen_viewed (área navigation) com a tela anterior e os segundos passados nela, e marca todo evento seguinte com um atributo screen.

override fun onResume() {
    super.onResume()
    Lyrelog.screen("Settings")
}

No Compose, chame a função a partir de um LaunchedEffect quando um destino for exibido. O evento traz screen, previous_screen e seconds_on_previous. Chamar screen de novo com o mesmo nome não registra nada. screen aceita attrs extras para o evento screen_viewed. Desative a marcação com attachScreen = false.

automaticScreens = true faz isso para toda Activity que vem para a frente, com o nome da classe (SettingsActivity). Vem desativado por padrão: apps com Compose e fragments têm muitas telas em uma só Activity, e um nome escolhido por você fica mais legível no painel.

Erros que você captura

try {
    store.purchase(product)
} catch (e: IOException) {
    Lyrelog.captureError(e, category = "store")
}

Capturar um erro envia o evento exception que todo SDK envia: nível error, os atributos error_type (o nome da classe) e error_message, e um payload com a descrição, até 60 frames, as causas (até 8, com 20 frames cada) e as exceções suprimidas. attrs acrescenta os seus; level muda o nível. Cada logger também tem captureError.

Os frames são como a VM os informa. Quando o app é minificado com R8, rode o retrace com o mapping file do build para obter os nomes originais.

Crashes

Uma exceção não capturada é gravada em disco na hora, na thread que está morrendo, junto com qualquer evento que ainda estivesse a caminho do disco. Depois ela é repassada ao handler que já existia (o diálogo de crash do sistema, ou outro crash reporter que tenha instalado um antes). Nada é enviado nesse momento: o processo está prestes a terminar.

A próxima inicialização faz o envio, com a hora em que aconteceu e na sessão que o crash encerrou, na área diagnostics, como os relatórios de crash do SDK de Swift, para que os crashes das duas plataformas fiquem juntos no painel:

EventoNívelO que ele traz
app_crashedcriticalerror_type, error_message, handled: false, mechanism: uncaught_exception, e um payload com a thread, os frames, as causas e as exceções suprimidas

Vem ativado por padrão; desative com captureCrashes = false. Crashes nativos e ANRs não são reportados.

Ambientes e plataforma

Ao iniciar, o SDK escolhe o ambiente: development quando o app é depurável (android:debuggable, todo build de debug), production nos outros casos.

Os seus próprios builds de debug enviam development, enquanto o painel abre em production: escolha development na barra superior para vê-los.

A plataforma é android. Sobrescreva qualquer um dos dois na configuração:

Configuration(
    apiKey = key,
    environment = if (BuildConfig.FLAVOR == "beta") "beta" else null,   // null = detected
    platform = null,
)

Qualquer nome serve: letras minúsculas, dígitos, - e _, até 32. Outros textos são convertidos em um nome válido (Staging EU vira staging-eu).

Lyrelog.start(this, Configuration(apiKey = key, consent = Consent.PENDING))
// later, when the person chooses:
Lyrelog.setConsent(Consent.GRANTED)   // sends, including what was kept while pending
Lyrelog.setConsent(Consent.DENIED)    // deletes everything and stops recording

PENDING mantém os eventos no dispositivo sem enviá-los. Nada é enviado a menos que o consentimento seja dado, inclusive o que uma inicialização anterior deixou. Iniciar com Consent.DENIED apaga tudo o que ainda estiver na fila de uma inicialização anterior e o id da instalação, e não registra nada. Um setConsent antes de start prevalece sobre Configuration.consent.

O consentimento não é salvo entre uma inicialização e outra: guarde você mesmo a escolha da pessoa e passe-a para start a cada vez.

Um app completo

Inicie com o consentimento guardado, defina a pessoa quando ela entrar e marque as telas:

import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Consent
import com.lyrelog.Lyrelog

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        val prefs = getSharedPreferences("settings", MODE_PRIVATE)
        val consent = when (prefs.getString("diagnostics", null)) {
            "granted" -> Consent.GRANTED
            "denied" -> Consent.DENIED
            else -> Consent.PENDING
        }
        Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", consent = consent))
    }
}

class HomeActivity : AppCompatActivity() {
    override fun onResume() {
        super.onResume()
        Lyrelog.screen("Home")
    }

    private fun signedIn(account: Account) {
        Lyrelog.setUser(account.id)
        Lyrelog.info("signed_in", category = "auth")
    }
}

fun choose(context: Context, allowed: Boolean) {
    context.getSharedPreferences("settings", Context.MODE_PRIVATE).edit()
        .putString("diagnostics", if (allowed) "granted" else "denied").apply()
    Lyrelog.setConsent(if (allowed) Consent.GRANTED else Consent.DENIED)
}

Esvaziar a fila e parar

Ir para segundo plano já esvazia a fila (quando a última Activity para; uma rotação não conta), então você raramente vai precisar fazer isso.

Lyrelog.flushInBackground()   // send now, without waiting
Lyrelog.flush()               // write everything to disk and send, waiting up to 5 seconds
Lyrelog.stop()                // send what's queued (up to 2 seconds), then stop
Lyrelog.stopNow()             // stop at once; what was logged goes with the next launch

flush e stop bloqueiam, então nunca os chame na thread principal. flush retorna true quando termina a tempo, e respeita um Retry-After pedido pelo servidor: não envia antes disso. Depois de stop, start pode ser chamado de novo.

Em desenvolvimento e testes

Não chame Lyrelog.start em testes unitários: tudo o que for registrado antes de start é ignorado, então o resto do seu código roda sem mudanças. mirrorToLogcat = true também imprime cada evento no logcat (tag Lyrelog) enquanto você trabalha.

Builds de debug enviam o ambiente development. Para enviar do emulador para um endpoint rodando no seu computador, use http://10.0.2.2 e a porta dele como endpoint (10.0.2.2 é o seu computador, visto pelo emulador), só no build de debug:

  • Permita http simples para 10.0.2.2. O Android o bloqueia, a menos que o app permita: adicione ao build de debug uma network security config que libere cleartext para esse endereço específico.
  • No Android 17, um app com target na API 37 também precisa de ACCESS_LOCAL_NETWORK para acessar um endereço privado como 10.0.2.2; sem ela, a conexão simplesmente dá timeout. Declare a permissão no manifest de debug (src/debug/AndroidManifest.xml) e conceda-a: adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK.

Isso é só para desenvolvimento local. A ingestão hospedada é um endereço https público e não precisa de nada disso.

Eventos verificados

Um evento verificado é um evento que não pode ter sido enviado por alguém que copiou a chave de ingestão pública de dentro de um app ou de uma página web. O que isso prova, e o que não prova, está em Eventos verificados.

Os eventos de um app Android são verificados com Key Attestation: o hardware seguro do celular prova que eles vêm do seu próprio app, assinado com o seu certificado, em um dispositivo real que não tem root nem bootloader desbloqueado. O Lyrelog faz a verificação nos próprios servidores; não há conta Google, Play Integrity nem projeto do Google Cloud envolvidos.

Vem ativado por padrão (attest em Configuration); configure no projeto:

  1. Em Project settings, na seção Verified events from your Android apps, adicione o seu pacote e a impressão digital SHA-256 de cada certificado que assina builds que enviam eventos: a chave de assinatura de apps do Play (Play Console, Test and release, App integrity) e, para builds que você mesmo assina, a que o ./gradlew signingReport mostra.
  2. No app, é só isso. Para desativar:
Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", attest = false))

Uma vez por instalação, o SDK cria uma chave no hardware seguro do celular (StrongBox ou o trusted execution environment) e pede ao dispositivo que a ateste; a partir daí, os lotes levam um token e chegam verificados (verified_by é key_attestation). O token dura 24 horas e é renovado em segundo plano antes de expirar. O envio nunca espera por isso: até o app ter um token, e sempre que algo falhar, os eventos são enviados sem verificação.

  • Emuladores nunca são verificados, e o SDK nem tenta neles.
  • Enquanto o projeto não tiver um app Android configurado, ou quando a chave for recusada ou o dispositivo não conseguir atestar, o SDK desativa a atestação naquela inicialização e avisa uma vez no logcat.
  • Um dispositivo que o servidor recusa (um celular com root, um bootloader desbloqueado, um certificado que o projeto não lista) tenta de novo um dia depois.
  • Recusar o consentimento apaga a chave atestada e o registro dela (noBackupFilesDir/lyrelog/attest.json).

Até isso estar configurado, os eventos chegam não verificados e contam para a cota diária de um endereço. Antes de fazer o projeto aceitar somente eventos verificados de android, confira no explorer se os eventos dos seus usuários reais chegam verificados: eventos de versões antigas, de emuladores e de dispositivos recusados ficariam retidos com um 425.

Os eventos que os seus próprios servidores enviam com uma chave de servidor, lyr_srv_..., são verificados. Nunca coloque uma chave de servidor em um app: qualquer coisa distribuída em um APK pode ser lida.

Para conferir, abra o explorer: um evento aberto diz isso em Context, na linha Sender: Verified, Key Attestation ou Not verified, public key.

Veja Eventos verificados para saber quem verifica o quê e como funciona a cota diária.

A partir de Java

Todas as funções de Lyrelog são estáticas a partir de Java, com sobrecargas para os argumentos opcionais:

Lyrelog.start(this, new Configuration("lyr_ing_..."));
Lyrelog.info("checkout_done");
Lyrelog.captureError(e, "store");

Configuration e as funções de um logger também têm sobrecargas, então os argumentos finais podem ser omitidos (logger.warning("sync_conflict"), logger.warning("sync_conflict", attrs)).

Configuração

OpçãoPadrãoSignificado
apiKeyobrigatóriaA chave de ingestão do projeto
endpointhttps://ingest.lyrelog.comA URL base; um caminho /v1/... colado é removido. Só https, http apenas para localhost e para o 10.0.2.2 do emulador
consentConsent.GRANTEDPENDING, GRANTED ou DENIED
minimumLevelLevel.DEBUGEventos abaixo dele nunca chegam ao disco
flushIntervalMillis15 sDe quanto em quanto tempo o envio roda enquanto uma Activity está iniciada
maxBatchBytes512 KiBUm lote fecha no limite que chegar primeiro (mantido dentro de 4 MiB)
maxBatchEvents500No máximo 2.000
maxDiskBytes20 MBLimite da fila em disco, os mais antigos saem primeiro
maxEventAgeMillis7 diasEventos mais antigos na fila são descartados
sessionTimeoutMillis30 minTempo de inatividade que inicia uma nova sessão
environmentdetectadoQualquer nome válido, ou null
platformandroidQualquer nome válido, ou null
appVersiono versionName do appEnviado como resource.app_version
redactedKeysnull: DEFAULT_REDACTED_KEYSNomes de chave a ocultar; a sua lista substitui os padrões, uma lista vazia desativa a ocultação
captureCrashestrueRegistra exceções não capturadas, enviadas na próxima inicialização
attachScreentrueMarca os eventos com a tela atual
automaticScreensfalseRegistra screen_viewed para cada Activity, com o nome da classe
attesttrueProva o app com Key Attestation para que os eventos cheguem verificados, assim que o projeto listar o pacote e o certificado
mirrorToLogcatfalseImprime também cada evento no logcat (tag Lyrelog)
storageDirectorynoBackupFilesDir/lyrelogOnde a fila fica

Entrega e limites

Nunca bloqueiaRegistrar um log copia o evento e retorna; um único writer em segundo plano o grava em disco e nunca espera pela rede.
Sobrevive a encerramentos forçados e à falta de conexãoUma fila em noBackupFilesDir/lyrelog, limitada a 20 MB e 7 dias. O que chegou ao disco sobrevive a um crash, a um encerramento forçado ou a dias sem conexão; os eventos ainda a caminho do writer (milissegundos) são gravados pelo handler de crash, ou se perdem se o processo for encerrado à força de uma vez. A pasta nunca entra em backup, então um celular restaurado não reenvia os eventos de outro dispositivo.
Quando enviaA cada 15 s enquanto uma Activity está iniciada, e uma vez quando o app vai para segundo plano. Em segundo plano nada roda por intervalo: o que sobrar sai na próxima inicialização ou na próxima vez que o app vier para a frente.
LotesAté 500 eventos ou 512 KiB por requisição, com gzip. Um evento com mais de 1 MiB depois de codificado é descartado e contado.
Novas tentativas1 s, dobrando até 5 min, com full jitter, respeitando o Retry-After. Qualquer outro 4xx descarta o lote, um 3xx (um redirecionamento, nunca seguido) o descarta, e uma chave revogada (401, 403) interrompe o envio até a próxima inicialização e mantém os eventos. Um lote que o servidor continua recusando enquanto os outros passam vai para o fim da fila e depois é descartado.
Cota mensalQuando uma organização Free já usou os eventos do mês, o servidor responde 429. Os eventos ficam na fila em disco e saem assim que o servidor voltar a aceitá-los, dentro dos limites de 20 MB e 7 dias. O SDK registra um aviso no logcat, e só registra outro depois que algum lote tiver sido aceito nesse meio-tempo.
Descartes visíveisOs eventos perdidos pelos limites viram um único aviso lyrelog_events_dropped (área lyrelog) com a contagem.
Os próprios problemasUm endpoint errado, um 404, linhas rejeitadas ou um endpoint que não responde vão uma vez por inicialização para o logcat, tag Lyrelog, no nível debug.
ContextoId do app (o nome do pacote), version name, version code, android, a versão do Android, o dispositivo (Google Pixel 9), locale, ambiente, plataforma android, id da sessão (novo após 30 min de inatividade) e id da instalação.
SegredosValores sob chaves cujo nome é ou termina com authorization, cookie, password, token, secret, apikey e o resto da lista compartilhada viram "[redacted]", em qualquer profundidade, antes de qualquer corte.
LimitesStrings longas são cortadas no limite de um caractere, atributos extras são contados em lyrelog_dropped_attrs, e payloads com mais de 64 KiB são resumidos como {"lyrelog_truncated": true, "bytes": N, "preview": "..."}.

Mude a lista com redactedKeys: a sua lista substitui os padrões, e uma lista vazia desativa a ocultação. Para acrescentar itens:

Lyrelog.start(this, Configuration(
    apiKey = "lyr_ing_...",
    redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "pin",
))

Segurança dos dados no Play

No formulário de segurança dos dados do Play Console, declare o que o seu app envia pelo Lyrelog:

  • App info and performance: Crash logs, Diagnostics (App functionality, e Analytics se você usar dessa forma). Coletados, não compartilhados.
  • Device or other IDs: o id da instalação, um UUID aleatório que não é o id de publicidade, não entra em backup e é apagado quando o consentimento é negado. Não vinculado à pessoa, a menos que você também chame setUser.
  • App activity > App interactions: se você registrar telas (screen_viewed) ou toques.
  • Qualquer outra coisa que os seus attrs ou payload levem (emails, compras...), na categoria correspondente.

Os dados são criptografados em trânsito (https). O servidor acrescenta o país do endereço de envio; o endereço em si não é armazenado.