SDK
どの言語でも同じモデル。使う言語を選ぶか、HTTP でイベントを送ってください。
Lyrelog の SDK はすべて同じモデル(レベル、領域、属性、ユーザー)を共有し、言語が許す限り同じ名前を、その言語の 命名規則に合わせて使います。違いがある箇所は表のとおりです。
アプリ
Web とサーバー
アプリ
| Swift | Android | React Native | Flutter | |
|---|---|---|---|---|
| 開始 | Lyrelog.start(Configuration(...)) | Lyrelog.start(context, Configuration(...)) | Lyrelog.init({...}) | Lyrelog.start(LyrelogConfiguration(...)) |
| ログ | Lyrelog.info("checkout_done", attrs:) | Lyrelog.info("checkout_done", attrs = ...) | Lyrelog.info("checkout_done", { attrs }) | Lyrelog.info('checkout_done', attrs: {...}) |
| 領域ごとのロガー | Lyrelog.Logger(category: "checkout") | Lyrelog.logger("checkout") | Lyrelog.logger("checkout") | Lyrelog.logger('checkout') |
| ユーザー | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser('u_123') |
| 画面 | Lyrelog.screen("Settings") | Lyrelog.screen("Settings") | trackNavigation(ref) または Lyrelog.screen("Settings") | LyrelogNavigatorObserver() または Lyrelog.screen('Settings') |
| リクエスト | session.loggedData(for:) | |||
| エラーの捕捉 | Lyrelog.captureError(error) | Lyrelog.captureError(e) | Lyrelog.captureException(error) | Lyrelog.captureError(e, stackTrace: s) |
| 未捕捉のエラーとクラッシュ | MetricKit のクラッシュとハング、自動 | 未捕捉の例外、自動、次回起動時に送信 | JavaScript の致命的なエラーとレンダリングエラーはクラッシュとして、Promise の reject やその他のエラーも、さらにネイティブのクラッシュも。自動 | Dart のエラー(FlutterError、PlatformDispatcher)とネイティブのクラッシュ。自動 |
| フラッシュ | await Lyrelog.flush() | Lyrelog.flush()(メインスレッド以外で) | await Lyrelog.flush() | await Lyrelog.flush() |
| 停止 | await Lyrelog.stop() | Lyrelog.stop() | await Lyrelog.close() | await Lyrelog.stop() |
Web とサーバー
| JavaScript | Python | Go | JVM | |
|---|---|---|---|---|
| 開始 | Lyrelog.init({...}) | lyrelog.init(...) | lyrelog.New(lyrelog.Config{...}) | Lyrelog.start(Configuration(...)) |
| ログ | client.info("checkout_done", { attrs }) | lyrelog.info("checkout_done", attrs=) | client.Info("checkout_done", lyrelog.Attrs{}) | Lyrelog.info("checkout_done", attrs = ...) |
| 領域ごとのロガー | client.logger("checkout") | lyrelog.logger("checkout") | client.Logger("checkout") | Lyrelog.logger("checkout") |
| ユーザー | client.setUser("u_123") | lyrelog.set_user("u_123") | client.SetUser("u_123") | Lyrelog.setUser("u_123")、スレッド単位なら Lyrelog.userScope(id) |
| 画面 | client.screen("Settings") | |||
| エラーの捕捉 | client.captureException(err) | lyrelog.capture_exception(exc) | client.CaptureError(err) | Lyrelog.captureError(e) |
| 未捕捉のエラーとクラッシュ | window と Node、自動 | 自前の sys.excepthook | 自前の recover | captureUncaught = true(デフォルトはオフ) |
| フラッシュ | await client.flush() | lyrelog.flush() | client.Flush(ctx) | Lyrelog.flush() |
| 停止 | await client.close() | lyrelog.shutdown() | client.Close() | Lyrelog.close()(終了時はシャットダウンフックが行います) |
| 標準のロギング | lyrelog.LoggingHandler() | lyrelog.NewSlogHandler(client, nil) | Logback 用の LyrelogAppender |
アプリ向けの SDK は、すべてのイベントをプラットフォーム自身のログにもコピーできるので、Xcode や logcat
にも表示されます。Swift では mirrorToOSLog、Android では mirrorToLogcat、React Native では
mirrorToNativeLog、Flutter では mirrorToConsole です。
社内プレビュー
SDK はまだどれも公開されていないため、これらのページのインストールコマンドは現時点ではすべて失敗します。
pnpm add、flutter pub add、uv add はパッケージを見つけられず、Gradle と Maven は Maven Central
で何も見つけられず、Swift Package Manager と go get は非公開のリポジトリにアクセスできません。各ページには、SDK が公開されたときのコマンドを載せています。
どの SDK も代わりにやってくれること
React Native と Flutter の SDK は、iOS では Swift SDK、Android では Android SDK を通して送信するので、 以下はすべてネイティブ SDK の機能として、各プラットフォームのやり方で行われます。JVM SDK は、Android SDK のエンジンをサーバー向けに 設定して動かしています。
- アプリのコードを決してブロックせず、例外も投げません。 ログを記録するとイベントがキューにコピーされてすぐに 戻り、バックグラウンドのワーカーが送信します。
- バッチ送信:1 リクエストあたり最大 500 イベントまたは約 512 KiB、1 イベントにつき NDJSON の 1 行で、 プラットフォームが対応していれば gzip で圧縮します。
- 送信先は
https://ingest.lyrelog.comです(別のendpointを設定しない限り)。エンドポイントはベース URL です。.../v1/events:batchのアドレス全体を貼り付けても、SDK がパスを取り除きます。エンドポイントが間違っている 場合(404やリダイレクト)は、SDK 自身のログに警告として出ます。 - 再試行:一時的な失敗(
408、425、429、5xx、ネットワークエラー)は、ジッター付きの指数バックオフ (1 秒から倍々で最大 5 分)で再試行し、Retry-Afterに従います。flushを呼んだときやクライアントを閉じる ときも同様です。Python 以外の SDK はフルジッター(0 から上限までのランダムな待ち時間)を、Python は イコールジッター(上限の半分から上限まで)を使います。 - 拒否されたバッチは破棄します。 それ以外の 4xx(
400、413、415など)はバッチ自体が不正という意味なので、 再送せずに破棄します。キーが拒否された場合(401、403)は、アプリやプロセスが再起動するまで送信を止め、 イベントは保持します。リダイレクトには決して従いません。3xx はエンドポイントが間違っているという意味なので、 バッチを破棄して警告をログに出します。 429のあいだもイベントを保持します。 Free の組織が月間のイベント数を使い切ったときや、プロジェクトがレート 制限を超えたときは、SDK はバッチを保持し、Retry-Afterのあとに再試行します(HTTP API を参照)。アプリ向けの SDK(Swift、Android、React Native、Flutter)は、起動をまたいでディスクに保持します。JVM SDK もディスクに保持しますが、storageDirectoryを指定しない限り、プロセス用の一時ディレクトリに置きます。 JavaScript、Python、Go はメモリに保持します。いずれの場合も、以下の上限は適用されます。- 待機中のイベントには上限があります。 JavaScript、Python、Go ではデフォルトでメモリ上に 10,000 イベントと 16 MiB、アプリ向けの SDK と JVM ではディスク上に 20 MB と 7 日間です。古いものから捨てられます。
- シークレットをマスクします(どの SDK でも同じ方法です)。フィールド名を小文字にし、
-、_、.、スペースを 除いたものがauthorization、cookie、password、passwd、secret、token、apikey、privatekey、credential(s)、accesskey、signatureのいずれかであるか、それで終わる場合、その値は"[redacted]"になります。つまりX-Api-Key、csrf_token、Set-Cookieはマスクされ、token_countやmax_tokensはマスクされません。属性やペイロードのどの深さでも、切り詰めより前に行われるので、短くした文字列やペイロードの プレビューにシークレットが残ることはありません。チェックするのは名前だけです。メッセージやエラーのテキストの中に あるシークレットは、そのまま送られます。リストはredactedKeys(Swift、Android、Flutter、JVM)、redactKeys(JavaScript、React Native)、redact_keys(Python)、RedactKeys(Go)で変更できます。指定したリストが デフォルトを置き換え、空のリストにするとマスクがオフになります。追加したい場合は、エクスポートされている デフォルトを拡張してください。Swift ではConfiguration.defaultRedactedKeys、Android と JVM ではConfiguration.DEFAULT_REDACTED_KEYS、Flutter ではLyrelogConfiguration.defaultRedactedKeys、 JavaScript、React Native、Python ではDEFAULT_REDACT_KEYS、Go ではDefaultRedactKeys()です。JavaScript と Python の SDK は、任意のイベントを変更または破棄できるbeforeSend/before_sendフックも受け付けます。 - フラッシュ:タイマー(アプリ向けの SDK では 15 秒、Web とサーバーでは 5 秒)、
flushを呼んだとき、 アプリがバックグラウンドに移ったとき、シャットダウン時に行います。 - イベントをサーバーの上限に収めてからキューに入れるので、形が原因でサーバーに拒否される行を送ることは ありません。
設定
どの SDK にも同じ設定があり、それぞれの言語の名前で提供されています。完全な一覧は各 SDK のページにあります。
アプリ
| 設定 | Swift | Android | React Native | Flutter | デフォルト |
|---|---|---|---|---|---|
| キー | apiKey | apiKey | apiKey | apiKey | 必須:インジェストキー |
| エンドポイント | endpoint | endpoint | endpoint | endpoint | https://ingest.lyrelog.com |
| 環境 | environment | environment | environment | environment | 自動検出。環境を参照 |
| プラットフォーム | platform | platform | platform | platform | OS。プラットフォームを参照 |
| バージョン | バンドルから | appVersion、なければパッケージから | アプリから | アプリから | resource.app_version として送信 |
| アプリ id | バンドルから | パッケージ名 | バンドル id またはパッケージ名 | バンドル id またはパッケージ名 | resource.app_id として送信 |
| 保持する最低レベル | minimumLevel | minimumLevel | minimumLevel | minimumLevel | debug |
| 送信間隔 | uploadInterval | flushIntervalMillis | flushIntervalMs | flushInterval | 15 秒 |
| キューのサイズ | maxDiskBytes | maxDiskBytes | maxDiskBytes | maxDiskBytes | ディスク上に 20 MB |
| 同意 | consent | consent | consent | consent | granted |
| アプリの証明(検証済みイベント) | appAttest | attest | attest | attest | オン |
Web とサーバー
| 設定 | JavaScript | Python | Go | JVM | デフォルト |
|---|---|---|---|---|---|
| キー | apiKey | api_key | APIKey | apiKey | 必須:ブラウザではインジェストキー、サーバーではサーバーキー |
| エンドポイント | endpoint | endpoint | Endpoint | endpoint | https://ingest.lyrelog.com |
| 環境 | environment | environment | Environment | environment | 自動検出。環境を参照 |
| プラットフォーム | platform | platform | Platform | platform | 自動検出。プラットフォームを参照 |
| バージョン | release | release | Release | release、なければ jar のマニフェスト | resource.app_version として送信 |
| アプリ id | appId | app_id | AppID | appId、なければ jar のマニフェスト | resource.app_id として送信 |
| 保持する最低レベル | minimumLevel | minimum_level | MinimumLevel | minimumLevel | debug |
| 送信間隔 | flushIntervalMs | flush_interval | FlushInterval | flushIntervalMillis | 5 秒 |
| キューのサイズ | maxQueue | max_queue | MaxQueue | maxDiskBytes | メモリ上に 10,000 イベント。JVM ではディスク上に 20 MB |
| 同意 | consent | granted(ブラウザ) |
JavaScript と Go の列では、インスタンスを client と呼んでいます(JavaScript の例では log)。ほかの SDK は
Lyrelog または lyrelog モジュールを通してログを記録します。カウンターの名前もそれぞれの言語に合わせてあり、
JavaScript と Python は delivered、Go は Sent を数えます。
イベントが表示されないとき
- 環境を確認してください。 ダッシュボードは
productionで開きます。Swift は Xcode とシミュレーターから、 Android はすべてのデバッグビルドからdevelopmentを送り、React Native と Flutter のアプリはその下にある ネイティブ SDK と同じ動きをします。JavaScript はlocalhostで、また Node ではNODE_ENVがproductionでないとき(未設定のときも含む)にdevelopmentを送ります。トップバーで環境を選ぶか、 All environments を選んでください。 - SDK 自身のメッセージを読んでください。 Swift:統合ログ、サブシステム
com.lyrelog.sdk、debug レベル (Console で Include Debug Messages をオンにします)。Android:logcat、タグLyrelog、debug レベル。 React Native と Flutter:ネイティブ SDK のもので、同じ場所に出ます。React Native は、開発ビルドでキーや ネイティブモジュールがないときに Metro でも一度だけ警告します。JavaScript:[lyrelog]で始まるコンソールの行。 Python:lyrelogロガー。Go:Config.ErrorLog。指定しなければ、最初の問題が一度だけ stderr に出力されます。 JVM:標準エラー出力のlyrelog:で始まる行、またはConfiguration.diagnostics。キーが拒否されたとき、 エンドポイントが間違っているとき、バッチが破棄されたときに知らせてくれます。 - プロセスが終わる前に送信させてください。 短いスクリプト、サーバーレス関数、
exitを呼ぶプロセスは、その前にクライアントをフラッシュするか閉じる必要があります。JVM SDK のシャットダウンフックは 通常の終了時にこれを行いますが、サーバーレスのハンドラーではやはりフラッシュが必要です。各 SDK のページを 参照してください。 - 同意とレベルを確認してください。 同意が
pendingのあいだは何も送信されません。保持する最低レベルより 下のイベントは、キューに入りません。 - キーを確認してください。
401や403のあとは、アプリやプロセスが再起動するまで何も送信されません。 キーが空だと何も送信されません(Go ではNewがエラーを返し、JVM ではstartがfalseを返します)。
送ってはいけないもの
message には変わらないイベント名を使い、個人データを含むテキストには決して使わないでください。ユーザーの識別には、
メールアドレスではなく自前の id を使ってください(setUser、user_id)。トークン、パスワード、
リクエストやレスポンスのボディ全体とそのヘッダーは、属性やペイロードに入れないでください。マスクは、
知っているキー名に対する安全網であって、頼りにできるフィルターではありません。
開発中とテスト
- Swift: テストでは
Lyrelog.startを呼ばないでください。startより前に記録されたものは無視されます。 - Android: 同じく、ユニットテストでは
Lyrelog.startを呼ばないでください。デバッグビルドはdevelopmentを送ります。エミュレーターから自分のコンピューター上のエンドポイントに届けるにはいくつか設定が 必要です。開発中とテストを参照してください。 - React Native: テストでは
Lyrelog.initを呼ばないでください。initより前の呼び出しは無視されます。 デバッグビルドはdevelopmentを送ります。 - Flutter: ウィジェットテストやユニットテストでは
Lyrelog.startを呼ばないでください。startより前に記録されたものは無視されます。プラグインが対応していないプラットフォーム(Web、デスクトップ)では、 どの呼び出しも何もしません。開発中とテストを参照してください。 - JavaScript:
apiKeyを空にすると、クライアントは一度だけ警告して何も送信しません。またはconsent: "denied"を渡してください。 - Python:
api_keyを空にすると、イベントを受け付けるが何も送信しないクライアントになります。 - Go:
APIKeyがないとNewはエラーを返し、nilの*Clientは何もしないので、同じコードがクライアントなしでも動きます。 - JVM: キーを指定しないでください。
startがfalseを返し、Logback のアペンダーも含めて、どの呼び出しも 何もしません。