SDKs
O mesmo modelo em todas as linguagens. Escolha a sua, ou envie eventos por HTTP.
Os SDKs do Lyrelog compartilham um mesmo modelo (níveis, áreas, atributos, usuários) e usam os mesmos nomes quando a linguagem permite, com a convenção de maiúsculas e minúsculas de cada uma. A tabela mostra onde eles diferem.
Apps
Web e servidores
Qualquer outra coisa
Apps
| Swift | Android | React Native | Flutter | |
|---|---|---|---|---|
| Iniciar | Lyrelog.start(Configuration(...)) | Lyrelog.start(context, Configuration(...)) | Lyrelog.init({...}) | Lyrelog.start(LyrelogConfiguration(...)) |
| Registrar log | Lyrelog.info("checkout_done", attrs:) | Lyrelog.info("checkout_done", attrs = ...) | Lyrelog.info("checkout_done", { attrs }) | Lyrelog.info('checkout_done', attrs: {...}) |
| Logger de uma área | Lyrelog.Logger(category: "checkout") | Lyrelog.logger("checkout") | Lyrelog.logger("checkout") | Lyrelog.logger('checkout') |
| Usuário | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser('u_123') |
| Tela | Lyrelog.screen("Settings") | Lyrelog.screen("Settings") | trackNavigation(ref), ou Lyrelog.screen("Settings") | LyrelogNavigatorObserver(), ou Lyrelog.screen('Settings') |
| Requisições | session.loggedData(for:) | |||
| Capturar um erro | Lyrelog.captureError(error) | Lyrelog.captureError(e) | Lyrelog.captureException(error) | Lyrelog.captureError(e, stackTrace: s) |
| Erros não capturados e crashes | Crashes e travamentos do MetricKit, automático | Exceções não capturadas, automático, enviadas na próxima inicialização | Erros fatais de JavaScript e de renderização como crashes, rejeições e outros erros, mais os crashes nativos; automático | Erros de Dart (FlutterError, PlatformDispatcher), mais os crashes nativos; automático |
| Esvaziar a fila | await Lyrelog.flush() | Lyrelog.flush() (fora da thread principal) | await Lyrelog.flush() | await Lyrelog.flush() |
| Parar | await Lyrelog.stop() | Lyrelog.stop() | await Lyrelog.close() | await Lyrelog.stop() |
Web e servidores
| JavaScript | Python | Go | JVM | |
|---|---|---|---|---|
| Iniciar | Lyrelog.init({...}) | lyrelog.init(...) | lyrelog.New(lyrelog.Config{...}) | Lyrelog.start(Configuration(...)) |
| Registrar log | client.info("checkout_done", { attrs }) | lyrelog.info("checkout_done", attrs=) | client.Info("checkout_done", lyrelog.Attrs{}) | Lyrelog.info("checkout_done", attrs = ...) |
| Logger de uma área | client.logger("checkout") | lyrelog.logger("checkout") | client.Logger("checkout") | Lyrelog.logger("checkout") |
| Usuário | client.setUser("u_123") | lyrelog.set_user("u_123") | client.SetUser("u_123") | Lyrelog.setUser("u_123"), ou Lyrelog.userScope(id) para uma thread |
| Tela | client.screen("Settings") | |||
| Capturar um erro | client.captureException(err) | lyrelog.capture_exception(exc) | client.CaptureError(err) | Lyrelog.captureError(e) |
| Erros não capturados e crashes | window e Node, automático | o seu próprio sys.excepthook | o seu próprio recover | captureUncaught = true (desativado por padrão) |
| Esvaziar a fila | await client.flush() | lyrelog.flush() | client.Flush(ctx) | Lyrelog.flush() |
| Parar | await client.close() | lyrelog.shutdown() | client.Close() | Lyrelog.close() (um shutdown hook faz isso ao sair) |
| Logging padrão | lyrelog.LoggingHandler() | lyrelog.NewSlogHandler(client, nil) | LyrelogAppender para Logback |
Os SDKs de apps também podem copiar cada evento para o log da própria plataforma, para que ele
apareça no Xcode e no logcat: mirrorToOSLog em Swift, mirrorToLogcat no Android,
mirrorToNativeLog em React Native e mirrorToConsole em Flutter.
Prévia interna
Nenhum dos SDKs foi publicado ainda, então por enquanto todo comando de instalação destas
páginas falha: pnpm add, flutter pub add e uv add não encontram o pacote, Gradle e Maven
não encontram nada no Maven Central, e o Swift Package Manager e o go get não conseguem acessar
os repositórios privados. Cada página mostra a linha como ela vai ser quando os SDKs forem
publicados.
O que todo SDK faz por você
Os SDKs de React Native e Flutter enviam pelo SDK de Swift no iOS e pelo SDK de Android no Android, então tudo o que vem abaixo vale para eles, feito do jeito nativo. O SDK da JVM roda o motor do SDK de Android, configurado para um servidor.
- Nunca bloqueia nem lança exceções no seu código. Registrar um log copia o evento para uma fila e retorna; um worker em segundo plano faz o envio.
- Agrupa em lotes de até 500 eventos ou cerca de 512 KiB por requisição, uma linha NDJSON por evento, com gzip quando a plataforma permite.
- Envia para
https://ingest.lyrelog.com, a menos que você defina outroendpoint. O endpoint é a URL base: se você colar o endereço inteiro.../v1/events:batch, o SDK remove o caminho. Um endpoint errado (um404, ou um redirecionamento) é reportado como um aviso no log do próprio SDK. - Tenta de novo em falhas temporárias (
408,425,429, 5xx, erros de rede) com backoff exponencial (1 s, dobrando até 5 min) e jitter, respeitando oRetry-After, inclusive quando você chamaflushou fecha o cliente. Todos os SDKs, exceto o de Python, usam full jitter (uma espera aleatória entre 0 e o teto); o de Python usa equal jitter (entre metade do teto e o teto). - Descarta um lote recusado. Qualquer outro 4xx (
400,413,415...) significa que o próprio lote está errado, então ele é descartado em vez de reenviado. Uma chave recusada (401,403) interrompe o envio até o app ou o processo reiniciar, e mantém os eventos. Redirecionamentos nunca são seguidos: uma resposta 3xx descarta o lote e registra um aviso, porque significa que o endpoint está errado. - Mantém os eventos diante de um
429. Quando uma organização Free já usou os eventos do mês, ou um projeto passa do limite de taxa, o SDK guarda o lote e tenta de novo depois doRetry-After(veja API HTTP). Os SDKs de apps (Swift, Android, React Native, Flutter) os guardam em disco entre uma inicialização e outra. O SDK da JVM também os guarda em disco, em um diretório temporário do processo, a menos que você informe umstorageDirectory. JavaScript, Python e Go os guardam em memória. Em todos os casos, os limites abaixo continuam valendo. - Limita o que fica esperando: 10.000 eventos e 16 MiB em memória por padrão em JavaScript, Python e Go; 20 MB em disco e 7 dias nos SDKs de apps e na JVM. Os mais antigos saem primeiro.
- Oculta segredos, do mesmo jeito em todos os SDKs. O valor de um campo vira
"[redacted]"quando o nome dele, em minúsculas e sem-,_,.ou espaços, é ou termina comauthorization,cookie,password,passwd,secret,token,apikey,privatekey,credential(s),accesskeyousignature. Assim,X-Api-Key,csrf_tokeneSet-Cookiesão ocultados, etoken_countemax_tokensnão. Isso acontece em qualquer profundidade dos atributos e do payload, antes de qualquer corte, então um segredo nunca sobrevive em uma string encurtada ou na prévia de um payload. Só os nomes são verificados: um segredo dentro de uma mensagem ou do texto de um erro é enviado como está. Mude a lista comredactedKeys(Swift, Android, Flutter, JVM),redactKeys(JavaScript, React Native),redact_keys(Python) ouRedactKeys(Go): a sua lista substitui a padrão, e uma lista vazia desativa a ocultação. Para acrescentar itens, estenda os padrões exportados:Configuration.defaultRedactedKeysem Swift,Configuration.DEFAULT_REDACTED_KEYSno Android e na JVM,LyrelogConfiguration.defaultRedactedKeysem Flutter,DEFAULT_REDACT_KEYSem JavaScript, React Native e Python,DefaultRedactKeys()em Go. Os SDKs de JavaScript e Python também aceitam um hookbeforeSend/before_sendpara alterar ou descartar qualquer evento. - Esvazia a fila em um intervalo fixo (15 s nos SDKs de apps, 5 s na web e nos servidores),
quando você chama
flush, quando um app vai para segundo plano e ao encerrar. - Ajusta os eventos aos limites do servidor antes de colocá-los na fila, então nunca envia uma linha que o servidor rejeitaria pelo formato.
Configuração
As mesmas configurações existem em todos os SDKs, com os nomes de cada linguagem. A página de cada SDK tem a lista completa.
Apps
| Configuração | Swift | Android | React Native | Flutter | Padrão |
|---|---|---|---|---|---|
| Chave | apiKey | apiKey | apiKey | apiKey | obrigatória: uma chave de ingestão |
| Endpoint | endpoint | endpoint | endpoint | endpoint | https://ingest.lyrelog.com |
| Ambiente | environment | environment | environment | environment | detectado, veja Ambientes |
| Plataforma | platform | platform | platform | platform | o sistema operacional, veja Plataformas |
| Versão | do bundle | appVersion, senão do pacote | do app | do app | enviada como resource.app_version |
| Id do app | do bundle | o nome do pacote | o bundle id ou o nome do pacote | o bundle id ou o nome do pacote | enviado como resource.app_id |
| Nível mínimo mantido | minimumLevel | minimumLevel | minimumLevel | minimumLevel | debug |
| Intervalo de envio | uploadInterval | flushIntervalMillis | flushIntervalMs | flushInterval | 15 s |
| Tamanho da fila | maxDiskBytes | maxDiskBytes | maxDiskBytes | maxDiskBytes | 20 MB em disco |
| Consentimento | consent | consent | consent | consent | granted |
| Provar o app (eventos verificados) | appAttest | attest | attest | attest | ativado |
Web e servidores
| Configuração | JavaScript | Python | Go | JVM | Padrão |
|---|---|---|---|---|---|
| Chave | apiKey | api_key | APIKey | apiKey | obrigatória: uma chave de ingestão em navegadores, uma chave de servidor em servidores |
| Endpoint | endpoint | endpoint | Endpoint | endpoint | https://ingest.lyrelog.com |
| Ambiente | environment | environment | Environment | environment | detectado, veja Ambientes |
| Plataforma | platform | platform | Platform | platform | detectada, veja Plataformas |
| Versão | release | release | Release | release, senão o manifest do jar | enviada como resource.app_version |
| Id do app | appId | app_id | AppID | appId, senão o manifest do jar | enviado como resource.app_id |
| Nível mínimo mantido | minimumLevel | minimum_level | MinimumLevel | minimumLevel | debug |
| Intervalo de envio | flushIntervalMs | flush_interval | FlushInterval | flushIntervalMillis | 5 s |
| Tamanho da fila | maxQueue | max_queue | MaxQueue | maxDiskBytes | 10.000 eventos em memória; 20 MB em disco na JVM |
| Consentimento | consent | granted (navegadores) |
Nas colunas de JavaScript e Go a instância se chama client (log nos exemplos de JavaScript);
os outros SDKs registram logs por meio de Lyrelog ou do módulo lyrelog. Os contadores também
seguem os nomes de cada linguagem: JavaScript e Python contam delivered, Go conta Sent.
Quando os eventos não aparecem
- Confira o ambiente. O painel abre em
production. O Swift enviadevelopmenta partir do Xcode e do simulador, o Android a partir de todo build de debug, e os apps React Native e Flutter fazem como o SDK nativo por baixo deles. O JavaScript enviadevelopmentemlocalhoste, no Node, sempre queNODE_ENVnão forproduction, inclusive quando não estiver definido. Escolha o ambiente, ou All environments, na barra superior. - Leia as mensagens do próprio SDK. Swift: o unified log, subsistema
com.lyrelog.sdk, no nível debug (no app Console, ative Include Debug Messages). Android: logcat, tagLyrelog, no nível debug. React Native e Flutter: as do SDK nativo, nos mesmos lugares; o React Native também avisa uma vez no Metro, em builds de desenvolvimento, quando a chave ou o módulo nativo está faltando. JavaScript: linhas do console que começam com[lyrelog]. Python: o loggerlyrelog. Go:Config.ErrorLog; sem ele, o primeiro problema é impresso uma vez no stderr. JVM: a saída de erro padrão, linhas que começam comlyrelog:, ouConfiguration.diagnostics. Elas dizem quando a chave foi recusada, quando o endpoint está errado ou quando um lote foi descartado. - Deixe o processo enviar antes de terminar. Scripts curtos, funções serverless e processos
que chamam
exitprecisam esvaziar a fila ou fechar o cliente antes. O shutdown hook do SDK da JVM faz isso em uma saída normal, mas um handler serverless ainda precisa chamar o flush. Veja a página de cada SDK. - Confira o consentimento e o nível. Com o consentimento
pending, nada é enviado. Eventos abaixo do nível mínimo mantido nunca entram na fila. - Confira a chave. Depois de um
401ou403, nada mais é enviado até o app ou o processo reiniciar. Uma chave vazia não envia nada (em Go,Newretorna um erro; na JVM,startretornafalse).
O que não enviar
Use message para um nome de evento estável, nunca para um texto com dados pessoais. Use os seus
próprios ids para as pessoas (setUser, user_id), não endereços de email. Deixe tokens, senhas
e corpos completos de requisição ou resposta com seus headers fora dos atributos e dos payloads.
A ocultação é uma rede de segurança para os nomes de chave que ela conhece, não um filtro em que
você possa confiar.
Em desenvolvimento e testes
- Swift: não chame
Lyrelog.startnos testes. Tudo o que for registrado antes destarté ignorado. - Android: o mesmo, não chame
Lyrelog.startem testes unitários. Builds de debug enviamdevelopment; acessar um endpoint no seu computador a partir do emulador exige algumas configurações, veja Em desenvolvimento e testes. - React Native: não chame
Lyrelog.initnos testes: chamadas antes deinitsão ignoradas. Builds de debug enviamdevelopment. - Flutter: não chame
Lyrelog.startem testes de widget e unitários: tudo o que for registrado antes destarté ignorado. Nas plataformas que o plugin não suporta (web, desktop), as chamadas não fazem nada. Veja Em desenvolvimento e testes. - JavaScript: deixe
apiKeyvazio e o cliente avisa uma vez e não envia nada, ou passeconsent: "denied". - Python: um
api_keyvazio gera um cliente que aceita eventos e não envia nada. - Go:
Newretorna um erro sem umAPIKey, e um*Clientnilnão faz nada, então o mesmo código roda sem cliente. - JVM: deixe a chave de fora:
startretornafalsee as chamadas não fazem nada, inclusive o appender do Logback.