React Native
Logs estruturados, erros de JavaScript e crashes do seu app React Native, por cima dos SDKs de Swift e Android.
O SDK de React Native é um TurboModule fino por cima dos SDKs de Swift e Android. Os SDKs nativos mantêm a fila em disco, enviam em lotes, tentam de novo, mantêm as sessões e reportam os crashes nativos. Este pacote acrescenta o que só o JavaScript enxerga: erros não capturados, rejeições de promise não tratadas, erros de renderização do React e as telas do React Navigation.
Ele requer React Native 0.80 ou posterior com a New Architecture, e React 19. Os apps rodam no iOS 16 ou posterior e no Android 7.0 (API 24) ou posterior.
Prévia interna: este pacote ainda não foi publicado. Até lá, @lyrelog/react-native não está
no npm, e os SDKs nativos sobre os quais ele é construído também não foram publicados.
Instalação
pnpm add @lyrelog/react-native
cd ios && pod installNo iOS, o pod traz o pacote Swift Lyrelog pelo Swift Package Manager. Defina o deployment
target do seu app (e a linha platform :ios do Podfile) como 16.0 ou posterior. No Android, o
Gradle baixa com.lyrelog:lyrelog-android do Maven Central, que adiciona a permissão
INTERNET.
Primeiros passos
Inicie uma única vez, o mais cedo possível, no index.js, antes do AppRegistry. Uma segunda
chamada mantém a primeira configuração. Eventos registrados antes de init são ignorados, mas
setUser e setConsent chamados antes de init são guardados e aplicados quando ele roda.
import { AppRegistry } from "react-native";
import { Lyrelog } from "@lyrelog/react-native";
import App from "./src/App";
Lyrelog.init({
apiKey: "lyr_ing_...", // ingest-only: it can append events, never read them
});
AppRegistry.registerComponent("main", () => App);Os eventos vão para https://ingest.lyrelog.com. Passe endpoint só para enviá-los para outro
lugar. Ele precisa ser https; http simples só funciona para localhost, 127.0.0.1 ou ::1
(o simulador do iOS) e, no emulador do Android, para 10.0.2.2.
Nada no SDK lança exceções no seu app. Em um build de desenvolvimento, uma chave faltando ou um
módulo nativo faltando (o app não foi recompilado depois da instalação) é avisado uma vez com
console.warn.
Registrar eventos
Uma função por nível: trace, debug, info, notice, warning, error, critical, ou
log(level, message, options).
Lyrelog.info("checkout_done", { attrs: { items: 3, latency_ms: ms } });
Lyrelog.error("payment_declined", {
category: "checkout",
attrs: { code: 51 },
payload: { response },
});Os atributos são campos pequenos para filtrar e montar gráficos: strings, números, booleanos,
null, arrays e objetos aninhados em até 4 níveis. O payload é qualquer JSON, para o detalhe que
você só lê quando abre um evento. minimumLevel (padrão debug) descarta os níveis mais baixos
antes que eles cheguem ao código nativo.
Loggers para cada área
Um logger marca a sua category em todo evento. Ele tem todos os níveis, além de log e
captureException.
const sync = Lyrelog.logger("sync");
sync.warning("sync_conflict", { attrs: { records: 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.
Telas
Com o React Navigation, faça o spread de trackNavigation no container:
import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native";
import { trackNavigation } from "@lyrelog/react-native";
const navigationRef = createNavigationContainerRef();
export default function App() {
return (
<NavigationContainer ref={navigationRef} {...trackNavigation(navigationRef)}>
{/* your navigators */}
</NavigationContainer>
);
}Cada tela exibida registra screen_viewed (área navigation) com screen, previous_screen e
seconds_on_previous, e todo evento seguinte é marcado com um atributo screen. O nome é o da
rota; passe name: (route) => ... para escolher outro, ou retorne undefined para ignorar uma
rota. Os seus próprios onReady e onStateChange vão nas opções e rodam depois dos do Lyrelog.
Sem o React Navigation, chame Lyrelog.screen("Settings"), ou useLyrelogScreen("Settings") no
componente da tela. Chamar screen de novo com o mesmo nome não registra nada. Desative a
marcação com attachScreen: false.
Erros que você captura
try {
await store.purchase(product);
} catch (error) {
Lyrelog.captureException(error, { category: "store" });
}Capturar uma exceção envia o evento exception que todo SDK envia: nível error, os atributos error_type e
error_message, e um payload com o nome, a mensagem, a stack e até 3 causas (error.cause).
attrs acrescenta os seus; level muda o nível. Em JavaScript, qualquer coisa pode ser lançada:
uma string ou um objeto também são registrados.
As stacks são como o Hermes as informa. Em um build de release, elas apontam para dentro do bundle: guarde o source map do build para conseguir lê-las.
Erros que ninguém capturou
Com captureErrors (ativado por padrão), o SDK se conecta ao tratamento de erros do React Native:
| O que acontece | Evento | Nível, área | mechanism |
|---|---|---|---|
| Um erro fatal de JavaScript, como um throw em um timer ou em um event handler | app_crashed | critical, diagnostics | js_fatal |
| Um erro de renderização que nenhum error boundary capturou | app_crashed | critical, diagnostics | react_render |
Um erro não fatal reportado ao ErrorUtils | exception, handled: false | error | js_error |
| Uma rejeição de promise não tratada | exception, handled: false | error | unhandled_rejection |
Um erro fatal é gravado em disco antes de o app fechar, esperando até 1,5 segundo, e é enviado
nesse momento se possível; senão, na próxima inicialização. Ele é um app_crashed na área
diagnostics, como os relatórios de crash nativos, para que os crashes de JavaScript e os nativos
fiquem juntos no painel.
Cada erro é registrado uma vez. Erros não capturados que não são fatais têm um limite de 10 por
minuto, e o mesmo erro no máximo uma vez a cada 10 segundos; Lyrelog.skippedErrors conta o que
ficou de fora. Os handlers que já existiam continuam rodando: a tela vermelha e o LogBox em
desenvolvimento, o crash em release.
Error boundaries
import { LyrelogErrorBoundary } from "@lyrelog/react-native";
<LyrelogErrorBoundary
category="feed"
fallback={({ error, reset }) => <Retry onPress={reset} />}
>
<Feed />
</LyrelogErrorBoundary>Um erro de renderização dentro do boundary é registrado como exception com
mechanism: error_boundary e a component stack do React (component_stack no payload), e o
fallback é exibido no lugar. onError é chamado depois do registro. Sem um fallback, ele não
renderiza nada depois de um erro.
Crashes nativos
Ficam por conta dos SDKs nativos (captureCrashes, ativado por padrão), enviados na próxima
inicialização na área diagnostics: no Android, as exceções da JVM não capturadas como
app_crashed; no iOS, os relatórios do MetricKit, com crashes como app_crashed e travamentos
como app_hung. Veja crashes no Android e
crashes e travamentos no Swift.
No Android, um erro fatal de JavaScript encerra o app com uma exceção Java. Assim que o
app_crashed do JavaScript está em disco, essa exceção é ignorada pelo registro do SDK de
Android, para que o mesmo crash não seja reportado duas vezes.
Ambientes e plataforma
O ambiente é o do SDK nativo: no iOS, development em builds de debug, testflight no
TestFlight, production nos outros casos; no Android, development quando o app é depurável,
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 é ios ou android. Sobrescreva qualquer um dos dois:
Lyrelog.init({
apiKey: key,
environment: isBeta ? "beta" : undefined, // undefined = detected
});Os eventos identificam este pacote e o SDK nativo por baixo dele (sdk é
lyrelog-react-native/0.1.0 lyrelog-swift/0.1.0 ou lyrelog-react-native/0.1.0 lyrelog-android/0.1.0).
Consentimento
Lyrelog.init({ apiKey: key, consent: "pending" });
// later, when the person chooses:
Lyrelog.setConsent("granted"); // sends, including what was kept while pending
Lyrelog.setConsent("denied"); // deletes everything and stops recordingpending mantém os eventos no dispositivo sem enviá-los. Nada é enviado a menos que o
consentimento seja dado. O consentimento não é salvo entre uma inicialização e outra: guarde você
mesmo a escolha da pessoa (por exemplo, com o AsyncStorage) e passe-a para init a cada vez.
Atestação
attest (ativado por padrão) prova o app com App Attest no iOS e Key Attestation no Android,
para que os eventos sejam armazenados como verificados. Veja
Eventos verificados.
Opções
| Opção | Padrão | O quê |
|---|---|---|
apiKey | A chave de ingestão do projeto, lyr_ing_... | |
endpoint | https://ingest.lyrelog.com | Para onde os eventos vão |
consent | granted | granted, pending ou denied |
environment | detectado | Qualquer nome |
platform | ios / android | Qual parte do produto envia |
minimumLevel | debug | Níveis mais baixos são descartados |
flushIntervalMs | 15000 | De quanto em quanto tempo os eventos na fila são enviados em primeiro plano |
sessionTimeoutMs | 30 minutos | Uma nova sessão depois desse tempo sem nenhum evento |
maxDiskBytes | 20 MB | O que pode ficar esperando no dispositivo; os mais antigos saem primeiro |
redactKeys | DEFAULT_REDACT_KEYS | Chaves de atributos e do payload cujos valores são substituídos. A sua lista substitui os padrões; [] desativa a ocultação |
captureErrors | true | Erros de JavaScript que ninguém capturou |
captureCrashes | true | Crashes nativos |
attachScreen | true | O atributo screen em todo evento |
attest | true | App Attest e Key Attestation |
mirrorToNativeLog | false | Imprime também cada evento no console do Xcode ou no logcat |
Esvaziar a fila e parar
Ir para segundo plano já esvazia a fila, então você raramente vai precisar fazer isso.
await Lyrelog.flush(); // write everything to disk and try to send now
await Lyrelog.close(); // send what's queued (up to 2 seconds), then stopDepois de close, init pode ser chamado de novo.