Android
Kotlin または Java で、Android アプリから構造化ログを送ります。Kotlin 標準ライブラリ以外の依存関係はありません。
Android SDK には Android 7.0(API 24)以降が必要です。Kotlin で書かれており、Kotlin 標準ライブラリ以外の 依存関係はなく(OkHttp、コルーチン、AndroidX のいずれも使いません)、すべての関数を Java からも呼び出せます。
社内プレビュー:このパッケージはまだ公開されていません。公開されるまでは Gradle で
com.lyrelog:lyrelog-android を取得できません。Maven Central になく、リポジトリは非公開で、まだリリースも
ありません。
インストール
Maven Central から取得します。アプリモジュールの build.gradle.kts に次を追加します。
dependencies {
implementation("com.lyrelog:lyrelog-android:0.1.0")
}ライブラリはアプリのマニフェストに INTERNET パーミッションを追加します。
開始
できるだけ早い段階で、Application の onCreate で一度だけ開始します。動作中の 2 回目の呼び出しは無視されます。
start より前に記録したイベントも無視されますが、start より前に呼んだ setUser と setConsent
は保持され、開始時に適用されます。
import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Lyrelog
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
Lyrelog.start(this, Configuration(
apiKey = "lyr_ing_...", // ingest-only: it can append events, never read them
))
}
}アプリにまだ Application がない場合は、マニフェストでクラスを指定してください
(<application android:name=".MyApp" ...>)。
イベントは https://ingest.lyrelog.com に送られます。endpoint は別の場所に送るときだけ指定してください。
これはベース URL で(.../v1/events:batch のパスを貼り付けても取り除かれます)、https でなければなりません。
プレーンな http は localhost、127.0.0.1、::1、そしてエミュレーターでは 10.0.2.2 に対してだけ使えます
(開発中とテストを参照)。それ以外のエンドポイントでは何も送信されず、イベントは
デバイスに残ります。
イベントを記録する
レベルごとに関数が 1 つあります。trace、debug、info、notice、warning、error、critical、
または Level を指定する log(level, message, ...) です。
Lyrelog.info("checkout_done", attrs = mapOf("items" to 3, "latency_ms" to ms))
Lyrelog.error("payment_declined", category = "checkout",
attrs = mapOf("code" to 51), payload = mapOf("response" to raw))属性は Map<String, Any?> です。文字列、数値、真偽値、null、リスト(要素は文字列として送られます)、
4 階層までのネストしたマップが使えます。ペイロードは任意のマップ、リスト、値で、1 つのイベントを開いたときに
だけ読む詳細のためのものです。
領域ごとのロガー
ロガーは、Android のログタグと同じように、すべてのイベントに自分の category を付けます。すべてのレベルと、
log、captureError があります。作るのも保持するのも軽く、呼ばれた時点で動いている SDK にログを記録します。
val sync = Lyrelog.logger("sync")
sync.warning("sync_conflict", mapOf("records" to 2))ユーザー
Lyrelog.setUser(playerId) // attached to every following event
Lyrelog.setUser(null) // on sign-outLyrelog.sessionId で現在のセッション id を取得できます。たとえばサポート画面に表示するのに使えます。
ユーザー id は起動をまたいで保存されません。起動のたびに、相手が誰かわかった時点で setUser を改めて呼んでください。
画面
ユーザーがどこにいるかを伝えます。Lyrelog は、直前の画面とそこで過ごした秒数を付けて screen_viewed
(領域 navigation)を記録し、以降のすべてのイベントに screen 属性を付けます。
override fun onResume() {
super.onResume()
Lyrelog.screen("Settings")
}Compose では、デスティネーションが表示されたときに LaunchedEffect から呼び出します。このイベントには
screen、previous_screen、seconds_on_previous が含まれます。同じ名前で screen をもう一度呼んでも
何も記録されません。screen には、screen_viewed イベント用に追加の attrs を渡せます。属性を付ける動作は
attachScreen = false でオフにできます。
automaticScreens = true にすると、前面に来たすべての Activity について、クラス名(SettingsActivity)で
これを行います。デフォルトはオフです。Compose やフラグメントのアプリでは 1 つの Activity に多くの画面があり、
自分で選んだ名前のほうがダッシュボードで読みやすいからです。
捕捉したエラー
try {
store.purchase(product)
} catch (e: IOException) {
Lyrelog.captureError(e, category = "store")
}すべての SDK に共通の exception イベントを送ります。レベルは error、属性は error_type(クラス名)と
error_message、ペイロードには説明、最大 60 フレーム、原因(最大 8 個、それぞれ 20 フレーム)、抑制された
例外が入ります。attrs で独自の属性を追加でき、level でレベルを変えられます。どのロガーにも
captureError があります。
フレームは VM が報告したとおりです。アプリを R8 で難読化している場合は、ビルドのマッピングファイルを使って
retrace を実行すると、元の名前がわかります。
クラッシュ
未捕捉の例外は、終了しようとしているスレッド上でその場でディスクに書き込まれます。ディスクへ書き込み途中だった イベントも一緒です。その後、もともと設定されていたハンドラー(システムのクラッシュダイアログ、または先に ハンドラーを登録した別のクラッシュレポーター)に渡されます。この時点では何も送信されません。プロセスがもうすぐ 終了するからです。
次回の起動時に、発生した時刻と、そのクラッシュで終わったセッションで、diagnostics 領域に送られます。
Swift SDK のクラッシュレポートと同じ形なので、両プラットフォームのクラッシュがダッシュボードに並びます。
| イベント | レベル | 含まれるもの |
|---|---|---|
app_crashed | critical | error_type、error_message、handled: false、mechanism: uncaught_exception、そしてスレッド、フレーム、原因、抑制された例外を含むペイロード |
デフォルトでオンです。captureCrashes = false でオフにできます。ネイティブのクラッシュと ANR は報告されません。
環境とプラットフォーム
開始時に、SDK が環境を選びます。アプリがデバッグ可能(android:debuggable、すべてのデバッグビルド)なら
development、それ以外は production です。
自分のデバッグビルドは development を送りますが、ダッシュボードは production で開きます。それらを見るには、
トップバーで development を選んでください。
プラットフォームは android です。どちらも設定で上書きできます。
Configuration(
apiKey = key,
environment = if (BuildConfig.FLAVOR == "beta") "beta" else null, // null = detected
platform = null,
)名前は自由で、英小文字、数字、-、_ からなる 32 文字以内です。それ以外のテキストは有効な名前に変換されます
(Staging EU は staging-eu になります)。
同意
Lyrelog.start(this, Configuration(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 recordingPENDING はイベントを送信せずにデバイスに保持します。同意が得られない限り、以前の起動で残ったものも含めて
何もアップロードされません。Consent.DENIED で開始すると、以前の起動からキューに残っているものとインストール id
が削除され、何も記録されません。start より前の setConsent は Configuration.consent より優先されます。
同意は起動をまたいで保存されません。ユーザーの選択は自分で保存し、毎回 start に渡してください。
アプリの完全な例
保存した同意で開始し、サインイン時にユーザーを設定し、画面にタグを付けます。
import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Consent
import com.lyrelog.Lyrelog
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
val prefs = getSharedPreferences("settings", MODE_PRIVATE)
val consent = when (prefs.getString("diagnostics", null)) {
"granted" -> Consent.GRANTED
"denied" -> Consent.DENIED
else -> Consent.PENDING
}
Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", consent = consent))
}
}
class HomeActivity : AppCompatActivity() {
override fun onResume() {
super.onResume()
Lyrelog.screen("Home")
}
private fun signedIn(account: Account) {
Lyrelog.setUser(account.id)
Lyrelog.info("signed_in", category = "auth")
}
}
fun choose(context: Context, allowed: Boolean) {
context.getSharedPreferences("settings", Context.MODE_PRIVATE).edit()
.putString("diagnostics", if (allowed) "granted" else "denied").apply()
Lyrelog.setConsent(if (allowed) Consent.GRANTED else Consent.DENIED)
}フラッシュと停止
バックグラウンドに移るときに送信されるので(最後の Activity が停止したとき。画面の回転は含みません)、自分で 行う必要はほとんどありません。
Lyrelog.flushInBackground() // send now, without waiting
Lyrelog.flush() // write everything to disk and send, waiting up to 5 seconds
Lyrelog.stop() // send what's queued (up to 2 seconds), then stop
Lyrelog.stopNow() // stop at once; what was logged goes with the next launchflush と stop はブロックするので、メインスレッドでは決して呼ばないでください。flush は時間内に終わると
true を返し、サーバーが求めた Retry-After を尊重して、それより早くは送信しません。stop のあとに、
もう一度 start を呼べます。
開発中とテスト
ユニットテストでは Lyrelog.start を呼ばないでください。start より前に記録されたものは無視されるので、
ほかのコードはそのまま動きます。mirrorToLogcat = true にすると、開発中はすべてのイベントが logcat
(タグ Lyrelog)にも出力されます。
デバッグビルドは環境 development を送ります。エミュレーターから自分のコンピューター上で動いているエンドポイントに
送るには、デバッグビルドでだけ、http://10.0.2.2 とそのポートをエンドポイントにします(10.0.2.2
はエミュレーターから見た自分のコンピューターです)。
10.0.2.2へのプレーンな http を許可してください。 アプリが許可しない限り Android はこれをブロックします。 デバッグビルドに、そのアドレスだけクリアテキスト通信を許可するネットワークセキュリティ構成を追加してください。- Android 17 で API 37 をターゲットにするアプリは、
ACCESS_LOCAL_NETWORKも必要です。 これがないと10.0.2.2のようなプライベートアドレスに届かず、接続はただタイムアウトします。デバッグ用のマニフェスト (src/debug/AndroidManifest.xml)でパーミッションを宣言し、付与してください:adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK。
これはローカルでの開発のためだけのものです。ホスト型のインジェストは公開の https アドレスなので、
どちらも必要ありません。
検証済みイベント
検証済みイベントとは、アプリや Web ページから公開のインジェストキーをコピーした誰かが送ったものではありえない イベントです。それが何を証明し、何を証明しないかは検証済みイベントにあります。
Android アプリのイベントは Key Attestation で検証されます。スマートフォンのセキュアなハードウェアが、イベントがあなたのアプリから、あなたの証明書で 署名され、root 化もブートローダーのアンロックもされていない実機から来たことを証明します。Lyrelog はこれを自社の サーバーで確認します。Google アカウント、Play Integrity、Google Cloud プロジェクトは一切関係ありません。
デフォルトでオンです(Configuration の attest)。プロジェクト側で設定します。
- Project settings の
Verified events from your Android apps で、パッケージと、イベントを送るビルドに署名するそれぞれの
証明書の SHA-256 フィンガープリントを追加します。Play のアプリ署名鍵(Play Console の Test and release、
App integrity)と、自分で署名するビルドについては
./gradlew signingReportが表示するものです。 - アプリ側の作業はこれだけです。オフにするには次のようにします。
Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", attest = false))インストールごとに 1 回、SDK はスマートフォンのセキュアなハードウェア(StrongBox または Trusted Execution
Environment)にキーを作り、デバイスにそれを attest させます。以降、バッチはトークンを付けて送られ、検証済みとして
届きます(verified_by は key_attestation)。トークンは 24 時間有効で、期限が切れる前にバックグラウンドで
更新されます。送信がこれを待つことはありません。アプリがトークンを持つまでと、何かが失敗したときは、イベントは
未検証で送られます。
- エミュレーターは決して検証されず、SDK もそこでは試みません。
- プロジェクトに Android アプリが設定されるまで、またはキーが拒否されたりデバイスが attest できなかったり した場合、SDK はその起動中は attestation をオフにし、logcat に一度だけそう出力します。
- サーバーが拒否したデバイス(root 化されたスマートフォン、アンロックされたブートローダー、プロジェクトに登録されて いない証明書)は、1 日後に再試行します。
- 同意を拒否すると、attest されたキーとその記録(
noBackupFilesDir/lyrelog/attest.json)が 削除されます。
設定されるまでは、イベントは未検証で届き、1 つのアドレスの 1 日の割り当て
に数えられます。プロジェクトで android からの検証済みイベントだけを受け付けるようにする前に、実際のユーザーの
イベントが検証済みで届いていることをエクスプローラーで確認してください。古いバージョン、エミュレーター、拒否された
デバイスからのイベントは 425 で保留されてしまいます。
自社のサーバーがサーバーキー lyr_srv_... で送るイベントは検証済みになります。サーバーキーは決してアプリに
入れないでください。APK に含めたものは何でも読み取れます。
確認するには、エクスプローラーを開きます。開いたイベントでは、Context の Sender 行に Verified, Key Attestation または Not verified, public key と表示されます。
誰が何を検証するのか、1 日の割り当てについては検証済みイベントを参照してください。
Java から使う
Lyrelog のすべての関数は Java からは static で、省略可能な引数のためのオーバーロードがあります。
Lyrelog.start(this, new Configuration("lyr_ing_..."));
Lyrelog.info("checkout_done");
Lyrelog.captureError(e, "store");Configuration とロガーの関数にもオーバーロードがあるので、末尾の引数は省略できます
(logger.warning("sync_conflict")、logger.warning("sync_conflict", attrs))。
設定
| オプション | デフォルト | 意味 |
|---|---|---|
apiKey | 必須 | プロジェクトのインジェストキー |
endpoint | https://ingest.lyrelog.com | ベース URL。貼り付けた /v1/... のパスは取り除かれます。https のみ、http は localhost とエミュレーターの 10.0.2.2 のみ |
consent | Consent.GRANTED | PENDING、GRANTED、DENIED |
minimumLevel | Level.DEBUG | これより下のイベントはディスクに書かれません |
flushIntervalMillis | 15 秒 | Activity が開始されているあいだにアップローダーが動く間隔 |
maxBatchBytes | 512 KiB | バッチは先に達したほうの上限で閉じられます(4 MiB 以内に収められます) |
maxBatchEvents | 500 | 最大 2,000 |
maxDiskBytes | 20 MB | ディスク上のキューの上限。古いものから捨てられます |
maxEventAgeMillis | 7 日 | これより古いキュー内のイベントは破棄されます |
sessionTimeoutMillis | 30 分 | 新しいセッションを始めるまでの無操作時間 |
environment | 自動検出 | 任意の有効な名前、または null |
platform | android | 任意の有効な名前、または null |
appVersion | アプリの versionName | resource.app_version として送信 |
redactedKeys | null:DEFAULT_REDACTED_KEYS | マスクするキー名。指定したリストがデフォルトを置き換え、空のリストでオフになります |
captureCrashes | true | 未捕捉の例外を記録し、次回の起動時に送信します |
attachScreen | true | イベントに現在の画面のタグを付けます |
automaticScreens | false | Activity ごとに、クラス名で screen_viewed を記録します |
attest | true | Key Attestation でアプリを証明し、プロジェクトにパッケージと証明書が登録されていれば、イベントが検証済みで届くようにします |
mirrorToLogcat | false | すべてのイベントを logcat(タグ Lyrelog)にも出力します |
storageDirectory | noBackupFilesDir/lyrelog | キューの置き場所 |
配信と上限
| ブロックしない | ログの記録はイベントをコピーしてすぐに戻り、バックグラウンドの 1 つのライターがディスクに書き込みます。ネットワークを待つことはありません。 |
| 強制終了やオフラインでも失われない | noBackupFilesDir/lyrelog にあるキューで、上限は 20 MB と 7 日間です。ディスクに届いたものは、クラッシュ、強制終了、何日ものオフラインを乗り越えます。ライターへ渡る途中のイベント(数ミリ秒)はクラッシュハンドラーが書き込みますが、プロセスがいきなり強制終了された場合は失われます。このフォルダーはバックアップに含まれないので、復元したスマートフォンが別のデバイスのイベントを再送することはありません。 |
| 送信のタイミング | Activity が開始されているあいだは 15 秒ごと、そしてアプリがバックグラウンドに移るときに 1 回。バックグラウンドではタイマーは動かず、残ったものは次回の起動時か、次にアプリが前面に来たときに送られます。 |
| バッチ | 1 リクエストあたり最大 500 イベントまたは 512 KiB、gzip で圧縮。エンコード後に 1 MiB を超えるイベントは破棄され、件数が数えられます。 |
| 再試行 | 1 秒から倍々で 5 分まで、フルジッター付きで、Retry-After に従います。それ以外の 4xx はバッチを破棄し、3xx(リダイレクト。決して従いません)も破棄し、失効したキー(401、403)は次の起動まで送信を止めてイベントを保持します。ほかのバッチは通るのにサーバーが失敗し続けるバッチは、後ろに回され、その後破棄されます。 |
| 月間クォータ | Free の組織が月間のイベント数を使い切ると、サーバーは 429 を返します。イベントはディスクのキューに残り、20 MB と 7 日間の上限の範囲内で、サーバーが再び受け付けるようになったら送られます。SDK は logcat に警告を 1 回出し、その後は、あいだに受け付けられたバッチがあった場合にだけ再び出します。 |
| 破棄も確認できる | 上限で失われたイベントは、件数付きの 1 つの lyrelog_events_dropped 警告(領域 lyrelog)になります。 |
| SDK 自身の問題 | エンドポイントの誤り、404、拒否された行、応答しないエンドポイントは、起動ごとに 1 回、logcat のタグ Lyrelog に debug レベルで出ます。 |
| コンテキスト | アプリ id(パッケージ名)、バージョン名、バージョンコード、android、Android のバージョン、デバイス(Google Pixel 9)、ロケール、環境、プラットフォーム android、セッション id(30 分操作がないと新しくなります)、インストール id。 |
| シークレット | 名前が authorization、cookie、password、token、secret、apikey など共通のリストのいずれかであるか、それで終わるキーの値は、どの深さでも、切り詰めより前に "[redacted]" になります。 |
| 上限 | 長い文字列は文字の境界で切られ、余分な属性は lyrelog_dropped_attrs に数えられ、64 KiB を超えるペイロードは {"lyrelog_truncated": true, "bytes": N, "preview": "..."} に要約されます。 |
リストは redactedKeys で変更できます。指定したリストがデフォルトを置き換え、空のリストにするとマスクが
オフになります。追加する場合は次のとおりです。
Lyrelog.start(this, Configuration(
apiKey = "lyr_ing_...",
redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "pin",
))Play のデータセーフティ
Play Console のデータセーフティのフォームでは、アプリが Lyrelog を通して送るものを申告してください。
- App info and performance: Crash logs、Diagnostics(App functionality。そのように使う場合は Analytics も)。 収集あり、共有なし。
- Device or other IDs: インストール id。広告 id ではないランダムな UUID で、バックアップされず、同意が
拒否されると削除されます。
setUserも呼んでいなければ、ユーザーには紐付けられません。 - App activity > App interactions: 画面(
screen_viewed)やタップを記録する場合。 - そのほか
attrsやpayloadに含めるもの(メールアドレス、購入など)は、それぞれのカテゴリで申告します。
データは転送中に暗号化されます(https)。サーバーは送信元アドレスの国を追加しますが、アドレス自体は保存されません。