LogAgent 场景使用示例
| 收藏

1. 生成数据

1.1 使用神策分析 SDK 生成数据文件

神策分析各后端语言的 SDK 都支持将数据写入文件，例如使用 Java SDK 的 ConcurrentLoggingConsumer，PHP SDK 的 FileConsumer，Python SDK 的 LoggingConsumer。下面以 Java SDK 为例：

// 使用 ConcurrentLoggingConsumer 初始化 SensorsAnalytics
// 将数据输出到 /data/sa 下的 service_log.2017-09-25 文件中，每天一个文件
final SensorsAnalytics sa = new SensorsAnalytics(
        new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa/service_log")); 

// 使用神策分析记录用户行为数据
sa.track(distinctId, true, "UserLogin");
sa.track(distinctId, true, "ViewProduct");

// 程序结束前，停止神策分析 SDK 所有服务
sa.shutdown();

JAVA

以上配置将在 /data/sa 目录下生成数据文件，一天一个文件，文件列表如：

service_log.20170923
service_log.20170924
service_log.20170925

CODE

对应 LogAgent 中的配置：

path=/data/sa
pattern=service_log.*

CODE

1.2 使用其他方式输出数据文件

若所使用的编程语言有对应的 SDK，建议直接使用 SDK 来输出数据文件；若需要自己写数据文件，有几点需要注意：

（非常重要）文件只能追加写入，即打开文件时以 Open Append 方式打开；
文件内容需要是 一条数据一行，并且是符合数据格式的完整 JSON；
数据文件名必须包含日期，还可以包含更详细的时间，例如将数据写到 service_log.20170925 或 service_log.2017092517，文件目录下文件应该类似如下：
```
service_log.20170923
service_log.20170924
service_log.20170925
```
CODE
对应 LogAgent 中的配置：
```
path=/data/sa
pattern=service_log.*
```
CODE
若多个进程写入同一个文件，需要使用文件锁避免文件交叉写入数据损坏；

2. 配置数据接收服务地址

2.1 私有部署版配置

LogAgent 将数据发送到服务端，至少需要配置接收数据的服务端地址，对应配置文件中 host 和 port 两个参数：

host：一个或多个以 ; 半角分号分隔的服务器 IP 地址。例如 192.168.50.10;192.168.50.11;192.168.50.12，LogAgent 启动时会选定其中一台发送数据，以均衡负载；
port：数据接收服务端口号，默认情况下集群版是 8106，单机版（1.7 及之前的版本为 8006，1.8 及之后的版本是 8106），云版不带端口号；

若部署神策分析同时有外网 IP 和内网 IP，host 的值应取内网 IP;

2.2 云版配置

点击“复制 https 数据接收地址”，例如复制到的是 https://example.datasink.sensorsdata.cn/sa?project=production&token=c9239cb3139077ca

在配置文件中，请删除或注释掉 host、port 和 token 字段，启用 service_uri 字段，取值是将上面获取到的值中的 /sa 改为 /log_agent，例如对于上面样例，应配置 https://example.datasink.sensorsdata.cn/log_agent?token=c9239cb3139077ca。

指定数据发往的项目请参考本文档 4.1 节。

2.3 通过外网使用额外需要注意的配置

LogAgent 是为内网后端实时数据导入设计开发，若通过公网使用 LogAgent 需要额外注意：

请确保一个 LogAgent 每次请求都落到同一台机器上。如果使用负载均衡，负载均衡算法请选择 ip_hash 源地址 方式；如果域名 DNS 直接解析到多台机器，则不能使用域名，应直接指定一个 IP 或按上面规则拼接多个服务器的外网 IP；
若公网使用 LogAgent 且服务端已经配置了 HTTPS 数据接入方式，可以按如下步骤配置使用 HTTPS 发送数据：
1. 注释掉配置文件中的 host、port 和 token 字段，即不使用 host、port 和 token 参数；
2. 在配置文件中启用 service_uri 字段，一个样例值为 https://example.sensorsdata.cn:4006/log_agent，请注意端口号应为 HTTPS 数据接入服务的地址，uri 是 /log_agent，而不是 /sa;

3. 其他配置说明

3.1 配置实时写入文件的文件名 real_time_file_name

配置文件中的 real_time_file_name 即实时写入文件的文件名, 一般用在滚动日志文件的场景。例如按日切分的数据目录下文件列表如下：

service_log.20170922
service_log.20170923
service_log

CODE

数据输出进程只向 service_log 中写入，当到了新的一天，定时调度程序将 service_log 改名为带日期的文件例如 service_log.20170923，数据输出进程开始写一个新的 service_log 文件，在这个场景里配置应当是:

pattern=service_log.*
real_time_file_name=service_log

CODE

即 pattern 可以匹配所有改名后的数据文件名，而 real_time_file_name 为实时输出的数据文件名。

3.2 以下场景无需配置 real_time_file_name

配置文件中的 real_time_file_name 优先级高于 pattern 参数，如果数据输出进程直接向 service_log.yyyymmdd / service_log.yyyymmddhh 中写入数据，且每天自动生成新的文件，则需要注释掉此参数，只配置 pattern 参数即可，否则数据可能会无法正常导入。

以 JAVA SDK 为例，使用 JAVA SDK 的 ConcurrentLoggingConsumer，通过 new SensorsAnalytics.ConcurrentLoggingConsumer(“/data/sa/service_log”))，此配置将在 /data/sa 目录下每天生成一个带日期的数据文件，文件列表如：

service_log.20170923
service_log.20170924
service_log.20170925

CODE

对应 LogAgent 中的配置：

path=/data/sa
pattern=service_log.*
# real_time_file_name=access_log

CODE

注：目前神策分析所有服务端 SDK 的 ConcurrentLoggingConsumer 模式下生成的日志文件都是每天生成一个带日期的数据文件，对应 LogAgent 的配置均无需配置 real_time_file_name 参数。

4. 其他使用场景说明

4.1 指定数据导入项目

指定数据导入的项目有两种方法：

在每条数据中添加 project 字段（详见数据格式），使用这种方式可以每条数据导入各自的项目；
在配置文件中指定 project。每条数据无论是否指定 project 字段都将导入到参数设置的项目中。

系统判定一条数据所属项目的流程为：

取配置文件中的 project；
若上一步没有取到，取数据中的 project 字段；
若上一步没有取到，（若有配置）取 service_uri 的 project 参数；
若上一步没有取到，取默认项目的项目名，即 default。

如果想用一个 LogAgent 导入多个项目的数据，请不要在配置文件中设置 project，在数据中添加 project 字段来设置每条数据所属项目。

4.2 使用 file-list-tool 列出文件读取情况

LogAgent 提供了 file-list-tool：

$ bin/file-list-tool
usage: [file-checker] --context_file <arg> [-h] [--new_file_format <arg>]
       [--old_file_format <arg>] [--reading_file_format <arg>]
    --context_file <arg>          LogAgent context file path, e.g.
                                  logagent.pid.context
 -h,--help                        help
    --new_file_format <arg>       对每个未读过的新文件的输出格式，指定后会格式化并输出，文件名以 {} 代替
    --old_file_format <arg>       对每个旧文件的输出格式，指定后会格式化并输出，文件名以 {} 代替
    --reading_file_format <arg>   对正在读取的文件的输出格式，指定后会格式化并输出，文件名以 {} 代替

BASH

使用 file-list-tool 解析 context 文件（与 pid 文件在同一个目录下）可以列出每个文件的读取状态：

$ bin/file-list-tool --context_file logagent.pid.context
18/01/22 17:35:29 INFO logagent.SourceFileReader: SourceFileReader recover progress:
[ fileKey: (dev=fc10,ino=118226959), offset: 11260636, fileName: test_data.2018012213, count: 161982, sourceCount: 161982 ]
18/01/22 17:35:29 INFO logagent.FileListTool: 进度之前的文件, path: /data/test/logagent/data/test_data.2018012212, size: 19191980, key: (dev=fc10,ino=118226958)
18/01/22 17:35:29 INFO logagent.FileListTool: 读取中的文件, path: /data/test/logagent/data/test_data.2018012213, size: 11260824, key: (dev=fc10,ino=118226959), tell: 11260636
18/01/22 17:35:29 INFO logagent.FileListTool: 进度之后的文件, path: /data/test/logagent/data/test_data.2018012214, size: 19191980, key: (dev=fc10,ino=118226960)

BASH

“进度之前的文件” 即已经读取过的可以安全地从 LogAgent 读取目录移走或删除的文件。

file-list-tool 还可以以指定格式输出文件列表，例如下面的例子生成将已经读取过的文件移到指定目录的命令文件 mv.sh 并执行：

$ bin/file-list-tool --context_file logagent.pid.context --old_file_format 'mv {} /data/test/logagent/backup' > mv.sh
18/01/22 17:44:29 INFO logagent.SourceFileReader: SourceFileReader recover progress:
[ fileKey: (dev=fc10,ino=118226959), offset: 11260636, fileName: test_data.2018012213, count: 161982, sourceCount: 161982 ]
18/01/22 17:44:29 INFO logagent.FileListTool: 进度之前的文件, path: /data/test/logagent/data/test_data.2018012212, size: 19191980, key: (dev=fc10,ino=118226958)
18/01/22 17:44:29 INFO logagent.FileListTool: 读取中的文件, path: /data/test/logagent/data/test_data.2018012213, size: 11260824, key: (dev=fc10,ino=118226959), tell: 11260636
18/01/22 17:44:29 INFO logagent.FileListTool: 进度之后的文件, path: /data/test/logagent/data/test_data.2018012214, size: 19191980, key: (dev=fc10,ino=118226960)

$ cat mv.sh
mv /data/test/logagent/data/test_data.2018012212 /data/test/logagent/backup

$ bash mv.sh

BASH

4.3 使用 --filename --offset 参数指定起始文件和 offset

版本高于 20191021 的 LogAgent 启动时可手工指定起始文件和 offset ：

$ bin/logagent --filename service.log.20191021 --offset 100

BASH

注意：

1. 启动后会忽略起始值之前所有的日志文件；
2. 该配置在与服务端正常获取进度之后才会生效。
3. --filename 只需设置文件名无需包含路径，文件必须在配置文件中指定的路径 path 下存在且名称必须符合 pattern 规定的格式。
4. --offset 必须与 --filename 搭配使用，默认值为 0。
5. 如果 --offset 指定的位置分割了一条完整的埋点数据，那么该数据会被舍弃。