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

SDK

どの言語でも同じモデル。使う言語を選ぶか、HTTP でイベントを送ってください。

Lyrelog の SDK はすべて同じモデル(レベル、領域、属性、ユーザー)を共有し、言語が許す限り同じ名前を、その言語の 命名規則に合わせて使います。違いがある箇所は表のとおりです。

アプリ

SwiftAndroidReact NativeFlutter
開始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 とサーバー

JavaScriptPythonGoJVM
開始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自前の recovercaptureUncaught = 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 のページにあります。

アプリ

設定SwiftAndroidReact NativeFlutterデフォルト
キーapiKeyapiKeyapiKeyapiKey必須:インジェストキー
エンドポイントendpointendpointendpointendpointhttps://ingest.lyrelog.com
環境environmentenvironmentenvironmentenvironment自動検出。環境を参照
プラットフォームplatformplatformplatformplatformOS。プラットフォームを参照
バージョンバンドルからappVersion、なければパッケージからアプリからアプリからresource.app_version として送信
アプリ idバンドルからパッケージ名バンドル id またはパッケージ名バンドル id またはパッケージ名resource.app_id として送信
保持する最低レベルminimumLevelminimumLevelminimumLevelminimumLeveldebug
送信間隔uploadIntervalflushIntervalMillisflushIntervalMsflushInterval15 秒
キューのサイズmaxDiskBytesmaxDiskBytesmaxDiskBytesmaxDiskBytesディスク上に 20 MB
同意consentconsentconsentconsentgranted
アプリの証明(検証済みイベント)appAttestattestattestattestオン

Web とサーバー

設定JavaScriptPythonGoJVMデフォルト
キーapiKeyapi_keyAPIKeyapiKey必須:ブラウザではインジェストキー、サーバーではサーバーキー
エンドポイントendpointendpointEndpointendpointhttps://ingest.lyrelog.com
環境environmentenvironmentEnvironmentenvironment自動検出。環境を参照
プラットフォームplatformplatformPlatformplatform自動検出。プラットフォームを参照
バージョンreleasereleaseReleaserelease、なければ jar のマニフェストresource.app_version として送信
アプリ idappIdapp_idAppIDappId、なければ jar のマニフェストresource.app_id として送信
保持する最低レベルminimumLevelminimum_levelMinimumLevelminimumLeveldebug
送信間隔flushIntervalMsflush_intervalFlushIntervalflushIntervalMillis5 秒
キューのサイズmaxQueuemax_queueMaxQueuemaxDiskBytesメモリ上に 10,000 イベント。JVM ではディスク上に 20 MB
同意consentgranted(ブラウザ)

JavaScript と Go の列では、インスタンスを client と呼んでいます(JavaScript の例では log)。ほかの SDK は Lyrelog または lyrelog モジュールを通してログを記録します。カウンターの名前もそれぞれの言語に合わせてあり、 JavaScript と Python は delivered、Go は Sent を数えます。

イベントが表示されないとき

  1. 環境を確認してください。 ダッシュボードは production で開きます。Swift は Xcode とシミュレーターから、 Android はすべてのデバッグビルドから development を送り、React Native と Flutter のアプリはその下にある ネイティブ SDK と同じ動きをします。JavaScript は localhost で、また Node では NODE_ENV が production でないとき(未設定のときも含む)に development を送ります。トップバーで環境を選ぶか、 All environments を選んでください。
  2. 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。キーが拒否されたとき、 エンドポイントが間違っているとき、バッチが破棄されたときに知らせてくれます。
  3. プロセスが終わる前に送信させてください。 短いスクリプト、サーバーレス関数、exit を呼ぶプロセスは、その前にクライアントをフラッシュするか閉じる必要があります。JVM SDK のシャットダウンフックは 通常の終了時にこれを行いますが、サーバーレスのハンドラーではやはりフラッシュが必要です。各 SDK のページを 参照してください。
  4. 同意とレベルを確認してください。 同意が pending のあいだは何も送信されません。保持する最低レベルより 下のイベントは、キューに入りません。
  5. キーを確認してください。 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 のアペンダーも含めて、どの呼び出しも 何もしません。