Swift
iOS、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-outLyrelog.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_crashed | critical | 例外、シグナル、終了理由、発生したときのバージョンとデバイス、アプリ自身の最上位フレーム、ペイロードに最大 60 フレーム |
app_hung | error | ハングしていた時間 |
cpu_overuse | warning | |
disk_write_overuse | warning | |
slow_launch | warning |
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、visionOS | tvOS | macOS | watchOS | |
|---|---|---|---|---|
platform | ios、visionos | tvos | macos | apple |
| アプリがバックグラウンドに移ったときに送信 | はい | はい | いいえ | いいえ |
| クラッシュとハング(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 stopawait なしで(同期コードから)呼ぶと、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 日の割り当てについては検証済みイベントを参照してください。
設定
| オプション | デフォルト | 意味 |
|---|---|---|
endpoint | https://ingest.lyrelog.com | ベース URL。貼り付けた /v1/... のパスは取り除かれます。https のみ、http は localhost のみ |
apiKey | 必須 | プロジェクトのインジェストキー |
consent | .granted | .pending、.granted、.denied |
minimumLevel | .debug | これより下のイベントはディスクに書かれません |
mirrorToOSLog | false | すべてのイベントを統合ログ(Console、Xcode)にも出力します |
uploadInterval | 15 秒 | フォアグラウンドでアップローダーが起きる間隔 |
pauseUploadsInLowPowerMode | true | 定期的なアップロードを一時停止します。バックグラウンドに移るときの送信は行われます |
maxBatchBytes | 512 KiB | バッチは先に達したほうの上限で閉じられます(64 KiB から 4 MiB の範囲に収められます) |
maxBatchEvents | 500 | 最大 2,000 |
maxDiskBytes | 20 MB | ディスク上のキューの上限。古いものから捨てられます |
maxEventAge | 7 日 | これより古いキュー内のイベントは破棄されます |
sessionTimeout | 30 分 | 新しいセッションを始めるまでの無操作時間 |
storageDirectory | Library/Caches/lyrelog | キューの置き場所 |
captureDiagnostics | true | MetricKit のクラッシュ、ハング、使いすぎのレポート |
attachScreen | true | イベントに現在の画面のタグを付けます |
environment | 自動検出 | 任意の有効な名前、または nil |
platform | OS | 任意の有効な名前、または nil |
appAttest | true | 対応デバイスで 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に含めるもの(メールアドレス、購入など)は、それぞれのカテゴリで申告します。
サーバーは送信元アドレスの国を追加しますが、アドレス自体は保存されません。