> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.
# Activity Log 監視
> デバイスからアプリケーションイベントとスクリーンショットをキャプチャ、可視化、クエリする
Activity Log 監視は [BRICKS Foundation](/ja/foundation) デバイスからアプリケーションイベントとスクリーンショットをキャプチャし、クラウドの時系列データベースに保存します。デバイスの動作の分析、ユーザーインタラクションの追跡、アプリケーションの健全性の監視、任意の時点でデバイスに表示されていた内容の視覚的確認に活用できます。
Activity Log 監視は Business プランのワークスペースで利用できます。
## ログを有効にする
[BRICKS Controller](/ja/controller/devices) からデバイスの Activity Log を有効にします：
1. デバイス詳細ページを開く
2. **設定** > **Activity Log** に移動する
3. **有効**をオンにする
**Device Group** タブから Activity Log 設定をデプロイして、グループ内のすべてのデバイスのログを有効にすることもできます。
### イベント ID フィルター
**イベント ID フィルター**フィールドを使って、どのイベントをログに記録するかを制御する正規表現パターンを設定します。ID がパターンに一致するイベントのみがキャプチャされます。空白にするとすべてのイベントがログに記録されます。
## ログに記録される内容
### イベント
各ログエントリには以下が含まれます：
| フィールド | 説明 |
| --------------- | ------------------------------- |
| **イベント名** | イベントタイプの識別子 |
| **タイムスタンプ** | イベントが発生した日時 |
| **Payload** | カスタムのイベント固有のコンテンツ |
| **デバイス ID** | イベントを生成したデバイス |
| **Subspace ID** | Canvas Subspace のコンテキスト（該当する場合） |
| **Sender** | イベントを発したコンポーネントまたはモジュール |
イベントは 3 つのカテゴリに分類されます：
| カテゴリ | イベント名 | 説明 |
| -------------- | -------------------------------------------------- | ---------------------------------------- |
| **General** | `BRICK_*`、`GENERATOR_*`、`CANVAS_*`、`SUBSPACE_*` など | UI インタラクション、ライフサイクルイベント、カスタムアプリケーションイベント |
| **Data** | `PROPERTY_BANK_*` | Property bank の状態更新 |
| **Local Sync** | `LOCAL_SYNC_INFO` | ローカルネットワーク上のデバイス検出と同期アクティビティ |
### スクリーンショット
スクリーンショットキャプチャが有効な場合、[BRICKS Controller](/ja/controller/devices) からスクリーンショットをトリガーでき、JPEG 画像として Activity Log サーバーにアップロードされます。スクリーンショットはタイムスタンプが付けられデバイスごとに保存されるため、任意の時点でデバイスに表示されていた内容を視覚的に確認できます。
スクリーンショットの用途：
* **視覚的な監査** — キャンペーンや特定の時間帯に正しいコンテンツが表示されていたことを確認する
* **インシデント調査** — 異常が発生した際にデバイスに何が表示されていたかを確認する
* **リモート監視** — 物理的なアクセスなしにデプロイ済みデバイスの状態を視覚的に確認する
## イベントのアップロード方法
イベントはデバイスでキャプチャされ、ローカルにキャッシュされた後、定期的にバッチで Activity Log サーバーにアップロードされます（デフォルト：2 分ごと）。ブラウザ環境では、データ損失を最小限に抑えるためにページのアンロード時に最後のアップロードが自動的にトリガーされます。
## スクリーンショット
### スクリーンショットキャプチャの仕組み
有効にすると、BRICKS Controller からスクリーンショットをトリガーでき、キャプチャのタイムスタンプが付けられた JPEG 画像として Activity Log サーバーにアップロードされます。サーバーはデバイスごと・タイムスタンプごとに 1 枚の画像を保存します——同じタイムスタンプで再アップロードすると前の画像が上書きされます。
各画像は 5 MB 未満である必要があります。
### スクリーンショットの閲覧
スクリーンショットは [BRICKS Controller](/ja/controller/devices) または GraphQL API からタイムスタンプで取得できます。screenshots クエリは利用可能なタイムスタンプのリストを返します。ダウンロード API または BRICKS CLI を使って任意のタイムスタンプの画像を取得してください。
```bash theme={null}
# デバイスの利用可能なスクリーンショットを一覧表示する
bricks activity-log screenshots --device --start-time 2024-01-01T00:00:00Z
# 特定のスクリーンショットをダウンロードする
bricks activity-log screenshot --device --ts 2024-01-15T10:30:00Z -o screenshot.jpg --open
```
## GraphQL でクエリする
Activity Log サーバーはイベントとスクリーンショットをクエリするための GraphQL API を提供します。カスタムダッシュボードの構築、外部分析ツールとの統合、ログ分析の自動化に活用できます。
### 認証
すべての GraphQL クエリには `query_activity_log` 権限を持つワークスペース token が必要です。**BRICKS Controller** → **ワークスペース設定** → **Tokens** で作成してください。
### エンドポイント
```
https://activity-log.bricks.tools/api/graphql
```
token を Bearer token として含めます：
```
Authorization: Bearer
```
### クエリ
#### イベントをクエリする
API はカテゴリ別のクエリ（`general_events`、`data_events`、`local_sync_stats`）と、カテゴリをまたいだ取得のための統合 `events` クエリを提供します。同じエンドポイント URL の GraphQL テスト UI でスキーマ全体を確認できます。
```graphql theme={null}
query {
general_events(filter: {
device_id: "your-device-id"
start_time: "2024-01-15T00:00:00Z"
end_time: "2024-01-15T23:59:59Z"
}) @stream {
timestamp
event_name
payload
}
}
```
#### 利用可能なフィルターフィールド
| フィールド | 適用対象 | 説明 |
| ------------- | ----------- | --------------------------------- |
| `device_id` | すべて | デバイスでフィルター |
| `event_type` | `events` のみ | `general`、`data`、または `local_sync` |
| `event_name` | すべて | 特定のイベント名でフィルター |
| `subspace_id` | すべて | Canvas Subspace でフィルター |
| `sender` | すべて | 発したコンポーネントでフィルター |
| `start_time` | すべて | 範囲の開始（ISO 8601） |
| `end_time` | すべて | 範囲の終了（ISO 8601） |
時間範囲クエリはリクエストあたり **30 日**に制限されています。
#### スクリーンショットをクエリする
```graphql theme={null}
query {
screenshots(filter: {
device_id: "your-device-id"
start_time: "2024-01-15T00:00:00Z"
end_time: "2024-01-15T23:59:59Z"
}) @stream {
timestamp
}
}
```
### BRICKS CLI を使う
BRICKS CLI は一般的なクエリパターンの GraphQL API をラップしています：
```bash theme={null}
# フィルターを使ってイベントをクエリする
bricks activity-log events \
--start-time 2024-01-15T00:00:00Z \
--device your-device-id \
--type general \
--event-name BRICK_CLICK \
--limit 100
# JSON として出力する
bricks activity-log events --start-time 2024-01-15T00:00:00Z --device your-device-id -f json
```
### Prometheus 互換 API
メトリクスダッシュボード（Grafana など）向けに、Activity Log は Prometheus 互換 API でもクエリできます。エンドポイント URL と使用例は**ワークスペース設定**の **Activity Log のクエリ**ガイドを参照してください。
## データ保持
### スクリーンショット
スクリーンショットの保持期間は、アップロード時のワークスペースプランによって決まります：
| プラン | スクリーンショット保持期間 |
| -------- | ------------- |
| Free | 7 日 |
| Basic | 90 日 |
| Pro | 90 日 |
| Business | 90 日 |
保持期間を超えたスクリーンショットは自動的に削除されます。プランをアップグレードしても、より低いプランでアップロード済みのスクリーンショットの保持期間は延長されません。
### イベント
イベントには固定の保持期間の制限はありません。
## ユースケース
* **ユーザー行動分析** — ユーザーが Brick とどのようにインタラクションし Canvas を移動するかを追跡する
* **トラブルシューティング** — エラーや予期しない動作の前に何が起きたかを調査する
* **フリート監視** — 複数の展開済みデバイスのイベントパターンを監視する
* **視覚的な監査** — スクリーンショットを確認して正しいコンテンツが表示されていたことを確認する
* **パフォーマンス追跡** — Generator のレスポンスタイムとイベント頻度を分析する
## 次のステップ
デバイス上のランタイム状態をリアルタイムで検査します。
デバイスでエンドツーエンドの自動化テストを実行します。