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

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
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 中对每个配置项的说明;

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 ID 取值不同(上面示例中是 test01.sa),服务端记录各机器的进度,以 LogAgent ID 区分不同机器;

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

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

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

bin/logagent
CODE

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

7. 监控 LogAgent:
LogAgent 启动后会在程序目录下生成一个 logagent.pid 文件,记录了进程的 pid 号,如果 LogAgent 需要常驻,建议自行对该进程做监控。

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

kill $(cat logagent.pid)
CODE

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

1.4.3. 不发送数据排查

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

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

    data.2016090120
    data.2016090121
    CODE

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

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

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

  5. 发送的数据文件用 “记事本” 等工具编辑后无法发送数据。“记事本” 等文本编辑工具在 “保存” 时可能是通过删除旧文件或截断文件后重新写入的方式来完成,这时会导致 4.删除或截断(truncate)正在读取的文件 提到的问题。
  6. 是否有多台机器使用了相同 LogAgent ID,问题一般表现为埋点管理里 LogAgent 的 已接收 > 已校验。LogAgent ID 用于服务端数据去重,若配置文件里没有指定 LogAgent ID,默认以 fqdn 作为 LogAgent ID,这时请检查 fqdn 是否相同。
  7. 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).
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:第一个值是读取到文件中的位置,第二个值是正在读取的文件总大小。

1.4.5. 在 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。

1.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
    CODE

1.4.7. 断点续传

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

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

1.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
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:当添加该参数时,校验通过的数据不会写入神策分析系统。

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

1.6. 注意事项

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

1.7. 更新日志

1.7.1. 20191227

  1. 修改部分日志文案;
  2. 修复当 jre 版本大于 10 的时候启动失败的问题。
  3. 修复 window 环境下启动脚本找不到主类的问题。
  4. 修复 20191021 版本在生成额外日志文件可能导致进程僵死的问题。

1.7.2. 20191021

  1. 移除了通过启动参数指定 Sender 的功能;
  2. 可通过启动参数手工指定起始文件和 offset;
  3. 在出错时可额外生成日志文件保存最近的日志与错误原因;
  4. 修复 cookie 反序列化异常的问题。

1.7.3. 20190605

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

1.7.4. 20180125

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

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

1.7.5. 20180108

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

1.7.6. 20171030

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

1.7.7. 20171028

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

1.7.8. 20171011

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

1.7.9. 20170922

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

1.7.10. 20170907

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

1.7.11. 20170707

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

1.7.12. 20170511

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

1.7.13. 20161122

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

1.7.14. 20161114

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

1.7.15. 20160927

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