Hane Platform

監査ログと使用量

改ざんできない監査ログの仕組みと検索、使用量・予算・モデルの呼出しの数え方、届かなかったイベントの扱いを説明します。

このページでは、Hane が操作をどう記録し、使った量をどう数えるかを説明します。監査ログの読み方と、予算やモデルの使用量を確かめる方法が分かります。

監査ログ

Hane は、組織の中の操作を監査ログに残します。メンバーやロールの変更、API キーの発行と失効、定義の有効化、承認の決定、外への操作の実行、連絡先の値の表示などが対象です。

書き換えられない仕組み

監査ログは追記だけで、書き換える手段も消す手段も持ちません。
記録は前の記録のハッシュとつないで保存し、区切りごとに署名した checkpoint を置きます。途中の記録を差し替えたり抜いたりすると、つながりが合わなくなります。
同じイベントが 2 度届いても、記録は 1 度だけです。
業務の処理と監査の保存は分かれていて、業務の側に監査ログを書き換える権限はありません。

誰が何をしたか

1 件の記録は、次の項目を持ちます。

項目	意味
`type`	何が起きたか（`platform.api_key.created` のようなイベントの種類）
`principal`	元の主体。操作を頼んだ人
`actor`	実行主体。実際に呼んだもの（顧客アプリのサービスアカウントなど）
`engagement_id`・`operator_tenant_id`	運営者の委任を通した操作なら、その委任と運営者の組織
`subject`	操作の対象
`project_id`・`environment`・`request_id`	どこで、どの要求で起きたか
`hash`	前の記録とつないだハッシュ

元の主体と実行主体を分けているので、顧客アプリがサービスアカウントで呼んだ操作でも、どの利用者の操作だったかを追えます。

検索する

GET /v1/audit/events で、新しい順に検索します。audit:read が要ります。

パラメーター	絞り方
`type`	イベントの種類の前方一致（`data.` など）
`actor`	実行主体
`engagement`	運営者の委任を通した操作だけ
`scope`	`project` なら今のプロジェクトだけ、`organization` なら組織全体
`since`・`until`	期間
`cursor`・`limit`	ページ送り

const page = await unwrap(
  client.GET("/v1/audit/events", {
    params: { query: { type: "platform.api_key", scope: "organization", limit: 50 } },
  }),
);

GET /v1/audit/events/{seq} は、1 件の記録と、保存した本体（前の記録のハッシュとつないだもの）を返します。コンソールの「監査ログ」の画面でも同じものを読めます。

監査の保存が止まったとき

監査の保存先に届かない記録が一定の数を超えると、Hane は影響の大きい操作を止めます。API キーの発行、定義の有効化、文書の削除、承認を受けた外への操作の実行などは、503（AUDIT_UNAVAILABLE）で断ります。読む操作と、API キーの失効や緊急停止のような安全側の操作は止めません。保存先が戻れば、溜めた記録を送り直してから再開します。

使用量

API	中身	権限
`GET /v1/usage/daily`	日ごとの数（公開 API の要求の数、API Gateway の呼出しの数など）	`usage:read`
`GET /v1/usage/overview`	ダッシュボードの数字（有効なバージョン、型ごとのレコードの数、ステータスごとの案件と Task の数、スケジュールの数）	`usage:read`
`GET /v1/agents/budget`	今日（UTC）の予算と、使った数・予約した数	`agents:read`
`GET /v1/agents/model-usage`	Model Gateway を通ったモデルの呼出しの、日・Agent・モデルごとの集計	`agents:read`

コンソールの「使用量と予算」の画面は、直近 14 日の使用量、今日の予算、モデルの呼出しの表をまとめて表示します。予算の使った割合が alertAtPercent（既定は 80%）を超えると、画面に警告が出て、usage.budget.alert のイベントも記録されます。

予算

予算はプロジェクトと環境ごとに、platform/v1alpha1 の Budget で決めます。

項目	上限に達したとき
`agentRunsPerDay`	Agent の実行を起動しません
`externalActionsPerDay`	メール・SMS・電話の提案を受け付けません
`modelTokensPerDay`	モデルを使う Agent を起動せず、動いている実行も上限で止めます

日の区切りは UTC です。書き方の例は Agent と AgentRun にあります。

費用について

届かなかったイベント

業務のイベントは、キューを通して監査や通知の処理へ届きます。何度届け直しても処理できなかったイベントは、GET /v1/audit/dead-letters に並びます。原因を直したら、POST /v1/audit/dead-letters/{id}/retry（audit:dead-letters.retry が必要）でキューに入れ直せます。処理する側はイベントの ID で重複を捨てるので、2 回入れ直しても結果は同じです。

次に読む