基本概念

Osprey 監看平台上持續發生的事件串流，讓每個事件即時通過規則，並記錄發現的結果，供分析人員查詢及採取行動。本頁定義其他文件與介面使用的術語。這些概念依資料流經 Osprey 的順序排列，後面的概念會建立在前面的概念上，建議依序閱讀。

文件中的範例以使用者可以建立貼文的小型社群網站為情境。同樣的概念也能套用到其他讓人們彼此互動的平台。

Events 與 actions

平台上發生的任何事情，例如註冊帳號、建立貼文、傳送訊息或回應內容，都可以在發生時作為 event 傳送至 Osprey。每個 event 都有名稱，例如 create_post，以及平台一併傳送的 JSON 資料，例如作者的 user ID 與貼文文字 hello world。

Note

您也可能遇到 action 這個術語。Osprey 的 submission API 與規則引擎過去將每個傳入 event 稱為 action，因此查詢列使用 ActionName 篩選，而介面的即時動態則稱為 Event Stream。在這個脈絡中，兩者指的是同一件事，也就是傳入一個 event，並記錄一個 ActionName。

Features

Feature 是規則從每個 event 擷取的具名值，例如 PostText、UserId 或 AccountAgeSeconds。查詢以 Features 為對象，規則定義的每個 Feature 都能依名稱查詢。名稱以底線開頭的 Feature 屬於例外，只供定義該 Feature 的規則檔案內部使用。

以 hello world 貼文為例，規則可能擷取 UserId、PostText 與 EventType 作為 Features。

Entities

Entity 是能在平台上唯一識別某個對象的 Feature，例如 user ID、電子郵件地址或 IP 位址。Entities 會宣告類型，例如 User，讓 Osprey 知道許多 Events 中的哪些值指向同一個對象。這項識別能力讓 Labels 得以運作，也讓介面能在選取 Entity 後，開啟 Osprey 已知的完整資料檢視。

在本頁範例中，UserId 應宣告為 Entity。同一位使用者會多次發文，而 Osprey 需要記住這位使用者。

Rules

Rule 是以 Osprey 規則語言 SML 撰寫、針對 Features 判斷的具名條件。每個 event 抵達時都會通過 Rules 評估。Rule 本身只回傳 True 或 False，而回傳值也能像其他 Feature 一樣查詢。若 Rule 依賴的 Signal 不存在，則回傳 None。Rules 可以連接至 Effects。

以本頁範例來說，Rule 可能判斷「event 是建立貼文，而且貼文文字包含 hello」。

Rules 會以程式碼形式與 Osprey 本身一同放在 Osprey 部署環境中。詳情請見英文官方文件的撰寫規則章節。

Effects

Effect 是 Rule 符合條件後，除了完成評估之外所執行的動作，例如停用使用者、為 Entity 新增 Label 或宣告 Verdict。Effects 會記錄在 event 的執行結果中，讓調查人員事後仍能確認 Osprey 做了什麼以及採取行動的原因。

當 demo 中的 ContainsHello Rule 符合 hello world 貼文時，會觸發兩個 Effects，包括停用作者，以及為該作者新增 meow Label。

Labels

Label 是持續存在於多個 Events 之間的 Entity 標記，也可以視為 Osprey 的記憶。Rules 可以透過 Effect 新增或移除 Labels，也能檢查既有 Labels，讓過去的決定影響後續判斷，例如「若貼文作者先前已被標記為垃圾訊息發布者，則標示這篇貼文」。也可以透過介面為單一 Entity 或批次 Entities 手動新增及移除 Labels。

Labels 包含名稱、適用的 Entity types，以及 positive、negative 或 neutral 的 connotation。Labels 在調查中的使用方式請見 Labels。

Verdicts

Verdict 是呼叫端等待回覆時，Osprey 提供的答案。多數部署會從 Queue 將 Events 傳入 Osprey，再以相同方式讀取結果；服務也可以同步提交 event 並取得回覆。Rules 會宣告 Verdict strings，並連同套用的 Labels 回傳給呼叫端。若部署只以非同步方式消費結果，可能不會直接處理 Verdict，但仍可在介面所記錄的 event Features 中看到它。

Results 及呈現位置

每個處理完成的 event 都會產生執行結果，包括擷取的 Features、符合條件的 Rules，以及觸發的 Effects。結果會建立索引以供查詢，介面中的調查功能都使用這些資料。查詢列能依 Feature 篩選結果，例如 ContainsHello == True；圖表能依時間彙整；Top N 能依任一 Feature 分組；Event Stream 則會逐筆呈現正在發生的 Events。點選 Entity 後，可以查看目前的 Labels 及該 Entity 在平台上的歷史。

引擎如何將結果傳送至這些檢視及平台自己的系統，取決於開發團隊控制的資料管線。詳情請見英文官方文件的資料流章節。

接下來的閱讀方向

執行 demo 後，可以用即時範例資料嘗試這些概念。接著閱讀調查了解查詢流程，或在準備自動化自己的判斷時前往英文官方文件的撰寫規則章節。