Lookup Tables 是 Graylog 中一項強大的資料查詢與擴充功能，可將外部資料源快速映射至日誌事件字段，實現地理位置、風險評級、用戶資訊等豐富擴展。

什麼是 Lookup Tables

Lookup Tables 由三個關鍵元件組成：

• Data Adapter（數據適配器）：負責從外部來源讀取映射表資料。
• Cache（快取）：暫存 Data Adapter 讀取結果，提升查詢效能並減少後端壓力。
• Lookup Table（查找表）：結合 Adapter 與 Cache，對外提供「鍵 → 值」查詢介面。

透過 Lookup Tables，我們可以將 log 事件中的文字（如 IP、使用者 ID、Error Code）作為「鍵」，查詢對應映射值（如 地理區域、使用者名稱、錯誤訊息描述），並將結果寫回事件。

基本配置步驟

1. 建立 Data Adapter

   • 在 Graylog Web → System/Lookup Tables → Data Adapters 標籤 → Create data adapter.
   • 選擇 CSV File，設定檔案路徑、分隔符號與 key / value 對應欄位。

2. 建立 Cache

   • 前往 Caches 標籤 → Create cache.
   • 選擇快取類型：
     • Node-local, in-memory cache：基於 Caffeine 引擎的本地記憶體快取，適合頻繁查詢且資料相對穩定的場景。可設定最大條目數（Maximum entries）、過期時間（Expire after access/write）等參數。重啟節點後快取會清空。
     • No caching：不使用快取機制，每次查詢直接從 Data Adapter 讀取。適合資料經常變動或記憶體資源有限的環境。
   • 若選擇記憶體快取，建議設定合理的最大條目數以避免記憶體溢位。
   • 可勾選 Ignore empty results 選項，避免快取空值結果，減少無效快取佔用。

3. 建立 Lookup Table

   • 進入 Lookup Tables → Create new.
   • 選擇剛才建立的 Adapter 與 Cache，命名為 ip_geo_lookup（範例）。

4. 測試與驗證

   • 在 Lookup Tables 列表，點選 Run Lookup，輸入測試鍵值（如：8.8.8.8）。
   • 如能正確返回結果，表示配置成功。

實際應用與 Pipeline 整合

下一步，可在 Pipeline 中使用 Lookup Tables 進行事件擴充。以下示範：

rule "Enrich with Geo"
when
  has_field("client_ip")
then
  let geo = lookup("ip_geo_lookup", to_string($message.client_ip));
  set_field("geo_country", geo["country"]);
end

此規則將提取 log 事件的 client_ip 欄位，查詢對應地理國家，並將結果寫入新欄位 geo_country。

使用注意事項

• 效能考量：大量查詢時，建議採用分散式快取（如 Redis）以減低 In-Memory Cache 單點壓力。
• 資料格式：CSV 檔案需包含唯一鍵欄位且無重複，否則查詢結果不確定。
• 更新策略：如需動態更新映射，可在 Data Adapter 設定中啟用「定期重讀」或使用 API 手動刷新。
• 錯誤處理：若查無結果，Lookup 會回傳 null，建議在 Pipeline 中加入預設值或異常判斷。