Flutter
ネイティブの Lyrelog SDK の上で、iOS と Android の Flutter アプリから構造化ログを送ります。
Flutter SDK は Dart パッケージ lyrelog で、iOS 16 以降と Android 7.0(API 24)以降に対応するプラグインです。
Flutter 3.50 でビルドされています。ネイティブの SDK(iOS では Swift SDK、Android では
Android SDK)の上に載った薄い Dart のレイヤーなので、ディスク上のキュー、ネイティブの
クラッシュ、バックグラウンドでの送信、セッション、同意、検証済みイベントはそれぞれの SDK と同じように動きます。
その上で、誰も捕捉しなかった Dart のエラーを報告し、ナビゲーターから画面に名前を付けます。
社内プレビュー:このパッケージはまだ公開されていません。公開されるまでは flutter pub add lyrelog
は何も見つけられません。pub.dev になく、リポジトリは非公開で、まだリリースもありません。
インストール
flutter pub add lyrelogまたは pubspec.yaml に次を追加します。
dependencies:
lyrelog: ^0.1.0iOS の設定
- プラグインは Swift パッケージなので、アプリは Swift Package Manager でビルドします。Flutter はデフォルトで これを使います。CocoaPods 版はありません。
- アプリの最小バージョンを iOS 16 にしてください。Xcode で Runner ターゲットの General、Minimum
Deployments です(
IPHONEOS_DEPLOYMENT_TARGET = 16.0)。Flutter のデフォルトはこれより低く、そのままだと その旨のメッセージを出してビルドが止まります。
Android の設定
- Flutter のデフォルトで動きます:compileSdk 36、Kotlin 2.2 以降。
minSdkは 24 のままで構いません。
ライブラリはアプリのマニフェストに INTERNET パーミッションを追加します。
開始
できるだけ早い段階で、main の runApp より前で一度だけ開始します。動作中の 2 回目の呼び出しは無視されます。
start は自分で WidgetsFlutterBinding.ensureInitialized() を呼ぶので最初に置けますし、その完了を待つ必要も
ありません。start のあとに記録したものは、そのあとでネイティブの SDK に届きます。start より前に記録した
イベントは無視されますが、start より前に呼んだ setUser と setConsent は保持され、開始時に適用されます。
import 'package:flutter/widgets.dart';
import 'package:lyrelog/lyrelog.dart';
void main() {
Lyrelog.start(const LyrelogConfiguration(
apiKey: 'lyr_ing_...', // ingest-only: it can append events, never read them
));
runApp(const MyApp());
}イベントは https://ingest.lyrelog.com に送られます。endpoint は別の場所に送るときだけ指定してください。
これはベース URL で(.../v1/events:batch のパスを貼り付けても取り除かれます)、https でなければなりません。
プレーンな http は localhost、127.0.0.1、::1、そして Android エミュレーターでは 10.0.2.2
に対してだけ使えます(開発中とテストを参照)。それ以外のエンドポイントでは何も
送信されず、イベントはデバイスに残ります。
イベントを記録する
レベルごとに関数が 1 つあります。trace、debug、info、notice、warning、error、critical、
または LogLevel を指定する log(level, message, ...) です。
Lyrelog.info('checkout_done', attrs: {'items': 3, 'latency_ms': ms});
Lyrelog.error('payment_declined', category: 'checkout',
attrs: {'code': 51}, payload: {'response': raw});属性は Map<String, Object?> です。文字列、数値、真偽値、null、リスト、4 階層までのネストしたマップが
使えます。DateTime は ISO 8601 のテキストとして、Duration はミリ秒として、enum はその名前として、それ以外は
toString() として送られます。ペイロードはこれらの種類の任意の値で、1 つのイベントを開いたときにだけ読む詳細の
ためのものです。
領域ごとのロガー
ロガーは、ログタグと同じように、すべてのイベントに自分の category を付けます。すべてのレベルと、log、
captureError があります。作るのも保持するのも軽く、呼ばれた時点で動いている SDK にログを記録します。
final sync = Lyrelog.logger('sync');
sync.warning('sync_conflict', attrs: {'records': 2});ユーザー
Lyrelog.setUser(account.id); // attached to every following event
Lyrelog.setUser(null); // on sign-outawait Lyrelog.sessionId() で現在のセッション id を取得できます。たとえばサポート画面に表示するのに使えます。
ユーザー id は起動をまたいで保存されません。起動のたびに、相手が誰かわかった時点で setUser を改めて呼んでください。
画面
ユーザーがどこにいるかを伝えます。Lyrelog は、直前の画面とそこで過ごした秒数を付けて screen_viewed
(領域 navigation)を記録し、以降のすべてのイベントに screen 属性を付けます。
アプリのナビゲーターに LyrelogNavigatorObserver を追加すると、一番上に来たページルートがそれぞれ画面になり、
ルート名がその名前になります。
MaterialApp(
navigatorObservers: [LyrelogNavigatorObserver()],
routes: {
'/': (_) => const HomePage(),
'/settings': (_) => const SettingsPage(),
},
)どの Navigator でも動くので、observer を受け付けるルーターでも使えます(go_router なら
GoRouter(observers: [LyrelogNavigatorObserver()], ...))。ページに戻ると、再びその画面になるので、もう一度
記録されます。ダイアログ、ボトムシート、メニューでは画面は変わらず、名前のないルートはスキップされます。
どちらも変更できます。
LyrelogNavigatorObserver(
nameExtractor: (settings) => settings.name?.replaceFirst('/', ''), // null or '' skips the route
routeFilter: (route) => route is PageRoute, // which routes are screens
)または自分で呼び出します。
Lyrelog.screen('Settings');このイベントには screen、previous_screen、seconds_on_previous が含まれます。同じ名前で screen
をもう一度呼んでも何も記録されません。screen には、screen_viewed イベント用に追加の attrs を渡せます。
属性を付ける動作は attachScreen: false でオフにできます。
捕捉したエラー
try {
await store.purchase(product);
} catch (e, s) {
Lyrelog.captureError(e, stackTrace: s, category: 'store');
}すべての SDK に共通の exception イベントを送ります。レベルは error、属性は error_type(実行時の型)と
error_message(その toString())、ペイロードには説明と最大 60 フレームのスタックが入ります。stackTrace
がない場合、Error が自分のスタックを持っていればそのフレームが使われます。attrs で独自の属性を追加でき、
level でレベルを変えられます。どのロガーにも captureError があります。
エラーとクラッシュ
誰も捕捉しない Dart のエラー
start はこれらを自動で報告します(captureErrors、デフォルトでオン)。handled: false と、Flutter が
どこでそれを渡したかを示す mechanism を付けた exception イベントになります。
mechanism | 発生元 | ペイロードにはさらに |
|---|---|---|
flutter_error | FlutterError.onError:ウィジェットのビルド、レイアウト、描画中のエラーと、ジェスチャーのコールバック内のエラー | library(widgets library)と context(building MyWidget) |
platform_dispatcher | PlatformDispatcher.instance.onError:非同期コード、タイマー、誰も await しなかった Future のエラー |
もともとあったハンドラーは、Lyrelog のものの後に引き続き実行され、PlatformDispatcher.onError は以前の
ハンドラーが返したものを返します(以前のハンドラーがなくても、Flutter はエラーを出力します)。独自のハンドラーを
設定する場合は、start より前に設定するか、そこから captureError を呼んでください。
送られるのは 1 分あたり最大 10 件で、同じエラー(型、メッセージ、最上位フレーム)は 10 秒に 1 回だけです。 そのため、毎フレーム繰り返されるレイアウトエラーでもイベントは 1 つです。Flutter が silent とマークし、リリース ビルドでも報告しないエラー(たとえば読み込みに失敗した画像)は除外されます。
Dart のエラーで Flutter アプリが終了することはないので、これらは exception イベントで、app_crashed
になることはありません。
アプリが独自のゾーンで動いている場合は、そのゾーンのエラーも同じように報告してください。
runZonedGuarded(() => runApp(const MyApp()), (error, stack) {
Lyrelog.captureError(error, stackTrace: stack, handled: false, mechanism: 'zone');
});ネイティブのクラッシュ
アプリ自体のクラッシュはネイティブの SDK から取得します(captureNativeCrashes、デフォルトでオン)。
次回の起動時に、発生した時刻で、diagnostics 領域に送られます。
| プラットフォーム | イベント | 発生元 |
|---|---|---|
| iOS | app_crashed(critical)、app_hung(error)、cpu_overuse、disk_write_overuse、slow_launch(warning) | MetricKit。Swift のページと同じ |
| Android | handled: false と mechanism: uncaught_exception 付きの app_crashed(critical) | 未捕捉の JVM 例外。Android のページと同じ |
Android では、ネイティブ(C や C++)のクラッシュと ANR は報告されません。
難読化したビルド
flutter build --obfuscate --split-debug-info=<dir> を使うと、error_type の型名とフレームは難読化されます。
ビルドが書き出すシンボルを保存しておき、それを使ってフレームに flutter symbolize を実行すると読めるようになります。
環境とプラットフォーム
ネイティブの SDK が、開始時に環境を選びます。
- iOS:Debug ビルド、シミュレーター上のすべてのビルド、またはプロビジョニングプロファイルが埋め込まれたビルド
(development と ad hoc の署名)は
development、TestFlight のビルドはtestflight、それ以外はproduction。その後は Swift のページと同じく StoreKit の応答に従います。 - Android:アプリがデバッグ可能(すべてのデバッグビルド)なら
development、それ以外はproduction。
自分で flutter run したビルドは development を送りますが、ダッシュボードは production で開きます。
それらを見るには、トップバーで development を選んでください。
プラットフォームは OS(ios または android)なので、1 つのプロジェクトに両方を入れ、ダッシュボードでそれぞれに
絞り込めます。どちらも設定で上書きできます。
LyrelogConfiguration(
apiKey: key,
environment: isInternalTester ? 'internal' : null, // null = detected
platform: null,
)名前は自由で、英小文字、数字、-、_ からなる 32 文字以内です。それ以外のテキストは有効な名前に変換されます
(Staging EU は staging-eu になります)。
同意
Lyrelog.start(LyrelogConfiguration(apiKey: key, consent: Consent.pending));
// later, when the person chooses:
Lyrelog.setConsent(Consent.granted); // sends, including what was kept while pending
Lyrelog.setConsent(Consent.denied); // deletes everything and stops recordingConsent.pending はイベントを送信せずにデバイスに保持します。同意が得られない限り、以前の起動で残ったものも
含めて何もアップロードされません。Consent.denied で開始すると、以前の起動からキューに残っているものと
インストール id が削除され、何も記録されません。start より前の setConsent は、設定の consent より優先されます。
同意は起動をまたいで保存されません。ユーザーの選択は自分で保存し、毎回 start に渡してください。
アプリの完全な例
保存した同意で開始し、サインイン時にユーザーを設定し、ナビゲーターから画面に名前を付けます。
import 'package:flutter/material.dart';
import 'package:lyrelog/lyrelog.dart';
import 'package:shared_preferences/shared_preferences.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
final prefs = await SharedPreferences.getInstance();
final consent = switch (prefs.getString('diagnostics')) {
'granted' => Consent.granted,
'denied' => Consent.denied,
_ => Consent.pending,
};
Lyrelog.start(LyrelogConfiguration(apiKey: 'lyr_ing_...', consent: consent));
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) => MaterialApp(
navigatorObservers: [LyrelogNavigatorObserver()],
routes: {
'/': (_) => const HomePage(),
'/sign-in': (_) => SignInPage(onSignedIn: signedIn),
},
);
}
void signedIn(Account account) {
Lyrelog.setUser(account.id);
Lyrelog.info('signed_in', category: 'auth');
}
Future<void> choose(bool allowed) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString('diagnostics', allowed ? 'granted' : 'denied');
Lyrelog.setConsent(allowed ? Consent.granted : Consent.denied);
}フラッシュと停止
バックグラウンドに移るときに送信されます。iOS ではバックグラウンドタスクの中で、Android ではアプリの Activity が停止したときです。そのため、自分で行う必要はほとんどありません。
await Lyrelog.flush(); // write everything to disk and send, waiting up to 5 seconds
await Lyrelog.stop(); // send what's queued (up to 2 seconds), then stopflush は時間内に終わると true を返し(待ち時間は timeout: で変えられます)、サーバーが求めた
Retry-After を尊重して、それより早くは送信しません。stop のあとに、もう一度 start を呼べます。
開発中とテスト
ウィジェットテストやユニットテストでは Lyrelog.start を呼ばないでください。start より前に記録されたものは
無視されるので、ほかのコードはそのまま動きます。プラグインが対応していないプラットフォーム(Web、デスクトップ)
では、どの呼び出しも何もせず、例外も投げません。
mirrorToConsole: true にすると、開発中はすべてのイベントがネイティブのログにも出力されます。iOS では Xcode
のコンソール、Android では logcat(タグ Lyrelog)です。
デバッグビルドは環境 development を送ります。自分のコンピューター上で動いているエンドポイントに送るには、
次のようにします。
- iOS シミュレーター:
http://127.0.0.1とそのポートを使います。シミュレーターはコンピューターのネットワークを 共有しており、そのための App Transport Security の例外も必要ありません。 - Android エミュレーター:デバッグビルドでだけ、
http://10.0.2.2とそのポートを使います(10.0.2.2はエミュレーターから見た自分のコンピューターです)。10.0.2.2へのプレーンな http を許可してください。 アプリが許可しない限り Android はこれをブロックします。 デバッグビルド(android/app/src/debug)に、そのアドレスだけクリアテキスト通信を許可するネットワーク セキュリティ構成を追加してください。- Android 17 で API 37 をターゲットにするアプリは、
ACCESS_LOCAL_NETWORKも必要です。 これがないと10.0.2.2のようなプライベートアドレスに届かず、接続はただタイムアウトします。デバッグ用のマニフェスト (android/app/src/debug/AndroidManifest.xml)でパーミッションを宣言し、付与してください:adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK。
キーは --dart-define-from-file を使ってソースコードに含めないようにしましょう。たとえば
flutter run --dart-define-from-file=lyrelog.local.json と String.fromEnvironment('LYRELOG_KEY')
を使い、そのファイルは git の管理対象外にします。
これはローカルでの開発のためだけのものです。ホスト型のインジェストは公開の https アドレスなので、
どれも必要ありません。
検証済みイベント
検証済みイベントとは、アプリや Web ページから公開のインジェストキーをコピーした誰かが送ったものではありえない イベントです。それが何を証明し、何を証明しないかは検証済みイベントにあります。
ネイティブの SDK が実機上でアプリを検証し(attest、デフォルトでオン)、Dart のコードは何も変わりません。
アプリを配布する各プラットフォームを設定してください。
- iOS、Apple の App Attest(
verified_byはapp_attest):- Xcode で Runner ターゲットに 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)を、 Project settings の Verified events from your Apple apps に追加します。
- Xcode で Runner ターゲットに App Attest capability(Signing & Capabilities)、つまりエンタイトルメント
- Android、Key Attestation
(
verified_byはkey_attestation):Project settings の Verified events from your Android apps で、パッケージと、イベントを送るビルドに署名するそれぞれの 証明書の SHA-256 フィンガープリントを追加します。Play のアプリ署名鍵(Play Console の Test and release、 App integrity)と、自分で署名するビルドについては./gradlew signingReportが表示するもの(アプリのandroidフォルダーで実行します)です。
両方でオフにするには次のようにします。
Lyrelog.start(const LyrelogConfiguration(apiKey: 'lyr_ing_...', attest: false));送信がこれを待つことはありません。アプリがトークンを持つまでと、何かが失敗したときは、イベントは未検証で 送られます。プロジェクトでプラットフォームが設定されるまで、SDK はその起動中は試行をやめます。
- iOS シミュレーターと Android エミュレーターは決して検証されません。
- サーバーが拒否したデバイス(root 化されたスマートフォン、アンロックされたブートローダー、プロジェクトに登録されて いない証明書)は未検証のイベントを送ります。Android は 1 日後に再試行します。
- 同意を拒否すると、両方のプラットフォームで attest されたキーの記録が削除されます。
プロジェクトで ios や android からの検証済みイベントだけを受け付けるようにする前に、実際のユーザーの
イベントが検証済みで届いていることをエクスプローラーで確認してください。古いバージョン、シミュレーター、
エミュレーター、拒否されたデバイスからのイベントは 425 で保留されてしまいます。サーバーキー(lyr_srv_...)
は決してアプリに入れないでください。アプリに含めたものは何でも読み取れます。
確認するには、エクスプローラーを開きます。開いたイベントでは、Context の Sender 行に Verified, App Attest、Verified, Key Attestation、または Not verified, public key と表示されます。
設定
| オプション | デフォルト | 意味 |
|---|---|---|
apiKey | 必須 | プロジェクトのインジェストキー |
endpoint | https://ingest.lyrelog.com | ベース URL。貼り付けた /v1/... のパスは取り除かれます。https のみ、http は localhost と Android エミュレーターの 10.0.2.2 のみ |
consent | Consent.granted | pending、granted、denied |
minimumLevel | LogLevel.debug | これより下のイベントは、デバイスのキューに届く前に破棄されます |
flushInterval | 15 秒 | フォアグラウンドでアップローダーが動く間隔 |
maxBatchBytes | 512 KiB | バッチは先に達したほうの上限で閉じられます(4 MiB 以内に収められます) |
maxBatchEvents | 500 | 最大 2,000 |
maxDiskBytes | 20 MB | ディスク上のキューの上限。古いものから捨てられます |
maxEventAge | 7 日 | これより古いキュー内のイベントは破棄されます |
sessionTimeout | 30 分 | 新しいセッションを始めるまでの無操作時間 |
environment | 自動検出 | 任意の有効な名前、または null |
platform | OS | 任意の有効な名前、または null |
redactedKeys | null:defaultRedactedKeys | マスクするキー名。指定したリストがデフォルトを置き換え、空のリストでオフになります |
captureErrors | true | 誰も捕捉しなかった Dart のエラーを報告します |
captureNativeCrashes | true | iOS:MetricKit のクラッシュ、ハング、使いすぎのレポート。Android:未捕捉の JVM 例外。次回の起動時に送信 |
attachScreen | true | イベントに現在の画面のタグを付けます |
attest | true | プロジェクトが設定されていれば、App Attest または Key Attestation でイベントを検証します |
mirrorToConsole | false | すべてのイベントをネイティブのログ(Xcode のコンソール、logcat)にも出力します |
pauseUploadsInLowPowerMode | true | iOS のみ:定期的なアップロードを一時停止します。バックグラウンドに移るときの送信は行われます |
配信と上限
配信はネイティブの SDK が行い、Swift や Kotlin のアプリと同じです。
| iOS | Android | |
|---|---|---|
| ブロックしない | 呼び出しはイベントをネイティブの SDK に渡してすぐに戻り、バックグラウンドの 1 つのライターがディスクに書き込みます。ネットワークを待つことはありません。 | 同じです。 |
| 強制終了やオフラインでも失われない | Library/Caches にあるキューで、上限は 20 MB と 7 日間です。デバイスの空き容量が少ないとシステムが Caches を消去することがあり、そのとき待機中のイベントも一緒に消えます。 | noBackupFilesDir/lyrelog にあるキューで、上限は 20 MB と 7 日間です。バックアップに含まれないので、復元したスマートフォンが別のデバイスのイベントを再送することはありません。 |
| 送信のタイミング | フォアグラウンドでは 15 秒ごと(低電力モードでは一時停止)、そしてアプリがバックグラウンドに移るときに、バックグラウンドタスクの中で。 | アプリの Activity が開始されているあいだは 15 秒ごと、そしてバックグラウンドに移るとき。バックグラウンドではタイマーは動かず、残ったものは次回の起動時か、次にアプリが前面に来たときに送られます。 |
| バッチ | 1 リクエストあたり最大 500 イベントまたは 512 KiB、gzip で圧縮。エンコード後に 1 MiB を超えるイベントは破棄され、件数が数えられます。 | 同じです。 |
| 再試行 | 1 秒から倍々で 5 分まで、フルジッター付きで、Retry-After に従います。それ以外の 4xx はバッチを破棄し、3xx(リダイレクト。決して従いません)も破棄し、失効したキー(401、403)は次の起動まで送信を止めてイベントを保持します。ほかのバッチは通るのにサーバーが失敗し続けるバッチは、後ろに回され、その後破棄されます。 | 同じです。 |
| 月間クォータ | Free の組織が月間のイベント数を使い切ると、サーバーは 429 を返します。イベントはディスクのキューに残り、20 MB と 7 日間の上限の範囲内で、サーバーが再び受け付けるようになったら送られます。統合ログ(サブシステム com.lyrelog.sdk)に警告が 1 回出ます。 | 同じです。警告は logcat(タグ Lyrelog)に出ます。 |
| 破棄も確認できる | 上限で失われたイベントは、件数付きの 1 つの lyrelog_events_dropped 警告(領域 lyrelog)になります。 | 同じです。 |
| SDK 自身の問題 | エンドポイントの誤り、拒否されたキー、拒否された行は、起動ごとに 1 回、統合ログのサブシステム com.lyrelog.sdk に debug レベルで出ます。 | 同じく logcat のタグ Lyrelog に debug レベルで出ます。 |
| コンテキスト | アプリ id、バージョン、ビルド、OS、デバイスモデル(iPhone18,1)、ロケール、プラットフォーム ios、セッション id(30 分操作がないと新しくなります)、インストール id。sdk は lyrelog-flutter/0.1.0 lyrelog-swift/0.1.0。 | アプリ id(パッケージ名)、バージョン名、バージョンコード、Android のバージョン、デバイス(Google Pixel 9)、ロケール、プラットフォーム android、セッション id、インストール id。sdk は lyrelog-flutter/0.1.0 lyrelog-android/0.1.0。 |
| シークレット | 名前が authorization、cookie、password、token、secret、apikey など共通のリストのいずれかであるか、それで終わるキーの値は、どの深さでも、切り詰めより前に "[redacted]" になります。 | 同じです。 |
| 上限 | 長い文字列は文字の境界で切られ、余分な属性は lyrelog_dropped_attrs に数えられ、64 KiB を超えるペイロードは {"lyrelog_truncated": true, "bytes": N, "preview": "..."} に要約されます。 | 同じです。 |
マスクするキーのリストは redactedKeys で変更できます。指定したリストがデフォルトを置き換え、空のリストにすると
マスクがオフになります。追加する場合は次のとおりです。
Lyrelog.start(const LyrelogConfiguration(
apiKey: 'lyr_ing_...',
redactedKeys: [...LyrelogConfiguration.defaultRedactedKeys, 'pin'],
));App Store のプライバシーと Play のデータセーフティ
Swift SDK のプライバシーマニフェスト(PrivacyInfo.xcprivacy)はアプリの中に含まれ、
Swift のページと同じく、Xcode がアプリのプライバシー
レポートに統合します。
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)やタップを記録する場合。
Play Console のデータセーフティのフォームでは次のとおりです。
- App info and performance: Crash logs、Diagnostics(App functionality。そのように使う場合は Analytics も)。 収集あり、共有なし。
- Device or other IDs: インストール id(上記と同じ)。
- App activity > App interactions: 画面やタップを記録する場合。
どちらでも、そのほか attrs や payload に含めるもの(メールアドレス、購入など)は、それぞれのカテゴリで申告します。
データは転送中に暗号化されます(https)。サーバーは送信元アドレスの国を追加しますが、アドレス自体は保存されません。