在使用前,请先阅读 数据模型 和 数据格式 的介绍。



 1. 概述

LogAgent 一般用于将 后端数据实时 导入到神策分析的工具,一般运行在生产日志的服务器上。

几个应用场景举例:

  • 我的程序不方便嵌入神策分析的 SDK,但又想将程序输出的数据导入神策分析;
  • 我希望在本地生成神策分析的导入数据,并在本地保留完整的副本;
  • 我不想自己控制数据发送进度,但又希望发送的数据不重不漏;

这时就可以考虑使用 LogAgent 来进行数据导入。

LogAgent 所做的事情非常简单,即按指定规则 tail 目录下的文件:

  • 若发现新数据,将数据简单格式校验并打包发送到神策分析;
  • 若无新数据,等待一段时间再查看是否有新数据;

LogAgent 启动时,会向神策分析询问本地目录文件的发送进度,以实现断点续传。

2. 使用方法

2.1 运行环境

Logagent 既支持在 Linux 环境下部署,也支持在 windows 环境下部署,windows 环境下部署时,需要注意文件编码问题,具体注意事项参考本文的 3.6 节。

2.2 使用方法

下面以 Linux 环境为例说明 LogAgent 的使用方法步骤。

1. 下载 LogAgent 部署包和解压:

wget LogAgent网络包链接(具体地址见上面链接)
tar xvf log_agent-XXXX.tar
cd log_agent
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 ,可参考 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,需要确保在不同机器上 LogAgent ID 取值不同(上面示例中是 test01.sa),服务端记录各机器的进度,以 LogAgent ID 区分不同机器;


5. 启动 LogAgent:
可以通过执行以下命令在后端执行 LogAgent:

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

新版本下,可直接使用

bin/start
CODE


6. 关闭 LogAgent:
在 LogAgent 目录下执行以下命令,即 kill 进程即可:

kill $(cat logagent.pid)
CODE

出现步骤 4 中的 pid 文件(步骤 4 输出样例最后一行 Pid file)则说明加载配置启动成功;
若未成功启动,可以查看 log 目录下的日志排查问题,或者直接在前端启动 LogAgent 观察是否有错误输出:

bin/logagent
CODE

新版本的 LogAgent,可直接使用

bin/stop
CODE


7. 一台机器启动多个 LogAgent:
一个 LogAgent 程序目录仅能启动一个 LogAgent 进程实例;若需要启动多个 LogAgent,请将 LogAgent 部署到不同目录分别启动即可。


8. 使用 LogAgent 校验数据:

当需要对数据格式、字段类型等进行校验时,可以使用 LogAgent 的 DebugSender。LogAgent 会按如下流程进行校验数据:

  1. LogAgent 本地校验数据格式是否合法,如 JSON 格式、必要字段(distinct_id 等)是否存在等。
  2. 将通过内部校验的数据发送到远端进行数据内容的校验,如字段类型、track_signup 等。

校验失败会将数据和错误原因打印到日志里,若配置文件设置了 debug_exit_with_bad_record=true,则 LogAgent 会中止,不再处理后面的数据;
校验通过的数据可以直接导入神策分析,或通过配置项 debug_not_import=true 设置为不导入这些数据。

  • 启动 LogAgent 校验数据,校验通过的数据导入系统,校验失败的输出错误日志:
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:当添加该参数时,校验通过的数据不会写入神策分析系统。

注意:校验数据一般用于少量数据检验格式、字段类型是否正确,不适用于大数据量的生产环境。

2.3 注意事项

  1. 当数据地址为负载均衡的时候,请保证 LogAgent 的请求能一直落在某台数据接收机上不要随意更改。
  2. 当服务端存在数据延迟的时候不要随意更改数据接收地址,其他细节请联系神策技术支持。

3. 常见问题

3.1 文件读取顺序

LogAgent 读取的文件列表由 path 目录下:pattern 所匹配的文件 和 real_time_file_name 指定的文件(若有配置)组成。其他文件将被忽略,这意味着 real_time_file_name (即实时文件)改名后需要符合 pattern 的匹配规则;

LogAgent 会对指定目录下所有规则匹配 pattern 的文件 按字典序排序,依次读取;

real_time_file_name(若有配置)总是被放在文件列表的最后,即认为其是最新的文件;

3.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 之前的数据都不会再被读取。

3.3获取读取进度

可借助 file-list-tool ,获取当前读取的进度、已读文件列表、未读文件列表

功能脚本路径执行语句
获取进度

bin/file-list-tool

bin/file-list-tool --context_file ./logagent.pid.context 
//context_file 为进度文件 logagent.pid.context 的路径,如果 loagegnt 已经出现进度错误,需要再加 --not start 参数
CODE
获取已读文件列表bin/file-list-tool
bin/file-list-tool --context_file ./logagent.pid.context 
--show_read_files_list
//context_file 为进度文件 logagent.pid.context 的路径 ,如果 loagegnt 已经出现进度错误,需要再加 --not start 参数
CODE
获取未读文件列表bin/file-list-tool
bin/file-list-tool --context_file ./logagent.pid.context 
--show_unread_files_list
//context_file 为进度文件 logagent.pid.context 的路径 ,如果 loagegnt 已经出现进度错误,需要再加 --not start 参数
CODE

 

3.4不发送数据排查

导致数据不能正常读取发送可能有多种原因,请按如下步骤检查:

1.LogAgent 目录下的 log 目录中的 logagent.log 是否有报错信息。错误可能是数据格式问题、网络问题等。其中有问题的数据会被 LogAgent 过滤而不会被导入,并记录在 log 目录下的 invalid_records 文件里;

2.期望被读取的文件是否匹配配置中的 pattern 。不符合 pattern 的文件不会被 LogAgent 扫描;

3.期望读取的文件在文件列表中是否位于当前进度之前。例如当前目录下有下列文件:

data.2016090120
data.2016090121
CODE

a.假设当前 LogAgent 正在读取 data.2016090121。

b.新增一个文件 data.20160901,不会被读取,因为按字典序排序目录下的文件,data.20160901 在 data.2016090121 之前;

c.在 data.2016090120 后面追加写入,不会被读取,因为 LogAgent 不会读取当前读取文件 data.2016090121 之前文件的数据。

4.是否有多台机器使用了相同 LogAgent ID,问题一般表现为埋点管理里 LogAgent 的 已接收 > 已校验。LogAgent ID 用于服务端数据去重,若配置文件里没有指定 LogAgent ID,默认以 fqdn 作为 LogAgent ID,这时请检查 fqdn 是否相同。

5.删除或截断(truncate)正在读取的文件。不应当删除或截断 LogAgent 正在读取的文件(4.3 节可以看到当前在读取哪个文件)!因为 LogAgent 进度是 当前读取到哪个文件以及文件内读到的位置 ,一旦这个文件被删除,LogAgent 不知道应该读哪个文件或从文件哪个位置开始读取。此时可参考 LogAgent 日志中的处理方法,

老版本处理步骤如下:

a.停止 LogAgent;

b.将数据目录 path 下已经读取过的文件移到其他目录;

c.修改配置文件,使用新的 logagent_id;

d.删除 logagent.pid.context 文件;

e.启动 LogAgent;

上面 步骤 c 将使新启动的 LogAgent 使用新的进度,即从头读取发送所有文件,而 步骤 b 是避免从头发送导致数据发送重复

新版本可直接用命令一键异常处理:

bin/abnormal-reset   --context_file ./logagent.pid.context  
//在新版本的 log_agent 目录下执行以上命令
CODE

             重置之后可使用 bin/start 重新启动,继续运行!

6.发送的数据文件用 “记事本” 等工具编辑后无法发送数据。“记事本” 等文本编辑工具在 “保存” 时可能是通过删除旧文件或截断文件后重新写入的方式来完成,这时会导致 4.删除或截断(truncate)正在读取的文件 提到的问题。

7.LogAgent 日志没有明显错误信息,服务端查不到相关数据。LogAgent 只校验数据是否符合基本的数据格式,其他更详细的校验例如数据字段类型会在服务端模块内校验,请查看导入项目的 埋点管理 查看是否有报错信息。

3.5 查看 LogAgent 运行状态

LogAgent 每间隔 10 秒会输出如下格式日志:

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:第一个值是读取到文件中的位置,第二个值是正在读取的文件总大小。

3.6 在 Windows 下使用 LogAgent

Windows 下不支持 real_time_file_name 参数,即无法跟踪实时文件改名;

需要 Java 8 运行环境;

如果打开配置文件只有一行,可以用尝试用 “写字板”(非记事本)或 notepad++ 等编辑器打开;

Windows 下配置 path 请注意转义的问题,例如 path 是:

D:\data\logs
CODE

则需要在配置文件中设置:

path=D:\\data\\logs
CODE

其他使用方式同本文档描述,先填写配置文件,再运行 bin/logagent.bat 启动 LogAgent。

3.7 升级 LogAgent

操作步骤如下:

  1. 关闭正在运行的 LogAgent,可以通过 kill 进程使 LogAgent 退出;
  2. 下载新版本并解压;
  3. 替换之前 LogAgent 部署目录下的 bin 目录 和 lib 目录
  4. 使用之前相同的参数和配置文件启动 LogAgent;

另外:

  • 若是从 20171028 之前版本升级到新版,需要在旧的配置文件中增加(新版配置文件中已包含) pid_file 项:

    # pid 文件路径, 若指定则生成 pid 文件, 若运行发现 pid 文件已经存在, 则 LogAgent 启动失败
    pid_file=logagent.pid
    CODE

3.8 断点续传

LogAgent 以 (LogAgent ID, path, pattern) 三元组对应一个数据 读取进度(哪个文件 inode 的哪个位置 offset)。

如果根据 读取进度 找不到续读的点(例如根据 inode 找不到文件,或 offset > 文件长度)将导致 LogAgent 启动失败进程退出。这时可以根据 LogAgent 日志中的提示来清除进度再开始新的导入。


3.9 日志清理

生产日志清理:可在 logagent.conf 里进行配置 operate_read_files_type(处理类型)、operate_read_files_before_days(处理规则)、operate_read_files_cron(处理频率) 等参数。

建议选择压缩。谨慎设置日志定期删除,如果因为配置参数有误导致日志被清理,需要您自负责任。

运行日志清理:运行日志在 logagent 的 log 文件夹下,占用存储比较小。也可考虑删除。

删除方法:

1.找到 logagent 目录下的 bin/logagent 文件,用文件编辑器打开

2.修改 SA_LOG_MAX_BACKUP_INDEX 参数,默认 60 天清理一次,可按需修改。