Swift
Logs estruturados do seu app para iOS, macOS, tvOS, watchOS ou visionOS. Sem dependências.
O SDK de Swift requer iOS 16, macOS 13, tvOS 16, watchOS 9 ou visionOS 1, e Swift 6. Alguns recursos dependem da plataforma: veja Plataformas.
Prévia interna: este pacote ainda não foi publicado. Até lá, o Xcode não consegue baixá-lo: o repositório é privado e ainda não tem nenhuma release.
Instalação
Swift Package Manager. No Xcode, escolha File > Add Package Dependencies, informe
https://github.com/GonzaloFuentes28/lyrelog-swift e adicione o produto Lyrelog ao target do
seu app. No Package.swift:
dependencies: [
.package(url: "https://github.com/GonzaloFuentes28/lyrelog-swift", from: "0.1.0"),
],
targets: [
.target(name: "MyApp", dependencies: [.product(name: "Lyrelog", package: "lyrelog-swift")]),
]Primeiros passos
Inicie uma única vez, o mais cedo possível, por exemplo no init do seu App. Uma segunda
chamada é 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 Lyrelog
@main
struct MyApp: App {
init() {
Lyrelog.start(Configuration(
apiKey: "lyr_ing_..." // ingest-only: it can append events, never read them
))
}
var body: some Scene { WindowGroup { ContentView() } }
}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. 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(_:_:) com um nível.
Lyrelog.info("checkout_done", attrs: ["items": 3, "latency_ms": .int(ms)])
Lyrelog.error("payment_declined", category: "checkout",
attrs: ["code": 51], payload: ["response": .string(raw)])Atributos e payloads são LogValues. Literais funcionam diretamente ("text", 412, 0.5,
true, ["a", "b"], dicionários aninhados, nil); para variáveis, use os cases (.int(ms),
.string(name), .double(x), .bool(flag)) ou LogValue(x). LogValue(duration) converte uma
Duration em milissegundos.
Se o seu app tiver o próprio tipo LogLevel, refira-se ao do Lyrelog como Lyrelog.Level.
Loggers para cada área
Um logger marca a sua category em todo evento, como o Logger(category:) do OSLog. Ele tem
todos os níveis, exceto trace, além de log e captureError.
let sync = Lyrelog.Logger(category: "sync")
sync.warning("sync_conflict", attrs: ["records": 2])Usuários
Lyrelog.setUser(playerID) // attached to every following event
Lyrelog.setUser(nil) // 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.
Lyrelog.screen("Settings") // anywhere
SettingsView().lyrelogScreen("Settings") // or in SwiftUI, on appearO evento traz screen, previous_screen e seconds_on_previous. Chamar screen de novo com o
mesmo nome não registra nada. As duas formas aceitam attrs extras para o evento
screen_viewed. Desative a marcação com attachScreen: false.
Requisições de rede
As requisições viram eventos http_request e http_request_failed na área network, com o
método, o host, um caminho cujos ids são reduzidos a :id, o status, a duração e o tamanho.
Nunca a query string, os headers ou o corpo.
let (data, response) = try await URLSession.shared.loggedData(for: request)Se os seus caminhos tiverem partes que essa redução não reconhece, passe a rota você mesmo:
loggedData(for: request, route: "/players/:id/stats").
loggedData(for:route:category:) funciona com qualquer URLSession. Com o seu próprio cliente,
registre cada requisição você mesmo:
let clock = ContinuousClock()
let start = clock.now
let (data, response) = try await myClient.send(request)
Lyrelog.Network.record(request, response: response, error: nil, duration: clock.now - start, bytes: data.count, route: "/orders/:id")duration é uma Duration do Swift: meça com ContinuousClock, como acima.
bytes e category (padrão network) são opcionais. 2xx e 3xx são debug, 4xx warning,
5xx e falhas error (uma requisição cancelada é debug). Uma falha traz error_domain e
error_code.
Erros que você captura
do {
try await store.purchase(product)
} catch {
Lyrelog.captureError(error, category: "store")
}Capturar um erro envia o evento exception que todo SDK envia: nível error, os atributos error_type e
error_message, e um payload com a descrição, o domínio e o código do NSError, e o erro
subjacente. attrs: acrescenta os seus; level: muda o nível. Cada Logger também tem
captureError.
Crashes e travamentos
Crashes e travamentos vêm do MetricKit (iOS, macOS, visionOS), ativado por padrão
(captureDiagnostics). O iOS os entrega na próxima inicialização, então cada um vira um evento
no momento em que aconteceu, sem sessão, na área diagnostics:
| Evento | Nível | O que ele traz |
|---|---|---|
app_crashed | critical | Exceção, sinal, motivo do encerramento, a versão e o dispositivo em que aconteceu, o frame mais alto do seu app e até 60 frames no payload |
app_hung | error | Quanto tempo ficou travado |
cpu_overuse | warning | |
disk_write_overuse | warning | |
slow_launch | warning |
Um relatório entregue duas vezes é armazenado uma vez. Os frames são offsets dentro de cada
binário, não símbolos: simbolique-os com o dSYM quando precisar dos nomes. Cada frame aparece como
MyApp +0x1a2b3c: o binário e o offset dentro do código dele, e o binary_images do payload traz
o UUID de cada binário. Com o dSYM do build que deu crash (o Organizer do Xcode, ou o seu
archive), o atos converte um offset na função, no arquivo e na linha. Passe o endereço de carga
usual do binário, 0x100000000 para um app em arm64, e esse endereço somado ao offset:
atos -arch arm64 \
-o MyApp.app.dSYM/Contents/Resources/DWARF/MyApp \
-l 0x100000000 \
0x1001a2b3cAntes, confira se o UUID do dSYM (dwarfdump --uuid MyApp.app.dSYM) bate com o que está em
binary_images.
Ambientes e plataforma
Ao iniciar, o SDK escolhe o ambiente:
developmentpara um build Debug, qualquer build no simulador ou um build com um provisioning profile embutido (assinatura de development, ad hoc e enterprise);testflightpara um build com um recibo sandbox da App Store e sem profile;productionnos outros casos.
Depois ele consulta o StoreKit em segundo plano (AppTransaction.shared.environment), sem pedir
nada à pessoa, e os eventos registrados depois da resposta levam essa resposta: xcode é
development, sandbox é testflight, production é production. É assim que um app de Mac
vindo do TestFlight é reconhecido. Sem conexão ou sem ter entrado na conta, a primeira resposta
continua valendo, e um app de Mac conta como production até o StoreKit responder.
As suas próprias execuções pelo Xcode enviam development, enquanto o painel abre em
production: escolha development na barra superior para vê-las.
A plataforma é o sistema operacional (ios, macos, tvos, visionos; apple no watchOS).
Sobrescreva qualquer um dos dois na configuração:
Configuration(apiKey: key,
environment: isInternalTester ? "internal" : nil, // nil = detected
platform: nil)Lyrelog.detectedEnvironment é a resposta na inicialização; await Lyrelog.detectEnvironment()
também espera o StoreKit (até 10 segundos). 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).
Plataformas
| iOS, iPadOS, visionOS | tvOS | macOS | watchOS | |
|---|---|---|---|---|
platform | ios, visionos | tvos | macos | apple |
| Envia quando o app vai para segundo plano | Sim | Sim | Não | Não |
| Crashes e travamentos (MetricKit) | Sim | Não | Sim | Não |
Sem o envio ao ir para segundo plano, os eventos são enviados no intervalo fixo enquanto o app
roda, e o que sobrar sai na próxima inicialização, já que a fila fica em disco. No watchOS,
os_name é unknown.
Consentimento
Lyrelog.start(Configuration(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 recording.pending mantém os eventos no dispositivo sem enviá-los. 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.
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 Lyrelog
import SwiftUI
@main
struct MyApp: App {
init() {
let consent: Lyrelog.Consent = switch UserDefaults.standard.string(forKey: "diagnostics") {
case "granted": .granted
case "denied": .denied
default: .pending
}
Lyrelog.start(Configuration(apiKey: "lyr_ing_...", consent: consent))
}
var body: some Scene {
WindowGroup { RootView() }
}
}
struct RootView: View {
@State private var account: Account?
var body: some View {
Group {
if let account {
HomeView(account: account).lyrelogScreen("Home")
} else {
SignInView { signedIn in
account = signedIn
Lyrelog.setUser(signedIn.id)
Lyrelog.info("signed_in", category: "auth")
}
.lyrelogScreen("Sign in")
}
}
}
}
func choose(_ allowed: Bool) {
UserDefaults.standard.set(allowed ? "granted" : "denied", forKey: "diagnostics")
Lyrelog.setConsent(allowed ? .granted : .denied)
}Esvaziar a fila e parar
No iOS, tvOS e visionOS, ir para segundo plano já esvazia a fila (com uma background task), então você raramente vai precisar fazer isso.
await Lyrelog.flush() // write everything to disk and try to send now
await Lyrelog.stop() // send what's queued (up to 2 seconds), then stopSem await (a partir de código síncrono), Lyrelog.stop() para na hora e não envia nada: os
eventos ainda em memória se perdem, e o que estava na fila em disco sai depois do próximo
start.
flush respeita um Retry-After pedido pelo servidor: não envia antes disso.
No macOS, envie o que sobrou quando o app for encerrado segurando o encerramento por um instante:
final class AppDelegate: NSObject, NSApplicationDelegate {
func applicationShouldTerminate(_ sender: NSApplication) -> NSApplication.TerminateReply {
Task {
await Lyrelog.stop() // sends what's queued, up to 2 seconds
sender.reply(toApplicationShouldTerminate: true)
}
return .terminateLater
}
}
// In your App: @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegateEm desenvolvimento e testes
Não chame Lyrelog.start em testes unitários nem em previews: tudo o que for registrado antes de
start é ignorado, então o resto do seu código roda sem mudanças.
if ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] == nil {
Lyrelog.start(Configuration(apiKey: "lyr_ing_..."))
}mirrorToOSLog: true também imprime cada evento no console do Xcode enquanto você trabalha.
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.
Em um iPhone, iPad ou Apple Watch real, o SDK prova com o App Attest da Apple que os eventos vêm
do seu app legítimo, e o Lyrelog os armazena como verificados (verified_by é app_attest). A
opção appAttest é true por padrão; ela precisa de:
- A capability App Attest no target do app (Signing & Capabilities), o entitlement
com.apple.developer.devicecheck.appattest-environment. Defina-o comoproductionpara builds da App Store e do TestFlight; sem ele, a Apple usa o ambiente de desenvolvimento. - O seu App ID, o Team ID, um ponto e o bundle id (
ABCDE12345.com.example.app), nas configurações do projeto, seção Verified events from your Apple apps. Enquanto ele não estiver definido, o SDK para de tentar naquela inicialização.
O envio nunca espera por isso: os lotes saem sem token até o dispositivo ter um, então os
primeiros eventos de uma instalação nova chegam não verificados, assim como os eventos enviados
sempre que algo falhar. Só o id da chave é guardado, no Keychain, e negar o consentimento o
apaga. Desative com appAttest: false.
Para conferir, abra o explorer: em Filter, escolha Verified by e App Attest (os outros valores são Server key e Not verified). Um evento aberto diz isso em Context, na linha Sender: Verified, App Attest ou Not verified, public key.
Macs (a Apple não oferece App Attest neles), o simulador, as app extensions (exceto no watchOS) e os dispositivos sem App Attest sempre enviam eventos não verificados, mesmo com tudo configurado: a chave de ingestão é pública, então qualquer pessoa com ela poderia ter enviado o mesmo. Um evento verificado prova qual app o enviou, não que o conteúdo dele seja verdadeiro.
Veja Eventos verificados para saber quem verifica o quê e como funciona a cota diária.
Configuração
| Opção | Padrão | Significado |
|---|---|---|
endpoint | https://ingest.lyrelog.com | A URL base; um caminho /v1/... colado é removido. Só https, http apenas para localhost |
apiKey | obrigatória | A chave de ingestão do projeto |
consent | .granted | .pending, .granted ou .denied |
minimumLevel | .debug | Eventos abaixo dele nunca chegam ao disco |
mirrorToOSLog | false | Imprime também cada evento no unified log (Console, Xcode) |
uploadInterval | 15 s | De quanto em quanto tempo o envio acorda em primeiro plano |
pauseUploadsInLowPowerMode | true | Os envios periódicos pausam; ir para segundo plano continua enviando |
maxBatchBytes | 512 KiB | Um lote fecha no limite que chegar primeiro (mantido entre 64 KiB e 4 MiB) |
maxBatchEvents | 500 | No máximo 2.000 |
maxDiskBytes | 20 MB | Limite da fila em disco, os mais antigos saem primeiro |
maxEventAge | 7 dias | Eventos mais antigos na fila são descartados |
sessionTimeout | 30 min | Tempo de inatividade que inicia uma nova sessão |
storageDirectory | Library/Caches/lyrelog | Onde a fila fica |
captureDiagnostics | true | Crashes, travamentos e relatórios de uso excessivo do MetricKit |
attachScreen | true | Marca os eventos com a tela atual |
environment | detectado | Qualquer nome válido, ou nil |
platform | o sistema operacional | Qualquer nome válido, ou nil |
appAttest | true | Verifica os eventos com o App Attest da Apple nos dispositivos compatíveis |
Entrega e limites
| Nunca bloqueia | Registrar um log copia o evento e retorna; um único writer em segundo plano o grava em disco. |
| Sobrevive a encerramentos forçados e à falta de conexão | Uma fila em Library/Caches, limitada a 20 MB e 7 dias. O sistema pode limpar Caches quando o dispositivo fica sem espaço, e os eventos que estavam esperando vão junto. |
| 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 com um aviso, e uma chave revogada (401, 403) interrompe o envio até a próxima inicialização. 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 (unified log, subsistema com.lyrelog.sdk) a cada parada por cota. |
| 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, uma chave recusada ou linhas rejeitadas vão uma vez por inicialização para o unified log, subsistema com.lyrelog.sdk, no nível debug (no app Console, ative Include Debug Messages). |
| Contexto | Id do app, versão, build, sistema operacional, modelo do dispositivo (iPhone18,1), locale, id da sessão 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 [] desativa a ocultação.
Para acrescentar itens:
Lyrelog.start(Configuration(
apiKey: "lyr_ing_...",
redactedKeys: Lyrelog.Configuration.defaultRedactedKeys + ["pin"]
))Manifesto de privacidade e privacidade na App Store
O pacote inclui um manifesto de privacidade (PrivacyInfo.xcprivacy) que o Xcode incorpora ao
relatório de privacidade do seu app: sem rastreamento, sem domínios de rastreamento, a API de
timestamp de arquivos com o motivo C617.1 (a fila lê o tamanho dos próprios arquivos), e os
dados que ele coleta (dados de crash, dados de desempenho, outros dados de diagnóstico, um id do
dispositivo), não vinculados à pessoa e não usados para rastreamento.
Para o rótulo de privacidade da App Store, declare o que o seu app envia pelo Lyrelog:
- Diagnostics: Crash Data, Performance Data, Other Diagnostic Data (App Functionality).
- Identifiers > Device ID: 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 (App Functionality). Não vinculado à
pessoa, a menos que você também chame
setUser. - Identifiers > User ID, vinculado à pessoa: só se você chamar
setUser. - Usage Data > Product Interaction: se você registrar telas (
screen_viewed) ou toques. - Qualquer outra coisa que os seus
attrsoupayloadlevem (emails, compras...), na categoria correspondente.
O servidor acrescenta o país do endereço de envio; o endereço em si não é armazenado.