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

Flutter

ネイティブの Lyrelog SDK の上で、iOS と Android の Flutter アプリから構造化ログを送ります。

iOS と Android のアプリ(ネイティブ SDK の上に構築)

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.0

iOS の設定

  • プラグインは 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-out

await 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_errorFlutterError.onError:ウィジェットのビルド、レイアウト、描画中のエラーと、ジェスチャーのコールバック内のエラーlibrary(widgets library)と context(building MyWidget)
platform_dispatcherPlatformDispatcher.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 領域に送られます。

プラットフォームイベント発生元
iOSapp_crashed(critical)、app_hung(error)、cpu_overuse、disk_write_overuse、slow_launch(warning)MetricKit。Swift のページと同じ
Androidhandled: 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 recording

Consent.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 stop

flush は時間内に終わると 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 に追加します。
  • 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必須プロジェクトのインジェストキー
endpointhttps://ingest.lyrelog.comベース URL。貼り付けた /v1/... のパスは取り除かれます。https のみ、http は localhost と Android エミュレーターの 10.0.2.2 のみ
consentConsent.grantedpending、granted、denied
minimumLevelLogLevel.debugこれより下のイベントは、デバイスのキューに届く前に破棄されます
flushInterval15 秒フォアグラウンドでアップローダーが動く間隔
maxBatchBytes512 KiBバッチは先に達したほうの上限で閉じられます(4 MiB 以内に収められます)
maxBatchEvents500最大 2,000
maxDiskBytes20 MBディスク上のキューの上限。古いものから捨てられます
maxEventAge7 日これより古いキュー内のイベントは破棄されます
sessionTimeout30 分新しいセッションを始めるまでの無操作時間
environment自動検出任意の有効な名前、または null
platformOS任意の有効な名前、または null
redactedKeysnull:defaultRedactedKeysマスクするキー名。指定したリストがデフォルトを置き換え、空のリストでオフになります
captureErrorstrue誰も捕捉しなかった Dart のエラーを報告します
captureNativeCrashestrueiOS:MetricKit のクラッシュ、ハング、使いすぎのレポート。Android:未捕捉の JVM 例外。次回の起動時に送信
attachScreentrueイベントに現在の画面のタグを付けます
attesttrueプロジェクトが設定されていれば、App Attest または Key Attestation でイベントを検証します
mirrorToConsolefalseすべてのイベントをネイティブのログ(Xcode のコンソール、logcat)にも出力します
pauseUploadsInLowPowerModetrueiOS のみ:定期的なアップロードを一時停止します。バックグラウンドに移るときの送信は行われます

配信と上限

配信はネイティブの SDK が行い、Swift や Kotlin のアプリと同じです。

iOSAndroid
ブロックしない呼び出しはイベントをネイティブの 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)。サーバーは送信元アドレスの国を追加しますが、アドレス自体は保存されません。