# LogBus Windows 版本使用指南
本节主要介绍数据传输工具 LogBus 的 Windows 版本使用方法：
在开始对接前，您需要先阅读数据规则，在熟悉 TA 的数据格式与数据规则后，再阅读本指南进行对接。
LogBus** 上传的数据必须遵循 TA 的**数据格式
# 下载 LogBus Windows 版本
最新版本为： 1.3.0
更新时间为： 2021-10-19
# 一、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 压缩包 (opens new window)，并解压。
2.解压后的目录结构：
- bin:启动程序文件夹
- conf:配置文件文件夹
- lib:功能文件夹
# 四、LogBus 的参数配置
1.进入解压后的conf目录，里面有一个配置文件logBus.conf.Template，该文件包含 LogBus 所有的配置参数，首次使用时可将其重命名为logBus.conf。
2.打开logBus.conf文件进行相关参数配置
# 4.1 项目与数据源配置（必须配置）
- 项目 APP_ID
APP_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
启动完成后会开启一个 logkit.exe，请勿关闭，否则可能会导致数据重复上传
# 六、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.3.0 --- 2021/10/19
- 支持非TA格式数据上传
# 版本 1.2.0 --- 2021/05/26
- 支持cygWin模式
# 版本 1.1.0 --- 2020/08/28
- 支持添加#UUID
- 支持#event_id 和#first_check_id
- 支持多线程发送
- 支持分隔符解析和正则解析
# 版本 1.0.0 --- 2020/06/25
- LogBus-Windows 发布