LogAgent 使用说明

最后更新于:2019-06-05 15:17:02

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

1. LogAgent 概述

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

几个应用场景举例:

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

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

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

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

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

2. 下载 LogAgent

当前最新版本:20190605

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

3. 部署 LogAgent

下面以 Linux 环境为例说明 LogAgent 的部署方法。

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

    wget http://download.sensorsdata.cn/release/logagent/logagent_20190605.tgz
    tar zxvf logagent_20190605.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
    
    • 其中需要 格外注意 的是,若有多台机器部署 LogAgent,需要确保在不同机器上 LogAgent ID 取值不同(上面示例中是 test01.sa),服务端记录各机器的进度,以 LogAgent ID 区分不同机器;
  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)
    

4. 常见问题

4.1 文件读取顺序

  1. LogAgent 读取的文件列表由 path 目录下:pattern 所匹配的文件 和 real_time_file_name 指定的文件(若有配置)组成。其他文件将被忽略,这意味着 real_time_file_name (即实时文件)改名后需要符合 pattern 的匹配规则;
  2. LogAgent 会对指定目录下所有规则匹配 pattern 的文件 按字典序排序,依次读取;
  3. real_time_file_name(若有配置)总是被放在文件列表的最后,即认为其是最新的文件;

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

4.3 不发送数据排查

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

  1. LogAgent 目录下的 log 目录中的 logagent.log 是否有报错信息。错误可能是数据格式问题、网络问题等。其中有问题的数据会被 LogAgent 过滤而不会被导入,并记录在 log 目录下的 invalid_records 文件里;
  2. 期望被读取的文件是否匹配配置中的 pattern。不符合 pattern 的文件不会被 LogAgent 扫描;
  3. 期望读取的文件在文件列表中是否位于当前进度之前。例如当前目录下有下列文件:

    data.2016090120
    data.2016090121
    

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

    • 新增一个文件 data.20160901不会被读取,因为按字典序排序目录下的文件,data.20160901data.2016090121 之前;
    • 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;

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

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

  6. 是否有多台机器使用了相同 LogAgent ID,问题一般表现为埋点管理里 LogAgent 的已接收 > 已校验。LogAgent ID 用于服务端数据去重,若配置文件里没有指定 LogAgent ID,默认以 fqdn 作为 LogAgent ID,这时请检查 fqdn 是否相同。
  7. LogAgent 日志没有明显错误信息,服务端查不到相关数据。LogAgent 只校验数据是否符合基本的数据格式,其他更详细的校验例如数据字段类型会在服务端模块内校验,请查看导入项目的“埋点管理”查看是否有报错信息。

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

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。

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
    

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 等。

校验失败会将数据和错误原因打印到日志里,若配置文件设置了 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:当添加该参数时,校验通过的数据不会写入神策分析系统。
  • 注意:校验数据一般用于少量数据检验格式、字段类型是否正确,不适用于大数据量的生产环境。

6. 更新日志

20190605

  1. Windows 下运行支持过滤 BOM;
  2. 支持 item 相关操作;

20180125

  1. 可通过环境变量指定 LogAgent 调试日志输出路径:

     SA_LOG_AGENT_LOG_PATH=/tmp/logagent.log bin/logagent
    

     export SA_LOG_AGENT_LOG_PATH=/tmp/logagent.log
     bin/logagent
    
  2. 更新 file-list-tool 脚本,详见 LogAgent 场景使用示例

20180108

修复 LogAgent 在 Windows 下使用时读取已加锁的文件导致的异常退出;

20171030

LogAgent 启动时若读到不完整的 context 将忽略文件内容;

20171028

  1. 修复当数据目录下文件列表为空时导致的空指针退出的问题,该问题于 20170922 之后版本存在;
  2. 修复 LogAgent 未成功启动时重写了 context 文件,该问题于 20170922 之后版本存在,context 文件用于排查问题和加速启动;

20171011

修复一个导致意外退出的 bug;

20170922

  1. 更详细的错误输出,以及相应的处理方法;
  2. 新增上下文文件,记录 LogAgent 运行状态,并通过上下文文件避免错误的 LogAgent 启动;
  3. 定期向服务端上报 LogAgent 状态,方便问题排查;

20170907

host 可以配置多个并以 ; 半角分号分隔;

20170707

  1. 修复安装 Java 脚本;
  2. 启动失败时,将异常写入日志便于排查;

20170511

  1. 新增对过期数据(根据数据 time 字段)的过滤,默认当前时间 2 年前和 1 小时后的数据将被忽略,并记录到日志目录下;
  2. 修复内部统计数据占用内存的问题;

20161122

  1. 添加对 $is_login_id 的支持,详情请见 如何准确的标识用户;
  2. 优化使用参数 --show_progress 时执行流程;
  3. 获取进度的请求超时改为 10 分钟;

20161114

优化 logagent.bat,Windows 下方便看到错误提示。

20160927

对有实时写入的文件,即配置 real_time_file_name 的场景进行优化。