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

Swift

Logs estruturados do seu app para iOS, macOS, tvOS, watchOS ou visionOS. Sem dependências.

iOS, iPadOS, macOS, tvOS, watchOS, visionOS

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-out

Lyrelog.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 appear

O 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:

EventoNívelO que ele traz
app_crashedcriticalExceçã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_hungerrorQuanto tempo ficou travado
cpu_overusewarning
disk_write_overusewarning
slow_launchwarning

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 \
  0x1001a2b3c

Antes, 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:

  • development para um build Debug, qualquer build no simulador ou um build com um provisioning profile embutido (assinatura de development, ad hoc e enterprise);
  • testflight para um build com um recibo sandbox da App Store e sem profile;
  • production nos 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, visionOStvOSmacOSwatchOS
platformios, visionostvosmacosapple
Envia quando o app vai para segundo planoSimSimNãoNão
Crashes e travamentos (MetricKit)SimNãoSimNã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.

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 stop

Sem 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 appDelegate

Em 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 como production para 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çãoPadrãoSignificado
endpointhttps://ingest.lyrelog.comA URL base; um caminho /v1/... colado é removido. Só https, http apenas para localhost
apiKeyobrigatóriaA chave de ingestão do projeto
consent.granted.pending, .granted ou .denied
minimumLevel.debugEventos abaixo dele nunca chegam ao disco
mirrorToOSLogfalseImprime também cada evento no unified log (Console, Xcode)
uploadInterval15 sDe quanto em quanto tempo o envio acorda em primeiro plano
pauseUploadsInLowPowerModetrueOs envios periódicos pausam; ir para segundo plano continua enviando
maxBatchBytes512 KiBUm lote fecha no limite que chegar primeiro (mantido entre 64 KiB e 4 MiB)
maxBatchEvents500No máximo 2.000
maxDiskBytes20 MBLimite da fila em disco, os mais antigos saem primeiro
maxEventAge7 diasEventos mais antigos na fila são descartados
sessionTimeout30 minTempo de inatividade que inicia uma nova sessão
storageDirectoryLibrary/Caches/lyrelogOnde a fila fica
captureDiagnosticstrueCrashes, travamentos e relatórios de uso excessivo do MetricKit
attachScreentrueMarca os eventos com a tela atual
environmentdetectadoQualquer nome válido, ou nil
platformo sistema operacionalQualquer nome válido, ou nil
appAttesttrueVerifica os eventos com o App Attest da Apple nos dispositivos compatíveis

Entrega e limites

Nunca bloqueiaRegistrar 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ãoUma 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.
LotesAté 500 eventos ou 512 KiB por requisição, com gzip. Um evento com mais de 1 MiB depois de codificado é descartado e contado.
Novas tentativas1 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 mensalQuando 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íveisOs eventos perdidos pelos limites viram um único aviso lyrelog_events_dropped (área lyrelog) com a contagem.
Os próprios problemasUm 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).
ContextoId do app, versão, build, sistema operacional, modelo do dispositivo (iPhone18,1), locale, id da sessão e id da instalação.
SegredosValores 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.
LimitesStrings 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 attrs ou payload levem (emails, compras...), na categoria correspondente.

O servidor acrescenta o país do endereço de envio; o endereço em si não é armazenado.