CLI の仕組み
ターミナルでは読みやすいテキストを使います。スクリプトやコーディングエージェントでは--json を使います。
アカウントの読み取りには、アカウントでのログインが必要です。ログインを始める前に logbrew status --json を実行します。ブラウザーでの認可は人が完了する必要があります。プロジェクトの取り込みキーはテレメトリを送信します。アカウントでのログインの代わりにはなりません。
プロジェクトの作成、キーの作成、課題のステータス・優先度・担当者の変更、デプロイ、サポートの更新は、アカウントのデータを変更します。これらを実行する前に、操作と対象が正しいことを確認してください。
すべてのコマンドを表示するには logbrew --help を実行します。logbrew read logs --help のようにコマンドに --help を付けると、そのフラグを表示できます。JSON のルールを確認するには logbrew help json を実行します。
プロジェクトの doctor レポートを読む
logbrew projects --json で得たプロジェクト ID を使います。
status、checks、next があります。各チェックには check、status、next があります。チェックは api、auth、project、ingest_key、setup、telemetry、logs です。
終了コード 0 は、CLI がレポートを書き出したことを示します。プロジェクトの準備ができているという意味ではありません。レポートの status と各チェックを読んでください。not_checked のチェックは合格していません。
プロジェクトの読み取りが成功すると、
logs のチェックは visible、empty、unavailable、error、invalid_response のいずれかになります。このチェックでレポートの status は変わりません。ログの結果が空でも、ほかのシグナルについては何もわかりません。読み取りの失敗は、空の結果とは違います。
next は回復のための案内として使います。アカウントやプロジェクトの状態を変更する許可を与えるものではありません。
例：アカウントのアクセスがない場合
アカウントの認証情報がない場合、このコマンドは API リクエストを送りません。次のレポートを標準出力に書き出し、終了コード0 で終わります。
state、setup_status、next_action は含まれません。
フィルター
--since には、24h や 7d のような期間、または RFC 3339 タイムスタンプを指定できます。--until には RFC 3339 タイムスタンプを指定できます。これは終了時刻で、その時刻自体は含まれず、--since より後である必要があります。ID で1件の課題を読む場合は、--until を指定できません。
ログの重大度は info、warning、error、critical のいずれかです。課題のステータスは課題のワークフロー上の状態で、重大度ではありません。--status ignored は --status archived の古い名前です。--status open は unresolved を、--status closed は resolved を意味します。--assignee none は担当者のいない課題を、--assignee my_teams は自分のチームの課題を選びます。--assignee にそれ以外の値を指定すると、invalid_assignee で失敗します。
CLI は次の別名も受け付けます：--project-id、--env、--service-name、--trace-id、--distinct-id、そして --severity の別名の --level。新しいスクリプトでは、表にある名前を使ってください。
次のコマンドは、1日分のエラーを読みます。
-- を置きます。
課題の発生事象を選ぶ
課題は、一致する発生事象をグループ化したものです。ステータス、発生事象の件数、初回確認と最終確認の時刻を知るには、課題を読みます。explain issue または investigate issue を使います。--occurrence を指定しないと、LogBrew は推奨する発生事象を選びます。これは最新のイベントとは限りません。最新のイベントを読むには次のようにします。
--occurrence には、recommended、first、または LogBrew が返した発生事象の ID も指定できます。これらのコマンドは、プロジェクト、リリース、環境、時刻のフィルターを受け付けません。証拠を比べる前に、選んだ発生事象のタイムスタンプを読みます。証拠のフィールドについては 課題を調査するを参照してください。
課題のステータスと優先度を変更する
1件の課題を変更するには、課題 ID を1つ使います。archive は archived を、resolve は resolved を、reopen は unresolved を設定します。優先度は high、medium、low のいずれかです。設定した優先度は固定されます。設定しない場合、優先度は課題の重大度に従います。
2件以上の課題を変更するには、--project を追加します。すべての課題がそのプロジェクトにある必要があります。1回のコマンドで最大100件の課題を変更できます。
updated、unchanged、not_found のいずれかです。unchanged の課題は、すでに指定した値になっていました。ネットワークの障害の後は、同じコマンドをもう一度実行できます。
これらのコマンドは確認を求めません。先に課題 ID を確認してください。課題の読み取りと変更では、ignored ではなく archived が表示され、各課題の priority、priority_source、assignee も表示されます。課題のレスポンスを参照してください。
課題を割り当てる
担当者は課題ごとに最大1つで、1つのアカウントか1つのチームです。プロジェクトで割り当てられるアカウントとチームを一覧表示します。me）、またはチームに割り当てます。
--project を追加すると、そのプロジェクトの最大100件の課題を変更できます。アカウントはそのプロジェクトを読み取れる必要があり、チームはそのプロジェクトの組織に属している必要があります。自分または自分のチームに割り当てられた課題を探すには次のようにします。
team #<slug> と表示されます。アカウントに名前がない場合はメールアドレスが、それもない場合はユーザー ID が表示されます。担当者のいない課題には unassigned と表示されます。
オーナー、変更履歴、受信トレイ
issues owners は、オーナー候補と、照合に使った証拠を一覧表示します。issues ownership set は、それぞれ 128 KiB 以下のローカルファイルを送信します。空のファイルを送ると、そのテキストは消去されます。issues activity と inbox では、--limit に 1〜200 を指定でき、next_cursor の値を --cursor-time と --cursor-id で渡せます。詳しくは 課題のオーナーを確認するを参照してください。
重大度のルールを設定する
info、warning、error、critical、source のいずれかです。source を指定すると、取得した重大度が再び表示されます。--ignore を付けると、一致するログがデフォルトのログの一覧に表示されなくなります。--ignore を付けない場合、ルールは一致するログを表示します。
次のページを読む
ログ、課題、アクション、メトリクス、トレースは、カーソルベースのページネーションに対応しています。リリースは対応していません。最初のページでは--pagination cursor を使います。
logs と next_cursor があります。next_cursor が null でない場合は、time と id を持ちます。これらを --cursor-time と --cursor-id で送信します。
next_cursor が null になったら止めます。次のページがあるかどうかは、行数ではなくカーソルで判断します。最後のページは空のことがあります。
logs の代わりに issues、actions、metrics を使います。
ライブ監視
logbrew watch --json は、ライブのログ、課題、アクションをストリーミングします。1つの種類だけをストリーミングするには、logs、issues、actions を追加します。tail、follow、stream は watch の別名です。watch はトレースやスパンに対応していません。
watch には --json が必要です。付けないと、コマンドは watch streams JSON for agents と書き出し、終了コード 1 で終わります。
watch の課題イベントでは、アーカイブ済みの課題が優先度なしの ignored として表示されます。現在のステータスと優先度を知るには、課題を読みます。
watch が受け付けるのは --severity だけです。たとえば --severity error,critical のように指定します。logbrew watch actions は --severity を受け付けません。CLI はイベントを受け取った後にこのフィルターを適用します。サーバーが送信する量は減りません。watch には、プロジェクト、リリース、環境、時刻のフィルターがありません。これらのフィルターを使うには read コマンドを使います。一時的に切断された場合、CLI は待ってから再接続します。
結果とエラーを読む
--json はコマンドの前後どちらにも置けます。出力を使う前に終了コードを読みます。人が読むための出力は解析しないでください。バージョンによって変わることがあります。
成功時の出力は、API のレスポンスの形式を保ちます。配列の場合もオブジェクトの場合もあります。カーソルベースのページネーションを使わない場合、ログの読み取りは配列を返します。空の配列は、一致するログがないことを意味します。エラーではありません。
エラーは標準エラー出力に書き出されます。例外は
debug-artifacts --json で、エラーを標準出力に書き出します。JSON のエラーには ok、error、message、next があります。安定した失敗コードとして error を使います。next が示すコマンドを実行する前に、その内容を確認してください。
たとえば、logbrew watch traces --json は終了コード 2 で終わり、次のように書き出します。
logbrew read logs --limit 0 --json は終了コード 2 で終わり、次のように書き出します。