エージェントのワークフローでは
--json を使います。認証情報は、保護されたローカルの設定に保管します。人、ツール、エージェントの間では、変数名だけを受け渡します。始める前に
次を用意します。- Node.js 18 以降。
- LogBrew CLI v0.1.30 以降。
jq。- Bash または Zsh。
- サーバーサイドの Node.js アプリのパッケージディレクトリ。
quickstart-node、環境 development、リリース quickstart@1 を使います。このテストは本番環境と分けておきます。他のランタイムについては、SDK 連携を使います。
最初のログを送信して読む
1
アカウントの状態を確認する
CLI を使うにあるコマンドで CLI をインストールします。次に、アカウントの状態を確認します。確認ポイント:status が、認証済みのアカウントのアクセス権を報告します。報告しない場合は、人が
logbrew login を1回実行します。その後、もう一度 logbrew status --json を実行します。現在の認証が有効なときは、エージェントは新しいログインを始めてはいけません。2
CLI からプロジェクトを1つ作成する
所有者だけがアクセスできるディレクトリで、新しいファイルを指定します。CLI は、成功を報告する前に、プロジェクトの取り込みキーをそのファイルに書き込みます。キーやそのファイルのパスは表示しません。プロジェクトの作成は、アカウントの状態を変更します。保存先のファイルは、まだ存在していてはいけません。結果がはっきりしない場合は、まったく同じコマンドをもう一度実行します。CLI は保留中のリクエストの識別情報を再利用します。別の試行を始めるときだけ
--abandon-retry を使います。確認ポイント:出力に status: "created"、セットアップのステータス created、取り込みキーの種類が表示されます。プロジェクトが作成され、キーが保存されています。これはテレメトリが届いたことを示すものではありません。プロジェクトと設定を参照してください。3
Node.js SDK をインストールする
4
安全な SDK のログを1件送信する
リリースと環境のマーカーを、プレースホルダーだけを含む 認証情報、ヘッダー、リクエストの本文、顧客データ、ローカルのパスをイベントに入れないでください。確認ポイント:スクリプトは、
info ログ1件と一緒に送信します。キーは、この Node.js プロセスだけに設定されます。アプリケーションの識別情報は context に入れます。実行するたびに、新しいイベント ID が作られます。同じ実行の中で SDK が送信を再試行する場合は、同じ本文を同じ ID で送信します。受け付けられたイベントが再試行でもう一度送信されても、LogBrew は2回保存しません。2xx の status_code とともに "ok":true を表示します。再試行した場合、attempts は 1 より大きくなります。送信の成功が最後の確認ではありません。送信に失敗すると、スクリプトはコード 1 で終了し、{"ok":false,"error":"unauthenticated"} のような短い JSON エラーを表示します。リクエストの本文やキーは表示しません。プロジェクトのキーが拒否されると unauthenticated になります。CLI で新しくログインしても解決しません。5
プロジェクトの doctor レポートを読む
この読み取りでは、CLI は保存されたアカウントのアクセス権を使います。プロジェクトの取り込みキーは使わないでください。確認ポイント:レポートに
status: "ready" があります。checks の各項目も読みます。終了コード 0 は、すべてのチェックに合格したことを示しません。他のステータスの場合は、next と doctor レポートのリファレンスに従います。プロジェクトが ready でも、このテストログが届いたことは示しません。6
テストログを読む
SDK のバッチと同じプロジェクト、リリース、環境を使います。確認ポイント:そのプロジェクト、リリース、環境に
LogBrew quickstart check が表示されます。これが示すのは、テストログが届いたことだけです。テストの結果を読む
サンプルは3件のイベントを送信します。そのうちログは1件だけです。リリースと環境のマーカーは、ログにコンテキストを与えます。
テストは
info のままにします。見つけやすくするために error に変えないでください。代わりに、プロジェクトと時間のフィルターを使います。重大度の値を参照してください。
console.log の行は、送信結果をターミナルに表示します。client.log の呼び出しは、ログを LogBrew に送信します。最初の送信に成功すると、次のように表示されます。
--project フィルターはイベントを移動しません。
サンプルはリクエストのスパンを作成しないため、このログにはトレースコンテキストがありません。これはログが失敗したことを示すものではありません。CLI の読み取りは、その時点のスナップショットです。後から届いたイベントを読むにはもう一度実行するか、ライブストリームで見るには logbrew watch logs --json を使います。
よくある復旧の判断
それでもテレメトリが見つからない場合は、最初のテレメトリの確認を行います。それでも解決しない場合は、問題を報告してください。認証情報、加工していないテレメトリ、顧客データ、ローカルのパス、ソースコードは添付しないでください。
自分のアプリケーションに移行する
- クライアントは、アプリのセットアップのコードで1回だけ作成します。
- パッケージファイルで SDK のバージョンを固定します。アップグレードは本番環境の外でテストします。
- 取り込みキーは、既存のシークレットの設定から読み込みます。漏えいした可能性がある場合は、キーをローテーションします。取り込みキーのローテーションを参照してください。
- サービス、環境、リリースには、デプロイ設定にある変わらない名前を使います。リリースを参照してください。
- ログのメッセージには、
Report generation completedのように、処理とその結果を書きます。非公開の値はメッセージに入れないでください。リクエストやユーザーのレコード全体をログにコピーしないでください。 - 重複したレコードを防ぐため、アプリケーションのログごとに送信元を1つにします。LogBrew を追加する前に、各レコードをすでに送信している連携を確認します。
- 本番環境に展開する前に、実際のコードの経路で安全なイベントを1件送信し、読み戻します。メッセージ、サービス、リリース、環境を確認します。単体のサンプルでは、アプリケーションのコードの経路はテストできません。
プロジェクトと設定
セットアップの状態を確認し、プロジェクトの取り込みキーを管理します。
SDK 連携
ランタイムに合った SDK のパッケージを選びます。
課題を調査する
1件の課題について、トレースと関連するログの証拠をたどります。
問題を報告
安全で非公開のサポートの報告を送信します。
