LogBus Windows版本使用指南
本节主要介绍数据传输工具LogBus的Windows版本使用方法：
在开始对接前，您需要先阅读数据规则，在熟悉TA的数据格式与数据规则后，再阅读本指南进行对接。
LogBus上传的数据必须遵循TA的数据格式
下载LogBus Windows版本
最新版本为： 1.1.0
更新时间为： 2020-08-28
一、LogBus简介
LogBus工具主要用于将后端的日志数据实时地导入到TA后台，其核心工作原理类似于Flume，会监控服务器日志目录下的文件流，当目录下任意日志文件有新数据产生时，会对新数据进行校验，并实时发送至TA后台。
以下几类用户建议使用LogBus接入数据：
- 使用服务端SDK的用户，通过LogBus上传数据
- 对数据的准确性及维度要求较高，仅通过客户端SDK无法满足数据需求，或不方便接入客户端SDK
- 不想自己开发后端数据推送流程
- 需要传输大批量历史数据
二、使用前数据准备
1.首先将需要传输的数据进行ETL转换成TA的数据格式，并写到本地或传输至Kafka集群，如果使用的是服务端SDK的写入本地文件或Kafka的consumer，则数据已经是正确的格式，无需再进行转换。
2.确定上传数据的文件存放的目录，或者Kafka的地址与topic，并配置LogBus的相关配置，LogBus会监控文件目录下的文件变更（监控文件新建或tail已有文件），或者订阅Kafka中的数据。
3.请勿对存放于监控目录下且已经上传的数据日志直接进行重命名，重命名日志相当于新建文件，LogBus将可能会重新上传这些文件，造成数据重复。4.由于LogBus数据传输组件中包含数据缓冲区，LogBus目录占磁盘可能会稍大，因此请确保LogBus安装节点的磁盘空间充足，每向一个项目（即增加一个APP_ID）传输数据需预留至少10G的存储空间。
三、LogBus的安装与升级
3.1 安装LogBus
1.下载LogBus压缩包，并解压。
2.解压后的目录结构：
- bin:启动程序文件夹
- conf:配置文件文件夹
- lib:功能文件夹
四、LogBus的参数配置
1.进入解压后的conf目录，里面有一个配置文件logBus.conf.Template，该文件包含LogBus所有的配置参数，首次使用时可将其重命名为logBus.conf。
2.打开logBus.conf文件进行相关参数配置
4.1 项目与数据源配置（必须配置）
- 项目APP_IDAPP_ID不可重复配置
##APPID来自tga官网的token，请在TA后台的项目配置页面获取接入项目的APPID并填入此处，多个APPID通过","分割
APPID=APPID_1,APPID_2
- 监控文件配置（请选择其中一种，必须配置）
4.1.1.数据来源是本地文件时
##LogBus读取的数据文件所在的路径及文件名(文件名支持模糊匹配), 需要有读权限
##不同APPID用逗号隔开，相同APPID不同目录用空格隔开
##TAIL_FILE的文件名支持通配符匹配
TAIL_FILE=C:/path1/dir*/log.*,C:/path3/txt.*
TAIL_FILE支持对多路径下的多分目录中的多个文件进行监控
对应参数配置为：
APPID=APPID1,APPID2
TAIL_FILE=C:/root/log_dir1/dir_*/log.* C:/root/log_dir*/log*/log.*,C:/test_log/*
具体规则如下：
- 同一APP_ID的多个监控路径通过空格分割
- 不同APP_ID的监控路径通过逗号","分割，且按逗号分割后监控路径对应APP_ID
- 监控路径中的目录支持通过通配符监控
- 文件名支持使用通配符监控
- 路径分隔符可使用"/"或"\\"，请勿使用"\"，例如：C:/root/.log 或 C:\\root\\.log
4.1.2.数据来源为kafka时
参数KAFKA_TOPICS需监控多个topic时，可使用空格分隔各topic；如存在多APP_ID，则使用半角逗号分割各APP_ID监控的topic。参数KAFKA_GROUPID必须唯一。参数KAFKA_OFFSET_RESET，可设置Kafka的kafka.consumer.auto.offset.reset参数，可取值为earliest与latest，默认设置为earliest。
注意：数据源的Kafka版本必须在 0.10.1.0 或更高
单APP_ID样例：
APPID=appid1
######kafka 配置
#KAFKA_GROUPID=tga.group
#KAFKA_SERVERS=localhost:9092
#KAFKA_TOPICS=topic1 topic2
#KAFKA_OFFSET_RESET=earliest
多APP_ID样例：
APPID=appid1,appid2
######kafka 配置
#KAFKA_GROUPID=tga.group
#KAFKA_SERVERS=localhost:9092
#KAFKA_TOPICS=topic1 topic2,topic3 topic4
#KAFKA_OFFSET_RESET=earliest
4.2 传输参数配置（必须配置）
##传输设置
##传送的url
##http传输请使用
PUSH_URL=http://receiver.ta.thinkingdata.cn/logbus
##如果您使用的是私有化部署服务，请修改传输URL为：http://数据采集地址/logbus
##每次传输的最大数量
#BATCH=10000
##最少多久传一次(单位：秒)
#INTERVAL_SECONDS=600
##传输线程数，默认单线程，建议网络条件较差时使用，多线程会耗费更大的内存和CPU资源
#NUMTHREAD=1
##文件传输的压缩格式:gzip,snappy,none
#COMPRESS_FORMAT=none
4.3 转换器配置（可选配置）
##转换器类型暂时支持json csv regex splitter
#PARSE_TYPE=json
##额外固定属性，格式为：name value,name1 value1
#LABELS=
##属性名和类型，适用于PARSE_TYPE为：csv regex splitter，格式为：name type,name1 type1
##支持的类型有：float int string date list bool
#SCHEMA=
##指定分隔符，PARSE_TYPE为csv splitter时不能为空
#SPLITTER=
##指定list类型的分隔符，适用于存在list类型时，默认为,
#LIST_SPLITTER=,
##正则表达式，PARSE_TYPE为regex时不能为空
#FORMAT_REGEX=
4.4 监控文件删除配置（可选配置）
# 监控目录文件删除,去除注释即为启动删除文件功能
# 只能以按天(day)或按小时(hour)删除
# UNIT_REMOVE=hour
# 删除多久之前的文件
# OFFSET_REMOVE=20
# 删除已经上传的监控文件，每隔多少分钟删除
# FREQUENCY_REMOVE=60
4.5 配置文件示例
##################################################################################
## thinkingdata数据分析平台传输工具logBus配置文件
##非注释的为必填参数,注释的为选填参数,可以根据你自身的情况进行
##合适的配置
##环境要求：java8+,更详细的要求请详见tga官网
##http://doc.thinkinggame.cn/tdamanual/installation/logbus_installation.html
##################################################################################
##APPID来自tga官网的token
##不同APPID用逗号隔开，不可重复配置
APPID=from_tga1,from_tga2
#-----------------------------------source----------------------------------------
######file-source
##LogBus读取的数据文件所在的路径及文件名(文件名支持模糊匹配), 需要有读权限
##不同APPID用逗号隔开，相同APPID不同目录用空格隔开
##TAIL_FILE的文件名支持java标准的正则表达式
TAIL_FILE=C:/path1/log.* C:/path2/txt.*,C:/path3/log.* C:/path4/log.* C:/path5/txt.*
######kafka-source
#KAFKA_GROUPID=tga.flume
#KAFKA_SERVERS=
#KAFKA_TOPICS=
#KAFKA_OFFSET_RESET=earliest
#------------------------------------sink-----------------------------------------
##传输设置
##传送的url
##如果您使用的是私有化部署服务，请修改传输URL为：http://数据采集地址/logbus
##PUSH_URL=http://receiver.ta.thinkingdata.cn/logbus
PUSH_URL=http://${数据采集地址}/logbus
##每次传输的最大数量
#BATCH=10000
##最少多久传一次(单位：秒)
#INTERVAL_SECONDS=60
##### http传输
##文件传输的压缩格式:gzip,snappy,none
#COMPRESS_FORMAT=none
##是否在每条数据中增加uuid属性
#IS_ADD_UUID=true
#------------------------------------parse----------------------------------------
##转换器类型暂时支持json csv regex splitter
#PARSE_TYPE=json
##额外固定属性，格式为：name value,name1 value1
#LABELS=
##属性名和类型，适用于PARSE_TYPE为：csv regex splitter，格式为：name type,name1 type1
##支持的类型有：float int string date list bool
#SCHEMA=
##指定分隔符，PARSE_TYPE为csv splitter时不能为空
#SPLITTER=
##指定list类型的分隔符，适用于存在list类型时，默认为,
#LIST_SPLITTER=,
##正则表达式，PARSE_TYPE为regex时不能为空
#FORMAT_REGEX=
#------------------------------------other----------------------------------------
##监控目录下文件删除,打开注释(必须将下面两个字段都打开)即为启动删除文件功能，每一个小时启动一次文件删除程序
##按unit删除offset之前的文件
##删除多久之前的文件
#OFFSET_REMOVE=
##只接收按天(day)或小时(hour)删除
#UNIT_REMOVE=
五、启动LogBus
在首次启动前请进行以下检查：
1.检查java版本
进入bin目录，里面会有两个脚本，check_java.bat与logbus.bat
其中check_java用于检测java版本是否满足要求，执行脚本，若java版本不满足会出现Java version is less than 1.8或Can't find java, please install jre first.等提示
您可以更新JDK版本或查看下一节中的内容为LogBus单独安装JDK
2.安装LogBus的独立JDK
如果LogBus部署节点，由于环境关系，JDK版本不满足LogBus需求，又无法替换成满足LogBus的JDK版本。可以使用此功能。
进入bin目录，里面会有install_logbus_jdk.bat。
运行此脚本会在LogBus工作目录新增出java目录。LogBus会默认使用这个目录下的JDK环境。
3.完成logBus.conf的配置，并运行参数环境检查命令
logBus.conf的配置请参考配置LogBus一节
配置完成后运行 env 命令，检查配置参数是否正确
logbus.bat env
如果输出红色异常信息，说明配置有问题，需要重新修改，直到配置文件没有异常的提示。
当您修改了logBus.conf的配置后，需要重启LogBus以使新配置生效
4.启动LogBus
logbus.bat start
六、LogBus命令详解
6.1 帮助信息
不带参数或--help或-h，将会显示帮助信息
主要介绍LogBus的命令：
usage: logbus <命令|辅助命令> [选项]
命令:
start 启动logBus.
restart 重启logBus.
stop 安全退出logBus.
reset 重置logBus读取记录.
stop_atOnce 强制退出logBus.
辅助命令：
env 运行环境校验.
server [-url <url>|-url <url> -appid <appid>] 测试接收端网络情况
show_conf 显示当前logBus配置信息.
version 显示版本号.
update 更新logbus到最新版本.
选项：
-appid <appid> 项目appid
-h,--help 显示帮助文档并退出.
-path <path> 指定测试文件的绝对路径
-url <url> 指定测试的url地址
示例：
logbus.bat start 启动logBus.
logbus.bat stop 安全退出logBus.
logbus.bat restart 重启logBus.
logbus.bat server -url http://${接收端地址}/logbus -appid ***** 测试接收端网络情况
6.2 传输通道检查server -url
在您完成格式校验后，您还需要检查数据通道是否打通，您可以使用server -url命令进行校验，在校验的同时可以输入您在TA平台收到的APP_ID，要注意APP_ID与您的项目是绑定的，在输入前请务必保证您输入的APP_ID对应您的项目
logbus.bat server -url http://${接收端地址}/logbus -appid ${appid}
6.3 展示配置信息show_conf
您可以使用show_conf命令来查看LogBus的配置信息，展示内容如下图所示：
logbus.bat show_conf
6.4 启动环境检查env
您可以使用env进行启动环境的检查，如果输出的信息后面带有星号，就说明配置有问题，需要重新修改，直至没有星号提示。
logbus.bat env
6.5 升级LogBus版本update
您可以使用update进行在线更新版本，该命令会将LogBus更新到最新版本
logbus.bat update
6.6 启动start
当您完成格式的校验、数据通道的检查以及环境检查后，即可启动LogBus进行数据的上传，LogBus将会自动检测您的文件是否有新数据写入，如果有新数据，则将数据进行上传。
logbus.bat start
6.7 停止stop
如果您想要停止LogBus。请使用stop命令，该命需要花费一定时间，但不会有数据损失。
logbus.bat stop
6.8 停止stop_atOnce
如果您想要立刻停止LogBus，请使用stop_atOnce命令，该命令可能导致数据丢失。
logbus.bat stop_atOnce
6.9 重启restart
您可以使用restart命令重启LogBus，适合在修改配置参数后使新配置生效。
logbus.bat restart
6.10 重置reset
使用reset将会重置LogBus，请务必谨慎使用该命令，一旦使用将会清空文件传输记录，LogBus将会重新上传所有数据。如果您在不明确的条件下使用该命令，可能导致您的数据出现重复。建议在与TA工作人员沟通后再进行使用。
logbus.bat reset
使用重置命令后，需要执行start重新开始传输数据
6.11 查看版本号version
如果您想要了解您所使用的LogBus的版本号，可以使用version命令，如果您的LogBus没有该命令，则您所使用的版本属于早期版本
logbus.bat version
七、ChangeLog
版本1.1.0 --- 2020/08/28
- 支持添加#UUID
- 支持#event_id和#first_check_id
- 支持多线程发送
- 支持分隔符解析和正则解析
版本1.0.0 --- 2020/06/25
- LogBus-Windows发布