LogAgent
1.1. LogAgent 概述
LogAgent 是用于将 后端数据实时 导入到神策分析的工具,一般运行在生产日志的服务器上。
几个应用场景举例:
- 我的程序不方便嵌入神策分析的 SDK,但又想将程序输出的数据导入神策分析;
- 我希望在本地生成神策分析的导入数据,并在本地保留完整的副本;
- 我不想自己控制数据发送进度,但又希望发送的数据不重不漏;
这时就可以考虑使用 LogAgent 来进行数据导入。
LogAgent 所做的事情非常简单,即按指定规则 tail 目录下的文件:
- 若发现新数据,将数据简单格式校验并打包发送到神策分析;
- 若无新数据,等待一段时间再查看是否有新数据;
LogAgent 启动时,会向神策分析询问本地目录文件的发送进度,以实现断点续传。
1.2. 下载 LogAgent
当前最新版本:20191227
LogAgent 部署包: http://download.sensorsdata.cn/release/logagent/logagent_20191227.tgz
1.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
2. 检查运行环境(至少 Java 8 以上):
bin/check-java
如果提示 Can't find java ,请指定 JAVA_HOME 环境变量 或 直接用附带的脚本(仅适用于 Linux 环境)安装绿色 JRE 环境(自动解压到 LogAgent 所在目录,不影响系统下其他 Java 环境):
bin/install-jre
3. 编辑配置文件:
可参考 LogAgent 场景使用示例 和 logagent.conf 中对每个配置项的说明;
4. 检查配置文件:
bin/logagent --show_conf
输出类似如下的信息:
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
5. 启动 LogAgent:
可以通过执行以下命令在后端执行 LogAgent:
nohup bin/logagent >/dev/null 2>&1 &
出现步骤 4 中的 pid 文件(步骤 4 输出样例最后一行 Pid file)则说明加载配置启动成功;
若未成功启动,可以查看 log 目录下的日志排查问题,或者直接在前端启动 LogAgent 观察是否有错误输出:
bin/logagent
6. 一台机器启动多个 LogAgent:
一个 LogAgent 程序目录仅能启动一个 LogAgent 进程实例;若需要启动多个 LogAgent,请将 LogAgent 部署到不同目录分别启动即可。
7. 监控 LogAgent:
LogAgent 启动后会在程序目录下生成一个 logagent.pid 文件,记录了进程的 pid 号,如果 LogAgent 需要常驻,建议自行对该进程做监控。
8. 关闭 LogAgent:
在 LogAgent 目录下执行以下命令,即 kill 进程即可:
kill $(cat logagent.pid)
1.4. 常见问题
1.4.1. 文件读取顺序
LogAgent 读取的文件列表由 path 目录下:pattern 所匹配的文件 和 real_time_file_name 指定的文件(若有配置)组成。其他文件将被忽略,这意味着 real_time_file_name (即实时文件)改名后需要符合 pattern 的匹配规则;
LogAgent 会对指定目录下所有规则匹配 pattern 的文件 按字典序排序,依次读取;
real_time_file_name(若有配置)总是被放在文件列表的最后,即认为其是最新的文件;
1.4.2. 读取文件流程
假设目录 path 下有如下文件:
service.log.20160817
service.log.20160818
service.log.20160819
- 当一个文件例如 service.log.20160818 读取到末尾时,刷新目录文件列表,若当前正在读取的文件 service.log.20160818 不是文件列表中最后一个文件,即认为有下一个时间点的文件如 service.log.20160819,那么标记当前文件 service.log.20160818 已经结束(即该文件不再继续写入)。
- 再次读取当前文件,若仍然没有读到数据,关闭当前文件 service.log.20160818,并开始从头读取下一个时间点的文件 service.log.20160819。
- 注意:当切换到读取 service.log.20160819 后,任何 字典序 位于 service.log.20160819 之前的数据都不会再被读取。
1.4.3. 不发送数据排查
导致数据不能正常读取发送可能有多种原因,请按如下步骤检查:
- LogAgent 目录下的 log 目录中的 logagent.log 是否有报错信息。错误可能是数据格式问题、网络问题等。其中有问题的数据会被 LogAgent 过滤而不会被导入,并记录在 log 目录下的 invalid_records 文件里;
- 期望被读取的文件是否匹配配置中的 pattern 。不符合 pattern 的文件不会被 LogAgent 扫描;
期望读取的文件在文件列表中是否位于当前进度之前。例如当前目录下有下列文件:
data.2016090120 data.2016090121
CODE假设当前 LogAgent 正在读取 data.2016090121。
- 新增一个文件 data.20160901,不会被读取,因为按字典序排序目录下的文件,data.20160901 在 data.2016090121 之前;
- 在 data.2016090120 后面追加写入,不会被读取,因为 LogAgent 不会读取当前读取文件 data.2016090121 之前文件的数据。
- 删除或截断(truncate)正在读取的文件。不应当删除或截断 LogAgent 正在读取的文件(4.3 节可以看到当前在读取哪个文件)!因为 LogAgent 进度是 当前读取到哪个文件以及文件内读到的位置 ,一旦这个文件被删除,LogAgent 不知道应该读哪个文件或从文件哪个位置开始读取。此时可参考 LogAgent 日志中的处理方法,老版本处理步骤如下:
- 停止 LogAgent;
- 将数据目录 path 下已经读取过的文件移到其他目录;
- 修改配置文件,使用新的 logagent_id;
- 删除 logagent.pid.context 文件;
启动 LogAgent;
上面 步骤 c 将使新启动的 LogAgent 使用新的进度,即从头读取发送所有文件,而 步骤 b 是避免从头发送导致数据发送重复。
- 发送的数据文件用 “记事本” 等工具编辑后无法发送数据。“记事本” 等文本编辑工具在 “保存” 时可能是通过删除旧文件或截断文件后重新写入的方式来完成,这时会导致 4.删除或截断(truncate)正在读取的文件 提到的问题。
- 是否有多台机器使用了相同 LogAgent ID,问题一般表现为埋点管理里 LogAgent 的 已接收 > 已校验。LogAgent ID 用于服务端数据去重,若配置文件里没有指定 LogAgent ID,默认以 fqdn 作为 LogAgent ID,这时请检查 fqdn 是否相同。
- LogAgent 日志没有明显错误信息,服务端查不到相关数据。LogAgent 只校验数据是否符合基本的数据格式,其他更详细的校验例如数据字段类型会在服务端模块内校验,请查看导入项目的 埋点管理 查看是否有报错信息。
1.4.4. 查看 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).
样例中值的解释:
- 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:第一个值是读取到文件中的位置,第二个值是正在读取的文件总大小。
1.4.5. 在 Windows 下使用 LogAgent
Windows 下不支持 real_time_file_name 参数,即无法跟踪实时文件改名;
需要 Java 8 运行环境;
如果打开配置文件只有一行,可以用尝试用 “写字板”(非记事本)或 notepad++ 等编辑器打开;
Windows 下配置 path 请注意转义的问题,例如 path 是:
D:\data\logs
则需要在配置文件中设置:
path=D:\\data\\logs
其他使用方式同本文档描述,先填写配置文件,再运行 bin/logagent.bat 启动 LogAgent。
1.4.6. 升级 LogAgent
操作步骤如下:
- 关闭正在运行的 LogAgent,可以通过 kill 进程使 LogAgent 退出;
- 下载新版本 LogAgent 部署包 并解压;
- 替换之前 LogAgent 部署目录下的 bin 目录 和 lib 目录;
- 使用之前相同的参数和配置文件启动 LogAgent;
另外:
若是从 20171028 之前版本升级到新版,需要在旧的配置文件中增加(新版配置文件中已包含) pid_file 项:
# pid 文件路径, 若指定则生成 pid 文件, 若运行发现 pid 文件已经存在, 则 LogAgent 启动失败 pid_file=logagent.pid
CODE
1.4.7. 断点续传
LogAgent 以 (LogAgent ID, path, pattern) 三元组对应一个数据 读取进度(哪个文件 inode 的哪个位置 offset)。
如果根据 读取进度 找不到续读的点(例如根据 inode 找不到文件,或 offset > 文件长度)将导致 LogAgent 启动失败进程退出。这时可以根据 LogAgent 日志中的提示来清除进度再开始新的导入。
1.5. 使用 LogAgent 校验数据
当需要对数据格式、字段类型等进行校验时,可以使用 LogAgent 的 DebugSender。LogAgent 会按如下流程进行校验数据:
- LogAgent 本地校验数据格式是否合法,如 JSON 格式、必要字段(distinct_id 等)是否存在等。
- 将通过内部校验的数据发送到远端进行数据内容的校验,如字段类型、track_signup 等。
校验失败会将数据和错误原因打印到日志里,若配置文件设置了 debug_exit_with_bad_record=true,则 LogAgent 会中止,不再处理后面的数据;
校验通过的数据可以直接导入神策分析,或通过配置项 debug_not_import=true 设置为不导入这些数据。
- 启动 LogAgent 校验数据,校验通过的数据导入系统,校验失败的输出错误日志:
sender=DebugSender
- 启动 LogAgent 校验数据,校验通过的数据 不导入系统,当遇到错误数据 LogAgent 退出:
sender=DebugSender
debug_exit_with_bad_record=true
debug_not_import=true
参数解释:
- debug_exit_with_bad_record:当添加该参数时,如遇到一条有问题的数据,LogAgent 会输出错误数据和原因,并退出。
- debug_not_import:当添加该参数时,校验通过的数据不会写入神策分析系统。
注意:校验数据一般用于少量数据检验格式、字段类型是否正确,不适用于大数据量的生产环境。
1.6. 注意事项
- 当数据地址为负载均衡的时候,请保证 LogAgent 的请求能一直落在某台数据接收机上不要随意更改。
- 当服务端存在数据延迟的时候不要随意更改数据接收地址,其他细节请联系神策技术支持。
1.7. 更新日志
1.7.1. 20191227
- 修改部分日志文案;
- 修复当 jre 版本大于 10 的时候启动失败的问题。
- 修复 window 环境下启动脚本找不到主类的问题。
- 修复 20191021 版本在生成额外日志文件可能导致进程僵死的问题。
1.7.2. 20191021
- 移除了通过启动参数指定 Sender 的功能;
- 可通过启动参数手工指定起始文件和 offset;
- 在出错时可额外生成日志文件保存最近的日志与错误原因;
- 修复 cookie 反序列化异常的问题。
1.7.3. 20190605
- Windows 下运行支持过滤 BOM;
- 支持 item 相关操作;
1.7.4. 20180125
可通过环境变量指定 LogAgent 调试日志输出路径:
SA_LOG_AGENT_LOG_PATH=/tmp/logagent.log bin/logagent 或 export SA_LOG_AGENT_LOG_PATH=/tmp/logagent.log bin/logagent
CODE- 更新 file-list-tool 脚本,详见 LogAgent 场景使用示例;
1.7.5. 20180108
- 修复 LogAgent 在 Windows 下使用时读取已加锁的文件导致的异常退出;
1.7.6. 20171030
- LogAgent 启动时若读到不完整的 context 将忽略文件内容;
1.7.7. 20171028
- 修复当数据目录下文件列表为空时导致的空指针退出的问题,该问题于 20170922 之后版本存在;
- 修复 LogAgent 未成功启动时重写了 context 文件,该问题于 20170922 之后版本存在,context 文件用于排查问题和加速启动;
1.7.8. 20171011
- 修复一个导致意外退出的 bug;
1.7.9. 20170922
- 更详细的错误输出,以及相应的处理方法;
- 新增上下文文件,记录 LogAgent 运行状态,并通过上下文文件避免错误的 LogAgent 启动;
- 定期向服务端上报 LogAgent 状态,方便问题排查;
1.7.10. 20170907
- host 可以配置多个并以 ; 半角分号分隔;
1.7.11. 20170707
- 修复安装 Java 脚本;
- 启动失败时,将异常写入日志便于排查;
1.7.12. 20170511
- 新增对过期数据(根据数据 time 字段)的过滤,默认当前时间 2 年前和 1 小时后的数据将被忽略,并记录到日志目录下;
- 修复内部统计数据占用内存的问题;
1.7.13. 20161122
- 添加对 $is_login_id 的支持,详情请见 标识用户;
- 优化使用参数 --show_progress 时执行流程;
- 获取进度的请求超时改为 10 分钟;
1.7.14. 20161114
- 优化 logagent.bat,Windows 下方便看到错误提示。
1.7.15. 20160927
- 对有实时写入的文件,即配置 real_time_file_name 的场景进行优化。