菜单

LogAgent

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

点击此处 下载最新版 LogAgent

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

2. 检查运行环境(至少 Java 8 以上):

bin/check-java

如果提示 Can't find java,请指定 JAVA_HOME 环境变量或直接用附带的脚本(仅适用于 Linux 环境)安装绿色 JRE 环境(自动解压到 LogAgent 所在目录,不影响系统下其他 Java 环境):

bin/install-jre

3. 编辑配置文件:

直接编辑 LogAgent 解压包的 logagent.conf,可参考 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

最新版本的 logagent 的配置文件检查,对于这些信息进行了简化,没注意检查配置时,少输出了日志,后面版本会增加,输出的结果如下

若有多台机器部署 LogAgent,需要确保在不同机器上 LogAgent ID 取值不同(上面示例中是 test01.sa),服务端记录各机器的进度,以 LogAgent ID 区分不同机器。

5. 启动 LogAgent:

可以通过执行以下命令在后端执行 LogAgent:

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

新版本下,可直接使用

bin/start

6. 关闭 LogAgent:

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

kill $(cat logagent.pid)

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

bin/logagent

新版本的 LogAgent,可直接使用

bin/stop

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
  • 启动 LogAgent 校验数据,校验通过的数据 不导入系统,当遇到错误数据 LogAgent 退出:
sender=DebugSender
debug_exit_with_bad_record=true
debug_not_import=true

参数解释:

  • 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
  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 参数
获取已读文件列表 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 参数
获取未读文件列表 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 参数

3.4 不发送数据排查

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

  1. LogAgent 目录下的 log 目录中的 logagent.log 是否有报错信息。错误可能是数据格式问题、网络问题等。其中有问题的数据会被 LogAgent 过滤而不会被导入,并记录在 log 目录下的 invalid_records 文件里。
  2. 期望被读取的文件是否匹配配置中的 pattern。不符合 pattern 的文件不会被 LogAgent 扫描。
  3. 期望读取的文件在文件列表中是否位于当前进度之前。例如当前目录下有下列文件:
    data.2016090120
    data.2016090121
    1. 假设当前 LogAgent 正在读取 data.2016090121。
    2. 新增一个文件 data.20160901,不会被读取,因为按字典序排序目录下的文件,data.20160901 在 data.2016090121 之前。
    3. 在 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 日志中的处理方法。
  6. 老版本处理步骤如下:
    1. 停止 LogAgent。
    2. 将数据目录 path 下已经读取过的文件移到其他目录。
    3. 修改配置文件,使用新的 logagent_id。
    4. 删除 logagent.pid.context 文件。
    5. 启动 LogAgent。
    上面 步骤 c 将使新启动的 LogAgent 使用新的进度,即从头读取发送所有文件,而 步骤 b 是避免从头发送导致数据发送重复。
  7. 新版本可直接用命令一键异常处理:
    bin/abnormal-reset --context_file ./logagent.pid.context  
    //在新版本的 log_agent 目录下执行以上命令
    重置之后可使用 bin/start 重新启动,继续运行!
  8. 发送的数据文件用“记事本”等工具编辑后无法发送数据。“记事本”等文本编辑工具在“保存”时可能是通过删除旧文件或截断文件后重新写入的方式来完成,这时会导致 4. 删除或截断(truncate)正在读取的文件 提到的问题。
  9. 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).

样例中值的解释:

  • 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

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

path=D:\\data\\logs

其他使用方式同本文档描述,先填写配置文件,再运行 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

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 天清理一次,可按需修改。

上一个
Integrator Importer
下一个
LogAgent 场景使用示例
最近修改: 2025-03-19