Android
Logs estruturados do seu app Android, em Kotlin ou Java. Sem dependências além da biblioteca padrão do Kotlin.
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-outLyrelog.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:
| Evento | Nível | O que ele traz |
|---|---|---|
app_crashed | critical | error_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).
Consentimento
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 recordingPENDING 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 launchflush 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_NETWORKpara acessar um endereço privado como10.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:
- 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 signingReportmostra. - 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ção | Padrão | Significado |
|---|---|---|
apiKey | obrigatória | A chave de ingestão do projeto |
endpoint | https://ingest.lyrelog.com | A URL base; um caminho /v1/... colado é removido. Só https, http apenas para localhost e para o 10.0.2.2 do emulador |
consent | Consent.GRANTED | PENDING, GRANTED ou DENIED |
minimumLevel | Level.DEBUG | Eventos abaixo dele nunca chegam ao disco |
flushIntervalMillis | 15 s | De quanto em quanto tempo o envio roda enquanto uma Activity está iniciada |
maxBatchBytes | 512 KiB | Um lote fecha no limite que chegar primeiro (mantido dentro de 4 MiB) |
maxBatchEvents | 500 | No máximo 2.000 |
maxDiskBytes | 20 MB | Limite da fila em disco, os mais antigos saem primeiro |
maxEventAgeMillis | 7 dias | Eventos mais antigos na fila são descartados |
sessionTimeoutMillis | 30 min | Tempo de inatividade que inicia uma nova sessão |
environment | detectado | Qualquer nome válido, ou null |
platform | android | Qualquer nome válido, ou null |
appVersion | o versionName do app | Enviado como resource.app_version |
redactedKeys | null: DEFAULT_REDACTED_KEYS | Nomes de chave a ocultar; a sua lista substitui os padrões, uma lista vazia desativa a ocultação |
captureCrashes | true | Registra exceções não capturadas, enviadas na próxima inicialização |
attachScreen | true | Marca os eventos com a tela atual |
automaticScreens | false | Registra screen_viewed para cada Activity, com o nome da classe |
attest | true | Prova o app com Key Attestation para que os eventos cheguem verificados, assim que o projeto listar o pacote e o certificado |
mirrorToLogcat | false | Imprime também cada evento no logcat (tag Lyrelog) |
storageDirectory | noBackupFilesDir/lyrelog | Onde a fila fica |
Entrega e limites
| Nunca bloqueia | Registrar 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ão | Uma 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 envia | A 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. |
| Lotes | Até 500 eventos ou 512 KiB por requisição, com gzip. Um evento com mais de 1 MiB depois de codificado é descartado e contado. |
| Novas tentativas | 1 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 mensal | Quando 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íveis | Os eventos perdidos pelos limites viram um único aviso lyrelog_events_dropped (área lyrelog) com a contagem. |
| Os próprios problemas | Um 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. |
| Contexto | Id 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. |
| Segredos | Valores 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. |
| Limites | Strings 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
attrsoupayloadlevem (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.