はじめに

Codatum の監査ログは、ワークスペース上で行われた重要な操作を、監査イベントとして記録する仕組みです。 記録されたイベントから、次の問いに答えられることを目指しています。

• 誰が、どのデータを取り出したのか
• その人はなぜそのデータに到達できたのか

設定ミスや権限の誤付与に気づいたとき、影響範囲を特定するための材料としてご利用ください。 このドキュメントでは、すべてのイベントに共通する構造と、イベントごとの定義を説明します。

記録の対象

上記の2つの問いに答えるうえで必要な操作を、記録の対象としています。

• データの取り出し（SQL の実行、結果の取得、エクスポート、閲覧、外部への送出）
• 到達可能性の変更（権限の付与、公開、招待、資格情報の発行・失効）
• データを保持するリソースのライフサイクルと所在の変更（作成・削除・複製・移動・復元）

ここでいうデータは、コネクション経由で取り出したデータのほか、 そこから得られた集計結果や示唆を載せたコンテンツ（ノートブック、レポート、署名付き埋め込みなど）と、 それらに到達するための資格情報を含みます。

イベントは、操作した主体を特定できる操作について記録します。 認証を必要としない公開コンテンツへのアクセスなど、主体が特定できない操作は記録されません。

定義されているイベントの一覧は 概要 を参照してください。

イベントの例

notebook.rename が1件記録されたときの全体像です。 各イベントページのサンプルは、イベント固有のフィールドだけを抜粋し、残りの Envelope を ... で省略しています。

{
  "event": {
    "uid": "0198f3a2-5c7e-7c31-9a44-6b2f0d8e1a55",
    "code": "notebook.rename",
    "time": "2026-08-14T02:31:07Z"
  },
  "scope": {
    "type": "workspace",
    "workspace_uid": "63e1be654aa70ad689601be0"
  },
  "actor": {
    "principal": {
      "type": "user",
      "uid": "63e1be654aa70ad689601bec",
      "email_addr": "taro@example.com"
    },
    "credential": { "type": "session" },
    "session": { "uid": "0193fa2c-8d4e-7a1b-9c3f-2e5d6a7b8c90" }
  },
  "resource": {
    "type": "notebook",
    "uid": "63e1be654aa70ad689601bf3",
    "name": "Sales KPI",
    "path": "notebook/63e1be654aa70ad689601bf3",
    "parts": [
      { "type": "notebook", "uid": "63e1be654aa70ad689601bf3", "name": "Sales KPI" }
    ]
  },
  "result": { "status": "success" },
  "request": {
    "uid": "0198f3a2-5c7e-7c31-9a44-6b2f0d8e1a56",
    "operation": "UpdateNotebookName",
    "path": "/api/v1/notebooks/63e1be654aa70ad689601bf3",
    "source_ip": "203.0.113.10",
    "user_agent": "Mozilla/5.0 ..."
  },
  "change": {
    "fields": [
      { "name": "name", "old": "Old", "new": "Sales KPI" }
    ]
  }
}

構成

イベントは、種類によらず共通の Envelope を持ちます。 イベント固有の情報も、内容に応じて Envelope 内の型付きフィールドに分かれて入り、 いずれにも該当しないフィールドが extra に入ります。

イベント（Envelope）
├─ event       イベント1件の識別（uid / code / time）
├─ scope       どこで起きたか（workspace / account / system）
├─ actor       誰が・どの資格情報で
├─ resource    何に対して
├─ references  操作対象以外の関連リソース
├─ context     操作の経路に関する情報
├─ result      どうなったか（success / deny / failure）
├─ request     きっかけになった HTTP リクエストの情報
├─ query       データをどう取り出そうとしたかの仕様
├─ outbound    データを Codatum の外へ送出した宛先
├─ change      操作対象自身の属性の変更
├─ grant       権限・ロール・所属の変更
└─ extra       上記のいずれにも該当しない値

event / scope / actor / resource / result はすべてのイベントに付きます。 そのため「いつ・誰が・何に・何をして・どうなったか」は、どのイベントでも同じフィールドから読み取れます。 残りのフィールドは、該当する情報を持つイベントにのみ付きます。 それぞれに何が入るかと、その使い分けは Envelope を参照してください。

イベントの種類は {ドメイン}.{アクション} 形式の event.code で識別します。

識別子と表示名

resource や references、grant などで使われる 表示名（name）やメールアドレス（email_addr）は、ログを読むための手がかりです。 イベント発生時点の値が入り、キャッシュを利用するため、古い値のまま記録されることがあります。 対象を絞り込むときは識別子（uid）をご利用ください。

互換性

新しいイベント、enum の新しい値、新しいフィールドは、予告なく追加されることがあります。 取り込む側では、未知のイベントコード・enum 値・フィールドを無視して動作するように実装してください。

各イベントはステータスを持ちます。 集計の前提にできるのは 安定 のイベントです。

詳しくは 互換性 を参照してください。

リファレンス

知りたいこと	ページ
Envelope の各フィールドの意味と使い分け	Envelope
操作した主体と、認証に使われた資格情報	Actor
操作対象のリソースと、その階層（type / path / parts）	Resource
操作対象以外の関連リソースと、その指し方	References
クエリの仕様（何を・どれだけ取り出すか）	Query
操作対象自身の属性の変更	Change
権限・ロール・所属の変更	Grant
操作の経路に関する情報	Context
データを Codatum の外へ送出した宛先	Outbound
イベントごとの固有フィールドの定義	概要（各ドメインページへ）
イベントのステータスと、定義の変更方針	互換性