> ## 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](/zh-Hant/foundation) 裝置的應用程式事件與截圖，並儲存至雲端時間序列資料庫。使用它來分析裝置行為、追蹤使用者互動、監控應用程式健康狀況，並視覺化檢閱裝置在任意時間點所顯示的畫面。

<Info>
  Activity Log 監控適用於 Business 方案的工作區。
</Info>

## 啟用記錄

從 [BRICKS Controller](/zh-Hant/controller/devices) 在裝置上啟用 Activity Log：

1. 開啟裝置詳細頁面
2. 前往**設定** > **Activity Log**
3. 開啟**已啟用**

您也可以透過**Device Group** 分頁部署 Activity Log 設定，為群組中的所有裝置啟用記錄。

### 事件 ID 篩選

使用**事件 ID 篩選**欄位設定 regex 模式，以控制要記錄哪些事件。只有 ID 符合模式的事件才會被擷取。留空則記錄所有事件。

## 記錄的內容

### 事件

每個記錄項目包含：

| 欄位              | 說明                      |
| --------------- | ----------------------- |
| **事件名稱**        | 事件類型的識別碼                |
| **時間戳記**        | 事件發生的時間                 |
| **Payload**     | 自訂的事件特定內容               |
| **裝置 ID**       | 產生事件的裝置                 |
| **Subspace ID** | Canvas Subspace 情境（若適用） |
| **Sender**      | 發出事件的元件或模組              |

事件分為三個類別：

| 類別             | 事件名稱                                              | 說明                    |
| -------------- | ------------------------------------------------- | --------------------- |
| **General**    | `BRICK_*`、`GENERATOR_*`、`CANVAS_*`、`SUBSPACE_*` 等 | UI 互動、生命週期事件及自訂應用程式事件 |
| **Data**       | `PROPERTY_BANK_*`                                 | Property bank 狀態更新    |
| **Local Sync** | `LOCAL_SYNC_INFO`                                 | 區域網路上的裝置探索與同步活動       |

### 截圖

啟用截圖擷取後，可從 [BRICKS Controller](/zh-Hant/controller/devices) 觸發截圖，並以 JPEG 圖片形式上傳至 Activity Log 伺服器。截圖會加上時間戳記並依裝置儲存，讓您能視覺化檢閱裝置在任意時間所顯示的畫面。

截圖適用於：

* **視覺稽核** — 確認在特定行銷活動或時間窗口期間顯示了正確的內容
* **事件調查** — 查看發生異常時裝置確切顯示的畫面
* **遠端監控** — 無需實體存取即可視覺化確認已部署裝置的狀態

## 事件的上傳方式

事件在裝置上被擷取、本機快取後，會定期以批次方式上傳至 Activity Log 伺服器（預設：每 2 分鐘）。在瀏覽器環境中，頁面卸載時會自動觸發最後一次上傳，以將資料遺失降至最低。

## 截圖

### 截圖擷取的運作方式

啟用後，可從 BRICKS Controller 觸發截圖，並以 JPEG 圖片形式上傳至 Activity Log 伺服器，並附上擷取時間戳記。伺服器每台裝置每個時間戳記僅儲存一張圖片——以相同時間戳記重新上傳會取代先前的圖片。

每張圖片必須小於 5 MB。

### 檢視截圖

截圖可透過 [BRICKS Controller](/zh-Hant/controller/devices) 或 GraphQL API 依時間戳記取得。screenshots 查詢會回傳可用時間戳記的清單；使用下載 API 或 BRICKS CLI 取得任意時間戳記的圖片。

```bash theme={null}
# 列出裝置的可用截圖
bricks activity-log screenshots --device <device-id> --start-time 2024-01-01T00:00:00Z

# 下載特定截圖
bricks activity-log screenshot --device <device-id> --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
```

以 Bearer token 方式帶入您的 token：

```
Authorization: Bearer <token>
```

### 查詢

#### 查詢事件

API 提供依類別分類的查詢（`general_events`、`data_events`、`local_sync_stats`）以及用於跨類別取得資料的統一 `events` 查詢。使用同一端點網址的 GraphQL 測試介面瀏覽完整 schema。

```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）                  |

<Warning>
  時間範圍查詢每次請求最多限制 **30 天**。
</Warning>

#### 查詢截圖

```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 查詢。請參閱**工作區設定**中的**查詢 Activity Log** 指南，了解端點 URL 與使用範例。

## 資料保留

### 截圖

截圖保留期限由上傳時的工作區方案決定：

| 方案       | 截圖保留期限 |
| -------- | ------ |
| Free     | 7 天    |
| Basic    | 90 天   |
| Pro      | 90 天   |
| Business | 90 天   |

超過保留期限的截圖會自動刪除。升級方案不會延長在較低方案下已上傳截圖的保留期限。

### 事件

事件沒有固定的保留期限。

## 使用情境

* **使用者行為分析** — 追蹤使用者如何與 Brick 互動並在 Canvas 之間切換
* **疑難排解** — 調查錯誤或非預期行為發生前的情況
* **機隊監控** — 監控多台已部署裝置的事件模式
* **視覺稽核** — 檢閱截圖以確認顯示了正確的內容
* **效能追蹤** — 分析 Generator 回應時間和事件頻率

## 下一步

<CardGroup cols={2}>
  <Card title="除錯面板" icon="bug" href="/zh-Hant/foundation/debug-panel">
    在裝置上即時檢查執行時狀態。
  </Card>

  <Card title="自動化" icon="vial" href="/zh-Hant/foundation/automations">
    在裝置上執行端對端自動化測試。
  </Card>
</CardGroup>