在使用前，請先閱讀 數據模型 和 數據格式 的介紹。

1. LogAgent 概述

LogAgent 是用於將 後端數據即時 匯入到神策分析的工具，一般執行在產生 log 的伺服器上。

幾個應用場景舉例：

  • 我的程式不方便嵌入神策分析的 SDK，但又想將程式輸出的數據匯入神策分析；
  • 我希望在本地產生神策分析的匯入數據，並在本地保留完整的副本；
  • 我不想自己控制數據傳送進度，但又希望傳送的數據不重複不遺漏；

這時就可以考慮使用 LogAgent 來進行數據匯入。

LogAgent 所做的事情非常簡單，即按指定規則 tail 目錄下的檔案：

  • 若發現新數據，將數據簡單格式校驗並打包傳送到神策分析；
  • 若無新數據，等待一段時間再查看是否有新數據；

LogAgent 啟動時，會向神策分析詢問本地目錄檔案的傳送進度，以實現斷點續傳。

2. 下載 LogAgent

目前最新版本：20191227

LogAgent 部署包: http://download.sensorsdata.cn/release/logagent/logagent_20191227.tgz

3. 部署 LogAgent

Logagent 即支援在 Linux 環境下部署，也支援在 windows 環境下部署，windows 環境下部署時，需要注意檔案編碼問題，詳細注意事項參考本文的 4.5 節。

下面以 Linux 環境為例說明 LogAgent 的部署方法。

1. 下載 LogAgent 部署包和解壓縮：

wget http://download.sensorsdata.cn/release/logagent/logagent_20191227.tgz
tar zxvf logagent_20191227.tgz
cd logagent
CODE

2. 檢查執行環境（至少 Java 8 以上）：

bin/check-java
CODE

如果提示 Can't find java ，請指定 JAVA_HOME 環境變數 或 直接用附帶的腳本（僅適用於 Linux 環境）安裝綠色 JRE 環境（自動解壓縮到 LogAgent 所在目錄，不影響系統下其他 Java 環境）：

bin/install-jre
CODE

3. 編輯設定檔案：

可參考 LogAgent 場景使用範例 和 logagent.conf 中對每個設定項的說明；

4. 檢查設定檔案：

bin/logagent --show_conf
CODE

輸出類似如下的資訊：

17/09/22 15:16:27 INFO logagent.LogAgentMain: LogAgent version: SensorsAnalytics LogAgent_20170922
17/09/22 15:16:27 INFO logagent.LogAgentMain: Use FQDN as LogAgentID
17/09/22 15:16:27 INFO logagent.LogAgentMain: LogAgent ID: test01.sa
17/09/22 15:16:27 INFO logagent.LogAgentMain: Source config, path: '/home/work/data', pattern: 'service_log.*'
17/09/22 15:16:27 INFO logagent.LogAgentMain: Service Uri: http://10.10.90.131:8106/log_agent
17/09/22 15:16:27 INFO logagent.LogAgentMain: Sender Type: BatchSender
17/09/22 15:16:27 INFO logagent.LogAgentMain: Pid file: /home/work/logagent/logagent.pid
CODE

若有多台電腦部署 LogAgent，需要確保在不同電腦上 LogAgent ID 取值不同（上面範例中是 test01.sa），伺服器記錄各電腦的進度，以 LogAgent ID 區分不同電腦；

5. 啟動 LogAgent：
可以透過執行以下指令在後端執行 LogAgent：

nohup bin/logagent >/dev/null 2>&1 &
CODE

出現步驟 4 中的 pid 檔案（步驟 4 輸出範例最後一行 Pid file）則說明加載設定啟動成功；
若未成功啟動，可以查看 log 目錄下的記錄檔排查問題，或者直接在前端啟動 LogAgent 觀察是否有錯誤輸出：

bin/logagent
CODE

6. 一台電腦啟動多個 LogAgent：
一個 LogAgent 程式目錄僅能啟動一個 LogAgent 程序實例；若需要啟動多個 LogAgent，請將 LogAgent 部署到不同目錄分別啟動即可。

7. 監控 LogAgent：
LogAgent 啟動後會在程式目錄下產生一個 logagent.pid 檔案，記錄了​​程序的 pid 號，如果 LogAgent 需要常駐，建議自行對該程序做監控。

8. 關閉 LogAgent：
在 LogAgent 目錄下執行以下指令，即 kill 程序即可：

kill $(cat logagent.pid)
CODE

4. 常見問題

4.1. 檔案讀取順序

LogAgent 讀取的檔案列表由 path 目錄下：pattern 所匹配的檔案 和 real_time_file_name 指定的檔案（若有設定）組成。其他檔案將被忽略，這意味著 real_time_file_name （即時檔案）改名後需要符合 pattern 的匹配規則;

LogAgent 會對指定目錄下所有規則匹配 pattern 的檔案 按英文字母大小寫排序，依次讀取;

real_time_file_name（若有設定）總是被放在檔案列表的最後，即認為其是最新的檔案;

4.2. 讀取檔案流程

假設目錄 path 下有如下檔案：

service.log.20160817
service.log.20160818
service.log.20160819
CODE
  1. 當一個檔案例如service.log.20160818 讀取到末尾時，更新目錄檔案列表，若目前正在讀取的檔案service.log.20160818 不是檔案列表中最後一個檔案，即認為有下一個時間點的檔案如service.log.20160819，那麼標記目前檔案service.log.20160818 已經結束（即該檔案不再繼續寫入）。
  2. 再次讀取目前檔案，若仍然沒有讀到數據，關閉目前檔案 service.log.20160818，並開始從頭讀取下一個時間點的檔案 service.log.20160819。
  • 注意：當切換到讀取 service.log.20160819 後，任何 英文字母大小寫排序 位於 service.log.20160819 之前的數據都不會再被讀取。

4.3. 不傳送數據排查

導致數據不能正常讀取傳送可能有多種原因，請按如下步驟檢查：

  1. LogAgent 目錄下的 log 目錄中的 logagent.log 是否有報錯資訊。錯誤可能是數據格式問題、網路問題等。其中有問題的數據會被 LogAgent 過濾而不會被匯入，並記錄在 log 目錄下的 invalid_records 檔案裡；
  2. 期望被讀取的檔案是否匹配設定中的 pattern 。不符合 pattern 的檔案不會被 LogAgent 掃描；

  3. 期望讀取的檔案在檔案列表中是否位於目前進度之前。例如目前目錄下有下列檔案：

    data.2016090120
data.2016090121
    CODE

    假設目前 LogAgent 正在讀取 data.2016090121。

    1. 新增一個檔案 data.20160901，不會被讀取，因為按英文字母大小寫排序目錄下的檔案，data.20160901 在 data.2016090121 之前；
    2. 在 data.2016090120 後面追加寫入，不會被讀取，因為 LogAgent 不會讀取目前讀取檔案 data.2016090121 之前檔案的數據。
  4. 刪除或截斷（truncate）正在讀取的檔案。不應當刪除或截斷 LogAgent 正在讀取的檔案（4.3 節可以看到目前在讀取哪個檔案）！因為 LogAgent 進度是 目前讀取到哪個檔案以及檔案內讀到的位置，一旦這個檔案被刪除，LogAgent 不知道應該讀哪個檔案或從檔案哪個位置開始讀取。此時可參考 LogAgent 記錄檔中的處理方法，舊版本處理步驟如下：
    1. 停止 LogAgent；
    2. 將數據目錄 path 下已經讀取過的檔案移到其他目錄；
    3. 修改設定檔案，使用新的 logagent_id；
    4. 刪除 logagent.pid.context 檔案；

    5. 啟動 LogAgent；

      上面 步驟 c 將使新啟動的 LogAgent 使用新的進度，即從頭讀取傳送所有檔案，而 步驟 b 是避免從頭傳送導致數據傳送重複。

  5. 傳送的數據檔案用 “記事本” 等工具編輯後無法傳送數據。 “記事本” 等文字編輯工具在“儲存” 時可能是透過刪除舊檔案或截斷檔案後重新寫入的方式來完成，這時會導致4.刪除或截斷（truncate）正在讀取的檔案 提到的問題。
  6. 是否有多台電腦使用了相同 LogAgent ID，問題一般表現為埋點管理裡 LogAgent 的 已接收 > 已校驗。 LogAgent ID 用於伺服器端數據去重，若設定檔案裡沒有指定 LogAgent ID，預設以 fqdn 作為 LogAgent ID，這時請檢查 fqdn 是否相同。
  7. LogAgent 記錄檔沒有明顯錯誤資訊，伺服器端查不到相關數據。 LogAgent 只校驗數據是否符合基本的數據格式，其他更詳細的校驗例如數據欄位型別會在伺服器端模組內校驗，請查看匯入專案的 埋點管理 查看是否有報錯資訊。

4.4. 查看 LogAgent 執行狀態

LogAgent 每間隔 10 秒會輸出如下格式 log檔：

LogAgent send speed: 1.200 records/sec, reading file: /home/work/app/logs/service.log.2016-08-17 (key: (dev=fc01,ino=1197810), offset: 122071 / 145071).
CODE

範例中值的解釋：

  • send speed: 1.200 records/sec：根據之前 10 秒處理情況計算的速度平均值；
  • reading file: /home/work/app/logs/service.log.2016-08-17：正在讀取的檔案路徑；
  • key: (dev=fc01,ino=1197810)：檔案所在磁碟以及 inode；
  • offset: 122071 / 145071：第一個值是讀取到檔案中的位置，第二個值是正在讀取的檔案總大小。

4.5. 在 Windows 下使用 LogAgent

Windows 下不支援 real_time_file_name 參數，即無法跟蹤即時檔案改名；

需要 Java 8 執行環境；

如果打開設定檔案只有一行，可以用嘗試用 “wordpad”（非記事本）或 notepad++ 等編輯器打開；

Windows 下設定 path 請注意轉義的問題，例如 path 是：

D:\data\logs
CODE

則需要在設定檔案中設定：

path=D:\\data\\logs
CODE

其他使用方式同本文件描述，先填寫設定檔案，再執行 bin/logagent.bat 啟動 LogAgent。

4.6. 升級 LogAgent

操作步骤如下：

  1. 關閉正在執行的 LogAgent，可以透過 kill 程序使 LogAgent 退出；
  2. 下載新版本 LogAgent 部署包 並解壓縮；
  3. 替換之前 LogAgent 部署目錄下的 bin 目錄 和 lib 目錄；
  4. 使用之前相同的參數和設定檔案啟動 LogAgent；

另外：

  • 若是從 20171028 之前版本升級到新版，需要在舊的設定檔案中增加（新版設定檔案中已包含） pid_file 項：

    # pid 檔案路徑, 若指定則產生 pid 檔案, 若執行發現 pid 檔案已經存在, 則 LogAgent 啟動失敗
pid_file=logagent.pid
    CODE

4.7. 斷點續傳

LogAgent 以 (LogAgent ID, path, pattern) 三元組對應一個數據 讀取進度（哪個檔案 inode 的哪個位置 offset）。

如果根據 讀取進度 找不到續讀的點（例如根據 inode 找不到檔案，或 offset > 檔案長度）將導致 LogAgent 啟動失敗程序退出。這時可以根據 LogAgent 記錄檔中的提示來清除進度再開始新的匯入。

5. 使用 LogAgent 校驗數據

當需要對數據格式、欄位型別等進行校驗時，可以使用 LogAgent 的 DebugSender。 LogAgent 會按如下流程進行校驗數據：

  1. LogAgent 本地校驗數據格式是否合法，如 JSON 格式、必要欄位（distinct_id 等）是否存在等。

  2. 將透過內部校驗的數據傳送到遠端進行數據內容的校驗，如欄位型別、track_signup 等。

校驗失敗會將數據和錯誤原因輸出到log檔裡，若設定檔案設定了 debug_exit_with_bad_record=true，則 LogAgent 會中止，不再處理後面的數據；
校驗通過的數據可以直接匯入神策分析，或透過設定項 debug_not_import=true 設定為不匯入這些數據。


  • 啟動 LogAgent 校驗數據，校驗通過的數據匯入系統，校驗失敗的輸出錯誤 log：
sender=DebugSender
CODE
  • 啟動 LogAgent 校驗數據，校驗通過的數據 不匯入系統，當遇到錯誤數據 LogAgent 退出：
sender=DebugSender
debug_exit_with_bad_record=true
debug_not_import=true
CODE


參數解釋：

  • debug_exit_with_bad_record：當增加該參數時，如遇到一條有問題的數據，LogAgent 會輸出錯誤數據和原因，並退出。
  • debug_not_import：當增加該參數時，校驗通過的數據不會寫入神策分析系統。

注意：校驗數據一般用於少量數據檢驗格式、欄位型別是否正確，不適用於大數據量的生產環境。

6. 注意事項

  1. 當數據網址為負載均衡的時候，請確保 LogAgent 的請求能一直落在某台數據接收機上不要隨意更改。
  2. 當伺服器端存在數據延遲的時候不要隨意更改數據接收網址，其他細節請聯繫神策技術支援。

7. 更新日誌

7.1. 20191227

  1. 修改部分日誌文案；
  2. 修復當 jre 版本大於 10 的時候啟動失敗的問題。
  3. 修復 window 環境下啟動腳本找不到主要類別的問題。
  4. 修復 20191021 版本在產生額外記錄檔案可能導致程式死當的問題。

7.2. 20191021

  1. 移除了透過啟動參數指定 Sender 的功能；
  2. 可透過啟動參數手工指定起始檔案和 offset；
  3. 在出錯時可額外產生log檔保存最近的log與錯誤原因；
  4. 修復 cookie 反序列化異常的問題。

7.3. 20190605

  1. Windows 下執行支援過濾 BOM；
  2. 支援 item 相關操作；

7.4. 20180125

  1. 可透過環境變數指定 LogAgent 除錯log檔輸出路徑：：

    SA_LOG_AGENT_LOG_PATH=/tmp/logagent.log bin/logagent
或
export SA_LOG_AGENT_LOG_PATH=/tmp/logagent.log
bin/logagent
    CODE
  2. 更新 file-list-tool 腳本，詳見 LogAgent 場景使用範例；

7.5. 20180108

  1. 修復 LogAgent 在 Windows 下使用時讀取已加密的檔案導致的異常退出；

7.6. 20171030

  1. LogAgent 啟動時若讀到不完整的 context 將忽略檔案內容；

7.7. 20171028

  1. 修復當數據目錄下檔案列表為空時導致的空指針退出的問題，該問題於 20170922 之後版本存在；
  2. 修復 LogAgent 未成功啟動時重寫了 context 檔案，該問題於 20170922 之後版本存在，context 檔案用於排查問題和加速啟動；

7.8. 20171011

  1. 修復一個導致意外退出的 bug；

7.9. 20170922

  1. 更詳細的錯誤輸出，以及相應的處理方法；
  2. 新增上下文檔案，記錄 LogAgent 執行狀態，並透過上下文檔案避免錯誤的 LogAgent 啟動；
  3. 定期向伺服器端上報 LogAgent 狀態，方便問題排查；

7.10. 20170907

  1. host 可以設定多個並以 ; 半形分號分隔；

7.11. 20170707

  1. 修復安裝 Java 腳本;
  2. 啟動失敗時，將異常寫入 log 便於排查;

7.12. 20170511

  1. 新增對過期數據（根據數據 time 欄位）的過濾，預設目前時間 2 年前和 1 小時後的數據將被忽略，並記錄到 log 目錄下;
  2. 修復內部統計數據佔用記憶體的問題;

7.13. 20161122

  1. 增加對 $is_login_id 的支援，詳情請見 標識用戶;
  2. 優化使用參數 --show_progress 時執行流程;
  3. 取得進度的請求超時改為 10 分鐘;

7.14. 20161114

  1. 優化 logagent.bat，Windows 下方便看到錯誤提示。

7.15. 20160927

  1. 對有即時寫入的檔案，即設定 real_time_file_name 的場景進行優化。