1. 產生數據

1.1.  使用神策分析 SDK 產生數據檔案

神策分析各後端語言的 SDK 都支援將數據寫入檔案，例如使用 Java SDK 的 ConcurrentLoggingConsumer，PHP SDK 的 FileConsumer，Python SDK 的 LoggingConsumer。下面以 Java SDK 為例：

// 使用 ConcurrentLoggingConsumer 初始化 SensorsAnalytics
// 將數據輸出到 /data/sa 下的 service_log.2017-09-25 檔案中，每天一個檔案
final SensorsAnalytics sa = new SensorsAnalytics(
        new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa/service_log")); 

// 使用神策分析記錄用戶行為數據
sa.track(distinctId, true, "UserLogin");
sa.track(distinctId, true, "ViewProduct");

// 程式結束前，停止神策分析 SDK 所有服務
sa.shutdown();
JAVA

以上設定將在 /data/sa 目錄下產生數據檔案，一天一個檔案，檔案列表如：

service_log.20170923
service_log.20170924
service_log.20170925
CODE

對應 LogAgent 中的設定：

path=/data/sa
pattern=service_log.*
CODE

1.2. 使用其他方式輸出數據檔案

若所使用的程式語言有對應的 SDK，建議直接使用 SDK 來輸出數據檔案；若需要自己寫數據檔案，有幾點需要注意：

  1. （非常重要）檔案只能追加寫入，即打開檔案時以 Open Append 方式打開；
  2. 檔案內容需要是 一條數據一行，並且是符合 數據格式 的完整 JSON；

  3. 數據檔案名 必須 包含日期，還可以包含更詳細的時間，例如將數據寫到 service_log.20170925 或 service_log.2017092517，檔案目錄下檔案應該類似如下：

    service_log.20170923
service_log.20170924
service_log.20170925
    CODE

    對應 LogAgent 中的設定：

    path=/data/sa
pattern=service_log.*
    CODE

  4. 若多個程序寫入同一個檔案，需要使用檔案加密避免檔案交叉寫入數據損壞；

2. 設定數據接收服務網址

2.1. 私有部署版設定

LogAgent 將數據發送到的伺服器，至少需要設定接收數據的伺服器網址，對應設定檔案中 host 和 port 兩個參數：

  • host：一個 或 多個以 ; 半形分號分隔的伺服器 IP 網址。例如 192.168.50.10;192.168.50.11;192.168.50.12，LogAgent 啟動時會選定其中一台傳送數據，以均衡負載；
  • port：數據接收伺服器端埠號，預設情況下叢集版是 8106，單機版（1.7 及之前的版本為 8006，1.8 及之後的版本是 8106），雲版不帶埠號；

若部署神策分析同時有外網 IP 和 內網 IP，host 的值應取內網 IP;

2.2. 雲版設定

點擊“複製 https 數據接收網址”，例如復製到的是 https://example.datasink.sensorsdata.cn/sa?project=production&token=c9239cb3139077ca

在設定檔案中，請刪除或註釋掉 host、port 和 token 欄位，啟用 service_uri 欄位，取值是將上面取得到的值中的 /sa 改為 /log_agent，例如對於上面範例，應設定 https://example.datasink.sensorsdata.cn/log_agent?token=c9239cb3139077ca。

  • 指定數據傳往的專案請參考本文件 4.1 節。

2.3. 透過外網使用額外需要注意的設定

LogAgent 是為內網後端即時數據匯入設計開發，若透過公網使用 LogAgent 需要額外注意：

  • 請確保一個 LogAgent 每次請求都落到同一台電腦上。如果使用負載均衡，負載均演算法請選擇 ip_hash 來源網址 方式；如果域名 DNS 直接解析到多台電腦，則不能使用域名，應直接指定一個 IP 或按上面規則拼接多個伺服器的外網 IP；
  • 若公共網路使用 LogAgent 且伺服器已經設定了 HTTPS 數據接入方式，可以按如下步驟設定使用 HTTPS 發送數據：
    1. 註釋掉設定檔案中的 host、port 和 token 欄位，即不使用 host、port 和 token 參數；

    2. 在設定檔案中啟用service_uri 欄位，一個範例值為 https://example.sensorsdata.cn:4006/log_agent，請注意埠號應為 HTTPS 數據接入服務的網址，uri 是 /log_agent，而不是 /sa ;

3. 其他設定說明

3.1. 設定即時寫入檔案的檔案名 real_time_file_name

設定檔案中的 real_time_file_name 即即時寫入檔案的檔案名, 一般用在捲軸記錄檔案的場景。例如按日切分的數據目錄下檔案列表如下：

service_log.20170922
service_log.20170923
service_log
CODE

數據輸出程序只向 service_log 中寫入，當到了新的一天，定時調度程式將 service_log 改名為帶日期的檔案例如 service_log.20170923，數據輸出程序開始寫一個新的 service_log 檔案，在這個場景裡設定應該是:

pattern=service_log.*
real_time_file_name=service_log
CODE

即 pattern 可以匹配所有改名後的數據檔案名，而 real_time_file_name 為即時輸出的數據檔案名稱。

3.2. 以下場景無需設定 real_time_file_name

設定檔案中的 real_time_file_name 優先級高於pattern 參數，如果數據輸出程序直接向 service_log.yyyymmdd / service_log.yyyymmddhh 中寫入數據，且每天自動產生新的檔案，則需要註釋掉此參數，只設定 pattern 參數即可，否則數據可能會無法正常匯入。

以 JAVA SDK 為例，使用 JAVA SDK 的 ConcurrentLoggingConsumer，透過 new SensorsAnalytics.ConcurrentLoggingConsumer(“/data/sa/service_log”))，此設定將在 /data/sa 目錄下每天產生一個帶日期的數據檔案，檔案列表如：

service_log.20170923
service_log.20170924
service_log.20170925
CODE


對應 LogAgent 中的設定：

path=/data/sa
pattern=service_log.*
# real_time_file_name=access_log
CODE

注：目前神策分析所有伺服器端 SDK 的 ConcurrentLoggingConsumer 模式下產生的記錄檔案都是每天產生一個帶日期的數據檔案，對應 LogAgent 的設定均無需設定 real_time_file_name 參數。

4. 其他使用場景說明

4.1. 指定數據匯入專案

指定數據匯入的專案有兩種方法：

  1. 在每條數據中增加 project 欄位（詳見 數據格式），使用這種方式可以每條數據匯入各自的專案；
  2. 在設定檔案中指定 project。每條數據無論是否指定 project 欄位都將匯入到參數設定的專案中。

系統判定一條數據所屬專案的流程為：

  1. 取設定檔案中的 project；
  2. 若上一步沒有取到，取數據中的 project 欄位；
  3. 若上一步沒有取到，（若有設定）取 service_uri 的 project 參數；
  4. 若上一步沒有取到，取預設專案的專案名，即 default。

如果想用一個 LogAgent 匯入多個專案的數據，請不要在設定檔案中設定 project，在數據中增加 project 欄位來設定每條數據所屬專案。

4.2. 使用 file-list-tool 列出檔案讀取情況

LogAgent 提供了 file-list-tool：

$ bin/file-list-tool
usage: [file-checker] --context_file <arg> [-h] [--new_file_format <arg>]
       [--old_file_format <arg>] [--reading_file_format <arg>]
    --context_file <arg>          LogAgent context file path, e.g.
                                  logagent.pid.context
 -h,--help                        help
    --new_file_format <arg>       對每個未讀過的新檔案的輸出格式，指定後會格式化並輸出，檔案名以 {} 代替
    --old_file_format <arg>       對每個舊檔案的輸出格式，指定後會格式化並輸出，檔案名以 {} 代替
    --reading_file_format <arg>   對正在讀取的檔案的輸出格式，指定後會格式化並輸出，檔案名以 {} 代替
BASH

使用 file-list-tool 解析 context 檔案（與 pid 檔案在同一個目錄下）可以列出每個檔案的讀取狀態：

$ bin/file-list-tool --context_file logagent.pid.context
18/01/22 17:35:29 INFO logagent.SourceFileReader: SourceFileReader recover progress:
[ fileKey: (dev=fc10,ino=118226959), offset: 11260636, fileName: test_data.2018012213, count: 161982, sourceCount: 161982 ]
18/01/22 17:35:29 INFO logagent.FileListTool: 進度之前的檔案, path: /data/test/logagent/data/test_data.2018012212, size: 19191980, key: (dev=fc10,ino=118226958)
18/01/22 17:35:29 INFO logagent.FileListTool: 讀取中的檔案, path: /data/test/logagent/data/test_data.2018012213, size: 11260824, key: (dev=fc10,ino=118226959), tell: 11260636
18/01/22 17:35:29 INFO logagent.FileListTool: 進度之後的檔案, path: /data/test/logagent/data/test_data.2018012214, size: 19191980, key: (dev=fc10,ino=118226960)
BASH

“進度之前的檔案” 即已經讀取過的可以安全地從 LogAgent 讀取目錄移走或刪除的檔案。

file-list-tool 還可以以指定格式輸出檔案列表，例如下面的例子產生將已經讀取過的檔案移到指定目錄的指令檔案 mv.sh 並執行：

$ bin/file-list-tool --context_file logagent.pid.context --old_file_format 'mv {} /data/test/logagent/backup' > mv.sh
18/01/22 17:44:29 INFO logagent.SourceFileReader: SourceFileReader recover progress:
[ fileKey: (dev=fc10,ino=118226959), offset: 11260636, fileName: test_data.2018012213, count: 161982, sourceCount: 161982 ]
18/01/22 17:44:29 INFO logagent.FileListTool: 進度之前的檔案, path: /data/test/logagent/data/test_data.2018012212, size: 19191980, key: (dev=fc10,ino=118226958)
18/01/22 17:44:29 INFO logagent.FileListTool: 讀取中的檔案, path: /data/test/logagent/data/test_data.2018012213, size: 11260824, key: (dev=fc10,ino=118226959), tell: 11260636
18/01/22 17:44:29 INFO logagent.FileListTool: 進度之後的檔案, path: /data/test/logagent/data/test_data.2018012214, size: 19191980, key: (dev=fc10,ino=118226960)

$ cat mv.sh
mv /data/test/logagent/data/test_data.2018012212 /data/test/logagent/backup

$ bash mv.sh
BASH

4.3. 使用 --filename --offset 參數指定起始檔案和 offset

版本高於 20191021 的 LogAgent 啟動時可手動指定起始檔案和 offset ：

$ bin/logagent --filename service.log.20191021 --offset 100
BASH

注意：

1. 啟動後會忽略起始值之前所有的記錄檔案；
2. 該設定在與伺服器端正常取得進度之後才會生效。
3. -filename  只需設定檔案名無需包含路徑，檔案必須在設定檔案中指定的路徑 path 下存在且名稱必須符合 pattern 規定的格式。
4. --offset  必須與  --filename  搭配使用，預設值為 0。
5. 如果 -offset 指定的位置分割了一條完整的埋點數據，那麼該數據會被捨棄。