1. 生成数据

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

神策分析各后端语言的 SDK 都支持将数据写入文件,例如使用 Java SDK 的 ConcurrentLoggingConsumerPHP SDK 的 FileConsumerPython 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 来输出数据文件;若需要自己写数据文件,有几点需要注意:

  1. (非常重要)文件只能追加写入,即打开文件时以 Open Append 方式打开;
  2. 文件内容需要是 一条数据一行,并且是符合 数据格式 的完整 JSON;
  3. 数据文件名 必须 包含日期,还可以包含更详细的时间,例如将数据写到 service_log.20170925 或 service_log.2017092517,文件目录下文件应该类似如下:

    service_log.20170923
    service_log.20170924
    service_log.20170925
    CODE

    对应 LogAgent 中的配置:

    path=/data/sa
    pattern=service_log.*
    CODE
  4. 若多个进程写入同一个文件,需要使用文件锁避免文件交叉写入数据损坏;

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

在配置文件中,请删除或注释掉 hostport 和 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 指定数据导入项目

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

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

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

  1. 取配置文件中的 project
  2. 若上一步没有取到,取数据中的 project 字段;
  3. 若上一步没有取到,(若有配置)取 service_uri 的 project 参数;
  4. 若上一步没有取到,取默认项目的项目名,即 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 指定的位置分割了一条完整的埋点数据,那么该数据会被舍弃。