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

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 的场景进行优化。