アーリーアクセス招待制です。SDK はまだ公開されていません。招待をリクエスト
本文へスキップ
ドキュメント

Swift

iOS、macOS、tvOS、watchOS、visionOS アプリから構造化ログを送ります。依存関係はありません。

iOS、iPadOS、macOS、tvOS、watchOS、visionOS

Swift SDK を使うには、iOS 16、macOS 13、tvOS 16、watchOS 9、visionOS 1 のいずれか以降と、Swift 6 が必要です。一部の 機能はプラットフォームによって異なります。プラットフォームを参照してください。

社内プレビュー:このパッケージはまだ公開されていません。公開されるまでは Xcode から取得できません。 リポジトリは非公開で、まだリリースもありません。

インストール

Swift Package Manager を使います。Xcode で File > Add Package Dependencies を選び、 https://github.com/GonzaloFuentes28/lyrelog-swift を入力して、プロダクト Lyrelog をアプリのターゲットに 追加します。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")]),
]

開始

できるだけ早い段階で一度だけ開始します。たとえば App の init の中です。2 回目の呼び出しは無視されます。 start より前に記録したイベントも無視されますが、start より前に呼んだ setUser と setConsent は保持され、開始時に適用されます。

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() } }
}

イベントは https://ingest.lyrelog.com に送られます。endpoint は別の場所に送るときだけ指定してください。 これはベース URL で(.../v1/events:batch のパスを貼り付けても取り除かれます)、https でなければなりません。 プレーンな http は localhost、127.0.0.1、::1 に対してだけ使えます。それ以外のエンドポイントでは何も 送信されず、イベントはデバイスに残ります。

イベントを記録する

レベルごとに関数が 1 つあります。trace、debug、info、notice、warning、error、critical、 またはレベルを指定する log(_:_:) です。

Lyrelog.info("checkout_done", attrs: ["items": 3, "latency_ms": .int(ms)])
Lyrelog.error("payment_declined", category: "checkout",
              attrs: ["code": 51], payload: ["response": .string(raw)])

属性とペイロードは LogValue です。リテラルはそのまま使えます("text"、412、0.5、true、 ["a", "b"]、ネストした辞書、nil)。変数には case(.int(ms)、.string(name)、.double(x)、 .bool(flag))か LogValue(x) を使います。LogValue(duration) は Duration をミリ秒に変換します。

アプリに独自の LogLevel 型がある場合は、Lyrelog のものを Lyrelog.Level として参照してください。

領域ごとのロガー

ロガーは、OSLog の Logger(category:) と同じように、すべてのイベントに自分の category を付けます。trace 以外のすべてのレベルと、log、captureError があります。

let sync = Lyrelog.Logger(category: "sync")
sync.warning("sync_conflict", attrs: ["records": 2])

ユーザー

Lyrelog.setUser(playerID)   // attached to every following event
Lyrelog.setUser(nil)        // on sign-out

Lyrelog.sessionID で現在のセッション id を取得できます。たとえばサポート画面に表示するのに使えます。

ユーザー id は起動をまたいで保存されません。起動のたびに、相手が誰かわかった時点で setUser を改めて呼んでください。

画面

ユーザーがどこにいるかを伝えます。Lyrelog は、直前の画面とそこで過ごした秒数を付けて screen_viewed (領域 navigation)を記録し、以降のすべてのイベントに screen 属性を付けます。

Lyrelog.screen("Settings")                 // anywhere
SettingsView().lyrelogScreen("Settings")   // or in SwiftUI, on appear

このイベントには screen、previous_screen、seconds_on_previous が含まれます。同じ名前で screen をもう一度呼んでも何も記録されません。どちらの書き方でも、screen_viewed イベント用に追加の attrs を渡せます。属性を付ける動作は attachScreen: false でオフにできます。

ネットワークリクエスト

リクエストは network 領域の http_request と http_request_failed イベントになり、メソッド、ホスト、 id を :id にまとめたパス、ステータス、所要時間、サイズが含まれます。クエリ文字列、ヘッダー、ボディは 決して含まれません。

let (data, response) = try await URLSession.shared.loggedData(for: request)

パスに、まとめる処理では認識できないものが含まれる場合は、ルートを自分で渡してください: loggedData(for: request, route: "/players/:id/stats")。

loggedData(for:route:category:) はどの URLSession でも使えます。独自のクライアントを使う場合は、 リクエストごとに自分で記録します。

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 は Swift の Duration です。上のように ContinuousClock で計測してください。

bytes と category(デフォルトは network)は省略できます。2xx と 3xx は debug、4xx は warning、 5xx と失敗は error です(キャンセルされたリクエストは debug)。失敗には error_domain と error_code が付きます。

捕捉したエラー

do {
    try await store.purchase(product)
} catch {
    Lyrelog.captureError(error, category: "store")
}

すべての SDK に共通の exception イベントを送ります。レベルは error、属性は error_type と error_message、ペイロードには説明、NSError のドメインとコード、元になったエラーが入ります。attrs: で独自の属性を追加でき、level: でレベルを変えられます。どの Logger にも captureError があります。

クラッシュとハング

クラッシュとハングは MetricKit(iOS、macOS、visionOS)から取得し、デフォルトでオンです (captureDiagnostics)。iOS は次回の起動時にこれらを渡すので、それぞれが発生した時刻のイベントとして、 セッションなしで diagnostics 領域に記録されます。

イベントレベル含まれるもの
app_crashedcritical例外、シグナル、終了理由、発生したときのバージョンとデバイス、アプリ自身の最上位フレーム、ペイロードに最大 60 フレーム
app_hungerrorハングしていた時間
cpu_overusewarning
disk_write_overusewarning
slow_launchwarning

2 回届いたレポートは 1 回だけ保存されます。フレームはシンボルではなく、各バイナリ内のオフセットです。名前が 必要なときは dSYM でシンボル化してください。各フレームは MyApp +0x1a2b3c のように、バイナリとそのコード内の オフセットを示し、ペイロードの binary_images に各バイナリの UUID があります。クラッシュしたビルドの dSYM (Xcode の Organizer、またはアーカイブ)があれば、atos でオフセットを関数、ファイル、行に変換できます。 バイナリの通常のロードアドレス(arm64 のアプリなら 0x100000000)と、そのアドレスにオフセットを足した値を 渡します。

atos -arch arm64 \
  -o MyApp.app.dSYM/Contents/Resources/DWARF/MyApp \
  -l 0x100000000 \
  0x1001a2b3c

その前に、dSYM の UUID(dwarfdump --uuid MyApp.app.dSYM)が binary_images のものと一致することを 確認してください。

環境とプラットフォーム

開始時に、SDK が環境を選びます。

  • Debug ビルド、シミュレーター上のすべてのビルド、またはプロビジョニングプロファイルが埋め込まれたビルド (development、ad hoc、enterprise の署名)は development。
  • サンドボックスの App Store レシートがあり、プロファイルがないビルドは testflight。
  • それ以外は production。

その後、バックグラウンドで StoreKit に問い合わせ(AppTransaction.shared.environment、ダイアログは出ません)、 応答のあとに記録されたイベントにはその結果が使われます。xcode は development、sandbox は testflight、production は production です。TestFlight から入れた Mac アプリはこの方法で区別されます。 オフラインやサインアウト中は最初の判定のままで、Mac アプリは StoreKit が応答するまで production として 扱われます。

Xcode から自分で実行したものは development を送りますが、ダッシュボードは production で開きます。 それらを見るには、トップバーで development を選んでください。

プラットフォームは OS です(ios、macos、tvos、visionos。watchOS では apple)。どちらも設定で 上書きできます。

Configuration(apiKey: key,
              environment: isInternalTester ? "internal" : nil,   // nil = detected
              platform: nil)

Lyrelog.detectedEnvironment は開始時の判定結果です。await Lyrelog.detectEnvironment() は StoreKit の 応答も待ちます(最大 10 秒)。名前は自由で、英小文字、数字、-、_ からなる 32 文字以内です。それ以外の テキストは有効な名前に変換されます(Staging EU は staging-eu になります)。

プラットフォーム

iOS、iPadOS、visionOStvOSmacOSwatchOS
platformios、visionostvosmacosapple
アプリがバックグラウンドに移ったときに送信はいはいいいえいいえ
クラッシュとハング(MetricKit)はいいいえはいいいえ

バックグラウンドでの送信がない場合、イベントはアプリの実行中にタイマーで送られ、残ったものはキューがディスクに あるので次回の起動時に送られます。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 はイベントを送信せずにデバイスに保持します。consent: .denied で開始すると、以前の起動から キューに残っているものとインストール id が削除され、何も記録されません。

同意は起動をまたいで保存されません。ユーザーの選択は自分で保存し、毎回 start に渡してください。

アプリの完全な例

保存した同意で開始し、サインイン時にユーザーを設定し、画面にタグを付けます。

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)
}

フラッシュと停止

iOS、tvOS、visionOS では、バックグラウンドに移るときに(バックグラウンドタスクで)フラッシュされるので、 自分で行う必要はほとんどありません。

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

await なしで(同期コードから)呼ぶと、Lyrelog.stop() はすぐに止まり、何も送信しません。メモリ上に残っていた イベントは失われ、ディスクのキューにあったものは次の start のあとに送られます。

flush は、サーバーが求めた Retry-After を尊重し、それより早くは送信しません。

macOS では、アプリの終了を少しだけ待たせることで、残りを送信できます。

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

開発中とテスト

ユニットテストやプレビューでは Lyrelog.start を呼ばないでください。start より前に記録されたものは 無視されるので、ほかのコードはそのまま動きます。

if ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] == nil {
    Lyrelog.start(Configuration(apiKey: "lyr_ing_..."))
}

mirrorToOSLog: true にすると、開発中はすべてのイベントが Xcode のコンソールにも出力されます。

検証済みイベント

検証済みイベントとは、アプリや Web ページから公開のインジェストキーをコピーした誰かが送ったものではありえない イベントです。それが何を証明し、何を証明しないかは検証済みイベントにあります。

実機の iPhone、iPad、Apple Watch では、SDK が Apple の App Attest を使って、イベントが正規のアプリから来た ことを証明し、Lyrelog はそれを検証済みとして保存します(verified_by は app_attest)。オプション appAttest はデフォルトで true です。次のものが必要です。

  • アプリのターゲットの App Attest capability(Signing & Capabilities)、つまりエンタイトルメント com.apple.developer.devicecheck.appattest-environment。App Store と TestFlight のビルドでは production に設定してください。設定しないと、Apple は development 環境を使います。
  • App ID(Team ID、ドット、バンドル id をつなげたもの:ABCDE12345.com.example.app)を、プロジェクトの 設定の Verified events from your Apple apps セクションに設定すること。設定されるまで、SDK はその起動中は試行をやめます。

送信がこれを待つことはありません。デバイスがトークンを持つまではバッチはトークンなしで送られるので、新規 インストールの最初のイベントは未検証で届きます。何かが失敗したときに送られたイベントも同様です。保持されるのは キーの id だけで、キーチェーンに保存され、同意が拒否されると削除されます。appAttest: false でオフにできます。

確認するには、エクスプローラーを開き、Filter で Verified by と App Attest を選びます(ほかの値は Server key と Not verified)。開いたイベントでは、Context の Sender 行に Verified, App Attest または Not verified, public key と表示されます。

Mac(Apple は App Attest を提供していません)、シミュレーター、App Extension(watchOS を除く)、App Attest のないデバイスは、すべてを設定していても常に未検証のイベントを送ります。インジェストキーは公開されているので、 それを持つ誰もが同じものを送れたはずだからです。検証済みイベントが証明するのは、どのアプリが送ったかであって、 その内容が正しいことではありません。

誰が何を検証するのか、1 日の割り当てについては検証済みイベントを参照してください。

設定

オプションデフォルト意味
endpointhttps://ingest.lyrelog.comベース URL。貼り付けた /v1/... のパスは取り除かれます。https のみ、http は localhost のみ
apiKey必須プロジェクトのインジェストキー
consent.granted.pending、.granted、.denied
minimumLevel.debugこれより下のイベントはディスクに書かれません
mirrorToOSLogfalseすべてのイベントを統合ログ(Console、Xcode)にも出力します
uploadInterval15 秒フォアグラウンドでアップローダーが起きる間隔
pauseUploadsInLowPowerModetrue定期的なアップロードを一時停止します。バックグラウンドに移るときの送信は行われます
maxBatchBytes512 KiBバッチは先に達したほうの上限で閉じられます(64 KiB から 4 MiB の範囲に収められます)
maxBatchEvents500最大 2,000
maxDiskBytes20 MBディスク上のキューの上限。古いものから捨てられます
maxEventAge7 日これより古いキュー内のイベントは破棄されます
sessionTimeout30 分新しいセッションを始めるまでの無操作時間
storageDirectoryLibrary/Caches/lyrelogキューの置き場所
captureDiagnosticstrueMetricKit のクラッシュ、ハング、使いすぎのレポート
attachScreentrueイベントに現在の画面のタグを付けます
environment自動検出任意の有効な名前、または nil
platformOS任意の有効な名前、または nil
appAttesttrue対応デバイスで Apple の App Attest によりイベントを検証します

配信と上限

ブロックしないログの記録はイベントをコピーしてすぐに戻り、バックグラウンドの 1 つのライターがディスクに書き込みます。
強制終了やオフラインでも失われないLibrary/Caches にあるキューで、上限は 20 MB と 7 日間です。デバイスの空き容量が少ないとシステムが Caches を消去することがあり、そのとき待機中のイベントも一緒に消えます。
バッチ1 リクエストあたり最大 500 イベントまたは 512 KiB、gzip で圧縮。エンコード後に 1 MiB を超えるイベントは破棄され、件数が数えられます。
再試行1 秒から倍々で 5 分まで、フルジッター付きで、Retry-After に従います。それ以外の 4xx はバッチを破棄し、3xx(リダイレクト。決して従いません)は警告付きで破棄し、失効したキー(401、403)は次の起動まで送信を止めます。ほかのバッチは通るのにサーバーが失敗し続けるバッチは、後ろに回され、その後破棄されます。
月間クォータFree の組織が月間のイベント数を使い切ると、サーバーは 429 を返します。イベントはディスクのキューに残り、20 MB と 7 日間の上限の範囲内で、サーバーが再び受け付けるようになったら送られます。SDK は、クォータで止まるたびに警告を 1 回ログに出します(統合ログ、サブシステム com.lyrelog.sdk)。
破棄も確認できる上限で失われたイベントは、件数付きの 1 つの lyrelog_events_dropped 警告(領域 lyrelog)になります。
SDK 自身の問題エンドポイントの誤り、拒否されたキー、拒否された行は、起動ごとに 1 回、統合ログのサブシステム com.lyrelog.sdk に debug レベルで出ます(Console で Include Debug Messages をオンにしてください)。
コンテキストアプリ id、バージョン、ビルド、OS、デバイスモデル(iPhone18,1)、ロケール、セッション id、インストール id。
シークレット名前が authorization、cookie、password、token、secret、apikey など共通のリストのいずれかであるか、それで終わるキーの値は、どの深さでも、切り詰めより前に "[redacted]" になります。
上限長い文字列は文字の境界で切られ、余分な属性は lyrelog_dropped_attrs に数えられ、64 KiB を超えるペイロードは {"lyrelog_truncated": true, "bytes": N, "preview": "..."} に要約されます。

リストは redactedKeys で変更できます。指定したリストがデフォルトを置き換え、[] にするとマスクが オフになります。追加する場合は次のとおりです。

Lyrelog.start(Configuration(
    apiKey: "lyr_ing_...",
    redactedKeys: Lyrelog.Configuration.defaultRedactedKeys + ["pin"]
))

プライバシーマニフェストと App Store のプライバシー

パッケージにはプライバシーマニフェスト(PrivacyInfo.xcprivacy)が含まれており、Xcode がアプリの プライバシーレポートに統合します。トラッキングなし、トラッキングドメインなし、理由 C617.1 によるファイルの タイムスタンプ API の使用(キューが自分のファイルのサイズを読むため)、そして収集するデータ(クラッシュデータ、 パフォーマンスデータ、その他の診断データ、デバイス id)で、いずれもユーザーに紐付けられず、トラッキングにも 使われません。

App Store のプライバシーラベルでは、アプリが Lyrelog を通して送るものを申告してください。

  • Diagnostics: Crash Data、Performance Data、Other Diagnostic Data(App Functionality)。
  • Identifiers > Device ID: インストール id。広告 id ではないランダムな UUID で、バックアップされず、 同意が拒否されると削除されます(App Functionality)。setUser も呼んでいなければ、ユーザーには紐付けられません。
  • Identifiers > User ID(ユーザーに紐付く):setUser を呼ぶ場合のみ。
  • Usage Data > Product Interaction: 画面(screen_viewed)やタップを記録する場合。
  • そのほか attrs や payload に含めるもの(メールアドレス、購入など)は、それぞれのカテゴリで申告します。

サーバーは送信元アドレスの国を追加しますが、アドレス自体は保存されません。