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

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

SwiftAndroidReact NativeFlutter
IniciarLyrelog.start(Configuration(...))Lyrelog.start(context, Configuration(...))Lyrelog.init({...})Lyrelog.start(LyrelogConfiguration(...))
Registrar logLyrelog.info("checkout_done", attrs:)Lyrelog.info("checkout_done", attrs = ...)Lyrelog.info("checkout_done", { attrs })Lyrelog.info('checkout_done', attrs: {...})
Logger de uma áreaLyrelog.Logger(category: "checkout")Lyrelog.logger("checkout")Lyrelog.logger("checkout")Lyrelog.logger('checkout')
UsuárioLyrelog.setUser("u_123")Lyrelog.setUser("u_123")Lyrelog.setUser("u_123")Lyrelog.setUser('u_123')
TelaLyrelog.screen("Settings")Lyrelog.screen("Settings")trackNavigation(ref), ou Lyrelog.screen("Settings")LyrelogNavigatorObserver(), ou Lyrelog.screen('Settings')
Requisiçõessession.loggedData(for:)
Capturar um erroLyrelog.captureError(error)Lyrelog.captureError(e)Lyrelog.captureException(error)Lyrelog.captureError(e, stackTrace: s)
Erros não capturados e crashesCrashes e travamentos do MetricKit, automáticoExceções não capturadas, automático, enviadas na próxima inicializaçãoErros fatais de JavaScript e de renderização como crashes, rejeições e outros erros, mais os crashes nativos; automáticoErros de Dart (FlutterError, PlatformDispatcher), mais os crashes nativos; automático
Esvaziar a filaawait Lyrelog.flush()Lyrelog.flush() (fora da thread principal)await Lyrelog.flush()await Lyrelog.flush()
Pararawait Lyrelog.stop()Lyrelog.stop()await Lyrelog.close()await Lyrelog.stop()

Web e servidores

JavaScriptPythonGoJVM
IniciarLyrelog.init({...})lyrelog.init(...)lyrelog.New(lyrelog.Config{...})Lyrelog.start(Configuration(...))
Registrar logclient.info("checkout_done", { attrs })lyrelog.info("checkout_done", attrs=)client.Info("checkout_done", lyrelog.Attrs{})Lyrelog.info("checkout_done", attrs = ...)
Logger de uma áreaclient.logger("checkout")lyrelog.logger("checkout")client.Logger("checkout")Lyrelog.logger("checkout")
Usuárioclient.setUser("u_123")lyrelog.set_user("u_123")client.SetUser("u_123")Lyrelog.setUser("u_123"), ou Lyrelog.userScope(id) para uma thread
Telaclient.screen("Settings")
Capturar um erroclient.captureException(err)lyrelog.capture_exception(exc)client.CaptureError(err)Lyrelog.captureError(e)
Erros não capturados e crasheswindow e Node, automáticoo seu próprio sys.excepthooko seu próprio recovercaptureUncaught = true (desativado por padrão)
Esvaziar a filaawait client.flush()lyrelog.flush()client.Flush(ctx)Lyrelog.flush()
Pararawait client.close()lyrelog.shutdown()client.Close()Lyrelog.close() (um shutdown hook faz isso ao sair)
Logging padrãolyrelog.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 outro endpoint. O endpoint é a URL base: se você colar o endereço inteiro .../v1/events:batch, o SDK remove o caminho. Um endpoint errado (um 404, 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 o Retry-After, inclusive quando você chama flush ou 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 do Retry-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 um storageDirectory. 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 com authorization, cookie, password, passwd, secret, token, apikey, privatekey, credential(s), accesskey ou signature. Assim, X-Api-Key, csrf_token e Set-Cookie são ocultados, e token_count e max_tokens nã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 com redactedKeys (Swift, Android, Flutter, JVM), redactKeys (JavaScript, React Native), redact_keys (Python) ou RedactKeys (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.defaultRedactedKeys em Swift, Configuration.DEFAULT_REDACTED_KEYS no Android e na JVM, LyrelogConfiguration.defaultRedactedKeys em Flutter, DEFAULT_REDACT_KEYS em JavaScript, React Native e Python, DefaultRedactKeys() em Go. Os SDKs de JavaScript e Python também aceitam um hook beforeSend / before_send para 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çãoSwiftAndroidReact NativeFlutterPadrão
ChaveapiKeyapiKeyapiKeyapiKeyobrigatória: uma chave de ingestão
Endpointendpointendpointendpointendpointhttps://ingest.lyrelog.com
Ambienteenvironmentenvironmentenvironmentenvironmentdetectado, veja Ambientes
Plataformaplatformplatformplatformplatformo sistema operacional, veja Plataformas
Versãodo bundleappVersion, senão do pacotedo appdo appenviada como resource.app_version
Id do appdo bundleo nome do pacoteo bundle id ou o nome do pacoteo bundle id ou o nome do pacoteenviado como resource.app_id
Nível mínimo mantidominimumLevelminimumLevelminimumLevelminimumLeveldebug
Intervalo de enviouploadIntervalflushIntervalMillisflushIntervalMsflushInterval15 s
Tamanho da filamaxDiskBytesmaxDiskBytesmaxDiskBytesmaxDiskBytes20 MB em disco
Consentimentoconsentconsentconsentconsentgranted
Provar o app (eventos verificados)appAttestattestattestattestativado

Web e servidores

ConfiguraçãoJavaScriptPythonGoJVMPadrão
ChaveapiKeyapi_keyAPIKeyapiKeyobrigatória: uma chave de ingestão em navegadores, uma chave de servidor em servidores
EndpointendpointendpointEndpointendpointhttps://ingest.lyrelog.com
AmbienteenvironmentenvironmentEnvironmentenvironmentdetectado, veja Ambientes
PlataformaplatformplatformPlatformplatformdetectada, veja Plataformas
VersãoreleasereleaseReleaserelease, senão o manifest do jarenviada como resource.app_version
Id do appappIdapp_idAppIDappId, senão o manifest do jarenviado como resource.app_id
Nível mínimo mantidominimumLevelminimum_levelMinimumLevelminimumLeveldebug
Intervalo de envioflushIntervalMsflush_intervalFlushIntervalflushIntervalMillis5 s
Tamanho da filamaxQueuemax_queueMaxQueuemaxDiskBytes10.000 eventos em memória; 20 MB em disco na JVM
Consentimentoconsentgranted (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

  1. Confira o ambiente. O painel abre em production. O Swift envia development a 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 envia development em localhost e, no Node, sempre que NODE_ENV não for production, inclusive quando não estiver definido. Escolha o ambiente, ou All environments, na barra superior.
  2. 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, tag Lyrelog, 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 logger lyrelog. 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 com lyrelog: , ou Configuration.diagnostics. Elas dizem quando a chave foi recusada, quando o endpoint está errado ou quando um lote foi descartado.
  3. Deixe o processo enviar antes de terminar. Scripts curtos, funções serverless e processos que chamam exit precisam 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.
  4. 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.
  5. Confira a chave. Depois de um 401 ou 403, nada mais é enviado até o app ou o processo reiniciar. Uma chave vazia não envia nada (em Go, New retorna um erro; na JVM, start retorna false).

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.start nos testes. Tudo o que for registrado antes de start é ignorado.
  • Android: o mesmo, não chame Lyrelog.start em testes unitários. Builds de debug enviam development; 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.init nos testes: chamadas antes de init são ignoradas. Builds de debug enviam development.
  • Flutter: não chame Lyrelog.start em testes de widget e unitários: tudo o que for registrado antes de start é ignorado. Nas plataformas que o plugin não suporta (web, desktop), as chamadas não fazem nada. Veja Em desenvolvimento e testes.
  • JavaScript: deixe apiKey vazio e o cliente avisa uma vez e não envia nada, ou passe consent: "denied".
  • Python: um api_key vazio gera um cliente que aceita eventos e não envia nada.
  • Go: New retorna um erro sem um APIKey, e um *Client nil não faz nada, então o mesmo código roda sem cliente.
  • JVM: deixe a chave de fora: start retorna false e as chamadas não fazem nada, inclusive o appender do Logback.