@thinkingai/ae-cli 1.0.30 → 6.0.16

package/skills/ae-data-integration-helper/references/logbus2_guide.md

@@ -0,0 +1,309 @@
+# LogBus2 Usage Guide
+
+> **Terminology**: 日志同步工具 = log sync tool | 数据格式转换 = data format conversion | 数据源 = data source | 磁盘空间 = disk space | 本地磁盘队列 = local disk queue | Kafka = Kafka message queue | 文件存放目录 = file storage directory | 传输速度 = transfer speed | 内存占用 = memory usage | 数据分流 = data routing (to multiple projects) | 神策数据 = Sensors Analytics data format | CPU 限制 = CPU limit | 带宽占用 = bandwidth usage | 网络条件 = network conditions | 磁盘 IO = disk IO | 监听文件 = watched/monitored files | 重试 = retry | 断点续传 = resume from breakpoint | 数据校验 = data validation | 黑名单 = blacklist (filter out events/properties) | 白名单 = whitelist (filter in events/properties) | 字段过滤 = field filtering | 数据脱敏 = data masking
+
+## 一、简介
+
+LogBus2 是数数科技在原 LogBus 基础上，使用 Go 语言重新开发的日志同步工具。相比 LogBus1，具有以下优势：
+
+- **内存占用更低**：减少至原先的五分之一（约 100-200M）
+- **传输速度更快**：提升至 3-5万条/秒
+- **运行更稳定**：logbus1在一些特殊场景下，文件缓存区修复难度较高
+- **部署更简单**：无需 JDK 环境，直接运行
+
+## 二、使用前准备
+
+1. **数据格式转换**：将需要传输的数据转换成 TE 的数据格式，支持 TA 格式和神策格式
+2. **确定数据源**：确定文件存放目录或 Kafka 地址与 topic
+3. **磁盘空间**：相比 LogBus1，LogBus2 去掉了本地磁盘队列，磁盘占用更小
+
+## 三、应用场景
+
+- 使用数数服务端 SDK 中 LogConsumer 模式的用户
+- 对数据准确性及维度要求较高的场景
+- 需要传输大批量历史数据
+- 需要数据分流到多个项目的场景
+- 需要对接神策数据的场景
+
+## 四、性能指标
+
+| 指标 | 说明 |
+|------|------|
+| 传输速度 | 3-5万条/秒（单个LogBus） |
+| 内存占用 | 约 100-200M |
+| CPU 限制 | 支持 cpu_limit 配置 |
+| 带宽占用 | 峰值约 70Mbps |
+
+> 传输效率受网络条件、磁盘 IO、系统分配资源、监听文件数量等因素影响。
+
+## 五、支持环境
+
+| 操作系统 | 架构 | 说明 |
+|----------|------|------|
+| Linux | amd64 | 推荐 |
+| Linux | arm64 | 支持 |
+| Windows | amd64 | 支持 |
+| macOS | amd64 | 支持 |
+| Docker | - | 宿主机持久化 |
+| K8S | - | 支持 Helm 部署 |
+
+下载地址：[官网下载](https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US)
+
+## 六、配置指南
+
+### 文件数据源配置
+
+```json
+{
+    "push_url": "http://RECEIVER_URL",
+    "cpu_limit": 4,
+    "datasource": [
+        {
+            "type": "file",
+            "file_patterns": ["/data/log/*.log"],
+            "app_id": "your_app_id",
+            "http_compress": "gzip",
+            "unit_remove": "day",
+            "offset_remove": 7
+        }
+    ]
+}
+```
+
+### Kafka 数据源配置
+
+```json
+{
+    "datasource": [
+        {
+            "type": "kafka",
+            "topic": "topic1,topic2",
+            "consumer_group": "consumer_group_name",
+            "brokers": ["localhost:9092"],
+            "auto_commit": false,
+            "app_id": "your_app_id"
+        }
+    ],
+    "push_url": "http://RECEIVER_URL"
+}
+```
+
+### 多项目数据分流配置
+
+```json
+{
+    "datasource": [
+        {
+            "file_patterns": ["/data/log/*.log"],
+            "app_id": "default_app_id",
+            "app_pipe": {
+                "attribute": "#lib_version",
+                "id_map": {
+                    "app_id_1": "1.0.0",
+                    "app_id_2": "2.0.0"
+                },
+                "default": "app_id_1"
+            }
+        }
+    ],
+    "push_url": "http://RECEIVER_URL"
+}
+```
+
+### 告警配置
+
+```json
+{
+    "alert": {
+        "enabled": true,
+        "receiver": "feishu_robot",
+        "extra": "logbus_instance_1",
+        "out_cfg": {
+            "feishu_robot_hook": "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
+        }
+    }
+}
+```
+
+## 七、常用操作命令
+
+### 环境检查
+
+```bash
+./logbus env
+```
+
+### 启动服务
+
+```bash
+./logbus start
+```
+
+### 停止服务
+
+```bash
+./logbus stop
+```
+
+### 查看同步进度
+
+```bash
+./logbus progress
+```
+
+### 升级版本
+
+```bash
+./logbus stop
+./logbus update
+./logbus start
+```
+
+### 查看传输速度
+
+查看 `logbus/log/transporter.log` 确认发送效率。
+
+## 八、配置参数详解
+
+### 全局配置
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| push_url | string | - | Receiver 地址，必填 |
+| cpu_limit | int | - | CPU 核心限制 |
+| ignore_app_id_verify | bool | false | 是否跳过 appid 和 push_url 校验 |
+
+### 数据上报配置
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| batch | int | 1000 | 数据发送条数条件，最小10，最大100000 |
+| interval_seconds | int | 2 | 数据发送时间间隔，最大60秒 |
+| send_thread_num | int | 3 | 数据上报线程数 |
+| http_timeout | string | 30s | HTTP 请求超时时间 |
+| http_compress | string | - | HTTP 压缩协议，支持 gzip/snappy |
+
+### 文件数据源配置
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| file_patterns | []string | - | 文件 glob 匹配模式，必填 |
+| traverse_dir_interval | string | 30s | 扫描目录间隔时间 |
+
+### Kafka 数据源配置
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| topic | string | - | Kafka topic，支持多 topic（逗号分隔） |
+| brokers | []string | - | Kafka broker 地址 |
+| consumer_group | string | - | 消费者组 |
+| auto_commit | bool | false | 是否自动提交 |
+| protocol | string | none | 认证协议：plain/scramsha256/scramsha512/iam/none |
+| fetch_count | int | 1000 | 一次性拉取数据条数 |
+
+### 文件删除配置
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| offset_remove | int | - | 删除周期 |
+| unit_remove | string | d | 删除单位：d(天)/h(小时) |
+| RemoveDirs | bool | false | 是否删除文件夹，不建议配置，可能导致服务端写入异常 |
+
+## 九、注意事项
+
+### 文件操作相关
+
+> **禁止对 LogBus 监听的文件进行重命名操作**，否则会导致数据丢失或数据重复。
+
+### 监听文件要求
+
+- LogBus 监听路径下文件必须是纯净的数据文件
+- 不能有 gz/.iso/.rpm/.zip/.bz/.rar/.bz2 后缀的文件
+- LogBus-v2 默认会绕过这些文件
+
+### 多实例运行
+
+- 可运行多个 LogBus，但多个 LogBus 不能监听相同路径下的文件上报到同一个项目
+
+### Kafka 消费优化
+
+- 消费者线程数建议与分区数相等
+- 避免单个 LogBus 消费 hash 模余结果一致的分区
+- 可通过增加分区数和 LogBus 消费者数来加快消费
+
+### 数据补报注意事项
+
+- 如果是历史数据，建议开启历史通道
+- 及时关注 Kafka 集群是否有数据积压
+- 补数据建议发送到单独的 topic，避免与正式数据混淆
+
+## 十、常见问题
+
+### 如何确认网络是否通畅？
+
+```bash
+curl 数据接收地址/health-check
+```
+
+### 如何确认 APPID 是否正确？
+
+```bash
+curl "数据接收地址/check_appid?appid=目标APPID"
+```
+
+返回 `{"code":0}` 即为正常。
+
+### 数据重复的原因？
+
+1. 是否对已同步完成的文件进行重命名
+2. 源数据文件中数据是否有重复
+3. 是否执行了 reset 操作
+
+### 传输较慢怎么办？
+
+1. 调大 `send_thread_num` 发送线程数
+2. 开启 HTTP 压缩：`http_compress: "gzip"`
+3. 检查网络延迟、带宽，建议 LogBus 与 Receiver 在同一内网
+4. 检查是否有限制 CPU、内存
+
+### Kafka 消费较慢怎么办？
+
+1. 增加 LogBus 实例
+2. 调大单个 LogBus 的 `send_thread_num`
+3. 增加分区数
+4. 最佳策略：LogBus 消费者线程数 = 分区数
+
+### 读取策略差异导致上报延迟？
+
+如果服务端数据存在多进程同时写入数据到不同文件的情况，logbus2老版本会出现串行读取的情况，导致部分实时写入的文件没有实时上报，新版本已兼容此场景。
+
+```bash
+# 停止 LogBus
+./logbus stop
+
+# 升级 LogBus
+./logbus update
+
+# 重启 LogBus
+./logbus start
+```
+
+## 十一、最佳实践建议
+
+### 部署建议
+
+1. **资源规划**：根据数据量合理配置 CPU 和内存
+2. **网络优化**：LogBus 与 Receiver 部署在同一内网
+3. **监控告警**：配置告警通知，及时发现异常
+
+### 配置建议
+
+1. **压缩传输**：建议开启 gzip 压缩，减少网络传输量
+2. **文件清理**：配置自动删除策略，避免磁盘空间不足
+3. **线程配置**：根据数据量调整发送线程数
+
+### 运维建议
+
+1. **版本升级**：定期关注发版记录，及时升级
+2. **日志留存**：合理配置日志留存时间
+3. **进程监控**：对 LogBus 进程进行监控

package/skills/ae-data-integration-helper/references/logbus2_parser_plugin.md

@@ -0,0 +1,348 @@
+# LogBus2 Data Parser Plugin
+
+> **Terminology**: 数据转译插件 = data parser/translation plugin | 自定义数据解析器 = custom data parser | 数据格式转换 = data format conversion | gRPC 插件 = gRPC plugin | 批量处理 = batch processing | 分隔符 = separator / delimiter | 拼接 = concatenate | proto 文件 = .proto file (Protocol Buffers) | 告警功能 = alerting | 无限重试 = infinite retry | 错误数据 = malformed/error data | 标准 TA 格式 = standard ThinkingAnalytics data format
+
+> Logbus2 from version 2.1.0.0 supports custom data parsers for converting source data formats that differ from the TE data format. This is equivalent to Logbus1's Custom Interceptor feature.
+
+## 一、准备工作
+
+### 数据格式
+
+1. gRPC插件服务端接收数据进行批量处理，多条数据以Logbus2配置参数 parser.separator（默认 :: )拼接
+2. 单条数据则拼接文件名称或者Kafka的topic名称，以配置参数 parser.index_separator（默认 |ta| ）拼接
+
+示例：
+
+```python
+# 文件名称为：event.log
+# 原始数据2条：
+{"user_id": "abc", "distinct_id": "123"}
+{"user_id": "def", "distinct_id": "456"}
+
+# gRPC插件服务端接收到的数据为：
+event.log|ta|{"user_id": "abc", "distinct_id": "123"} ::event.log|ta|{"user_id": "def", "distinct_id": "456"}
+```
+
+gRPC插件服务端返回数据格式，以parser.separator拼接转换为标准ta格式的数据：
+
+```python
+# 返回数据应为：
+{"#account_id": "abc", "#distinct_id": "123"}::{\"#account_id\": \"def\", \"distinct_id\": \"456\"}
+```
+
+错误处理：
+- 返回非正确json数据，则主程序会跳过错误行
+- 返回非标准ta数据，则数据上报会产生错误
+- 返回第二个参数为error，则会进行无限重试，防止错误数据进入te集群。可搭配告警功能，提前预知错误信息。
+
+### proto文件
+
+parser.proto 文件用于生成各语言的 gRPC 服务端代码。
+
+### Java
+
+1. JDK 8+ (Logbus部署环境和开发环境保持一致)、Maven
+2. 下载 protobuf 编译工具：https://github.com/protocolbuffers/protobuf/releases
+3. 下载 grpc-java 编译工具：https://repo.maven.apache.org/maven2/io/grpc/protoc-gen-grpc-java/
+
+编译步骤：
+
+```shell
+# 生成ParserGrpc.java文件
+protoc --plugin=protoc-gen-grpc-java=protoc-gen-grpc-java-1.51.0-osx-aarch_64.exe  --grpc-java_out=/ta/path/ -I=/ta/path/ /ta/path/parser.proto
+
+# 生成ParserOuterClass.java文件
+protoc --experimental_allow_proto3_optional -I /ta/path/ --java_out=/ta/path/ /ta/path/parser.proto
+```
+
+### Python
+
+1. Python3.6+
+2. 安装三方库：
+
+```shell
+pip3 install grpcio-tools==1.48.2 -i https://pypi.tuna.tsinghua.edu.cn/simple
+pip3 install grpcio-health-checking==1.48.2 -i https://pypi.tuna.tsinghua.edu.cn/simple
+```
+
+编译步骤：
+
+```shell
+python -m grpc_tools.protoc -I /ta/path/ --python_out=/ta/path/ --grpc_python_out=/ta/path/ /ta/path/parser.proto
+```
+
+## 二、gRPC服务端开发
+
+### Java版本（所需版本JDK 8+）
+
+Maven依赖：
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>com.google.protobuf</groupId>
+        <artifactId>protobuf-java</artifactId>
+        <version>3.19.4</version>
+    </dependency>
+    <dependency>
+        <groupId>io.grpc</groupId>
+        <artifactId>grpc-all</artifactId>
+        <version>1.51.0</version>
+    </dependency>
+</dependencies>
+```
+
+开发转译逻辑demo：
+
+```java
+package org.interceptor.logbus2.service;
+
+import org.interceptor.logbus2.proto.ParserGrpc;
+import org.interceptor.logbus2.proto.ParserOuterClass;
+import com.google.protobuf.ByteString;
+import io.grpc.Server;
+import io.grpc.ServerBuilder;
+import io.grpc.stub.StreamObserver;
+import java.util.*;
+
+public class Demo extends ParserGrpc.ParserImplBase {
+
+    // 对应logbus2参数parser.separator，多条数据之间自定义的分隔符，默认 ::
+    private static final String separator = ":ta:";
+    
+    // 对应logbus2参数parser.index_separator，单条数据，索引与数据之间的分隔符，默认 |ta|
+    private static final String indexSeparator = "\\|ta\\|";
+    
+    // 对应logbus2参数parser.batch_separator，用于数据一条转多条的分隔符，默认 0x01
+    private static final String batchSeparator = new String(new byte[]{0x01}, StandardCharsets.UTF_8);
+    
+    public static String parseData(final String rawData) {
+        try {
+            // 处理逻辑：将接收到的数据中的test字符转为product，并将数据增加为3条返回
+            String parseData = JSON.toJSONString(JSON.parseObject(rawData.replaceAll("test", "product"), TaDataDo.class));
+            return parseData + batchSeparator + parseData + batchSeparator + parseData;
+        } catch (Exception e) {
+            e.printStackTrace();
+            return null;
+        }
+    }
+    
+    @Override
+    public void parse(ParserOuterClass.Request request, StreamObserver<ParserOuterClass.Response> responseObserver) {
+        String content = request.getContent().toStringUtf8();
+        String[] datas = content.split(separator);
+        List<String> responseList = new ArrayList<>();
+        
+        for (String data : datas) {
+            try {
+                String[] split = data.split(indexSeparator);
+                responseList.add(parseData(split[1]));
+            } catch (Exception e) {
+                responseList.add("{}");
+                e.printStackTrace();
+            }
+        }
+        String join = String.join(separator, responseList);
+        
+        ParserOuterClass.Response response = ParserOuterClass.Response.newBuilder().setContent(ByteString.copyFrom(join.getBytes())).build();
+        responseObserver.onNext(response);
+        responseObserver.onCompleted();
+    }
+
+    public static void main(String[] args) throws InterruptedException {
+        int availablePort = RandomUtils.nextInt(10000, 12000);
+        Server server = null;
+        for (int i = availablePort; i < 60000; i++) {
+            try {
+                server = ServerBuilder.forPort(i)
+                        .maxInboundMessageSize(100 * 1024 * 1024)
+                        .addService(new Demo())
+                        .build()
+                        .start();
+                break;
+            } catch (IOException e) {
+                // Port unavailable, try the next one
+            }
+        }
+        assert server != null;
+        // ‼️重要：此行输出信息供logbus获取，格式不能变动
+        System.out.println("1|1|tcp|127.0.0.1:" + server.getPort() + "|grpc");
+        server.awaitTermination();
+    }
+}
+```
+
+### Python版本
+
+```python
+import random
+from concurrent import futures
+import socket
+import sys
+import json
+import grpc
+import parser_pb2
+import parser_pb2_grpc
+from grpc_health.v1.health import HealthServicer
+from grpc_health.v1 import health_pb2, health_pb2_grpc
+
+separator = ":ta:"
+index_separator = "|ta|"
+
+class ParserServicer(parser_pb2_grpc.ParserServicer):
+    def Parse(self, request, context):
+        data = request.content
+        result = parser_pb2.Response()
+        data_list = data.decode('utf-8').split(separator)
+        return_data_list = []
+        for data in data_list:
+            try:
+                raw_data_list = data.replace('\r\n', '').split(index_separator)
+                parse_data = json.loads(raw_data_list[1])
+                new_parse_data = {}
+                new_parse_data["properties"] = parse_data.copy()
+                new_parse_data["#account_id"] = parse_data["ACCOUNTID"]
+                new_parse_data["#distinct_id"] = parse_data["OSTYPE"]
+                new_parse_data["#type"] = "track"
+                new_parse_data["#ip"] = parse_data["IP"]
+                new_parse_data["#uuid"] = parse_data["UID"]
+                new_parse_data["#time"] = parse_data["LOGTM"]
+                new_parse_data["#event_name"] = "event_" + str(parse_data["CODE"])
+                return_data_list.append(json.dumps(new_parse_data))
+            except Exception as ve:
+                return_data_list.append('{}')
+        result.content = separator.join(return_data_list).encode('utf-8')
+        return result
+
+def serve():
+    health = HealthServicer()
+    health.set("plugin", health_pb2.HealthCheckResponse.ServingStatus.Value('SERVING'))
+    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10), options=[
+         ('grpc.max_send_message_length', 4 * 1024 * 1024),
+         ('grpc.max_receive_message_length', 4 * 1024 * 1024),
+    ])
+    parser_pb2_grpc.add_ParserServicer_to_server(ParserServicer(), server)
+    health_pb2_grpc.add_HealthServicer_to_server(health, server)
+    port = get_open_port_in_random_range()
+    server.add_insecure_port(f'127.0.0.1:{port}')
+    server.start()
+    try:
+        # ‼️重要：此行输出信息供logbus获取，格式不能变动
+        print(f'1|1|tcp|127.0.0.1:{port}|grpc')
+        sys.stdout.flush()
+        while True:
+            time.sleep(60*60*24)
+    except KeyboardInterrupt:
+        server.stop(0)
+
+if __name__ == '__main__':
+    serve()
+```
+
+## 三、本地gRPC调试
+
+创建本地调试 gRPC 客户端，服务端启动后再启动客户端发送消息。
+
+### Java客户端
+
+```java
+public class ProtoClient {
+    private static final String indexSeparator = "|ta|";
+
+    public static void main(String[] args) {
+        String event = "{\"#type\":\"track\",\"#time\":\"2023-09-05 18:58:17.021\",\"#event_name\":\"test\",\"#account_id\":\"test\",\"properties\":{\"#lib\":\"tga_python_sdk\"}}";
+
+        ManagedChannel channel = ManagedChannelBuilder.forAddress("127.0.0.1", 12345)
+                .usePlaintext()
+                .build();
+        ParserGrpc.ParserBlockingStub stub = ParserGrpc.newBlockingStub(channel);
+        ParserOuterClass.Request request = ParserOuterClass.Request.newBuilder()
+                .setContent(ByteString.copyFrom(("ta.log"+ indexSeparator + event).getBytes()))
+                .build();
+
+        try {
+            ParserOuterClass.Response response = stub.parse(request);
+            System.out.println("Server Response: " + response.getContent().toStringUtf8());
+        } catch (Exception e) {
+            e.printStackTrace();
+        } finally {
+            channel.shutdown();
+        }
+    }
+}
+```
+
+### Python客户端
+
+```python
+import grpc
+import parser_pb2
+import parser_pb2_grpc
+
+def send_grpc_request():
+    channel = grpc.insecure_channel('127.0.0.1:12345')
+    stub = parser_pb2_grpc.ParserStub(channel)
+    event = '{"#type":"track","#time":"2023-09-04 16:46:06.055","#event_name":"test","#distinct_id":"test"}'
+    request = parser_pb2.Request(content=f'1.log|ta|{event}'.encode('utf-8'))
+    response = stub.Parse(request)
+    print("Response received:", response.content)
+
+if __name__ == '__main__':
+    send_grpc_request()
+```
+
+## 四、配置
+
+### Logbus2配置文件
+
+```json
+{
+  "datasource": [
+    {
+      "file_patterns": ["/path/server_log/*log"],
+      "app_id": "debug-appid",
+      "parser": {
+        "cmd": "java -jar /path/lib/xxx.jar",
+        "depend_sh": "true",
+        "separator": ":ta:",
+        "hand_shake": {
+          "protocol_version": 1,
+          "magic_cookie_key": "LogBus",
+          "magic_cookie_value": "v2"
+        }
+      }
+    }
+  ],
+  "push_url": "http://push_url"
+}
+```
+
+> 注：注释部分启动前要去除
+
+## 五、FAQ
+
+1. **启动时报错：Unrecongnized remote plugin message......latest protocol**
+
+原因：程序使用的proto生成文件非最新，Logbus客户端校验失败
+
+解决：参考准备工作部分，重新根据proto文件生成java类或python文件
+
+2. **日志中报错：Parser return data is invalid: length is changed**
+
+原因：目前版本Logbus2转译插件会校验数据转译前后条数是否相同，如果不同会导致校验失败
+
+解决：确认转译前后数据条数是否相同，如果需要一转多功能，请使用parser.batch_separator进行数据拼接
+
+3. **Logbus日志中报错：rpc error: code = Canceled desc = stream terminated by RST_STREAM with error code: CANCEL**
+
+同时Java程序报错：io.grpc.StatusRuntimeException: RESOURCE_EXHAUSTED: gRPC message exceeds maximum size
+
+原因：转译程序设置的传输数据字节数过小，导致logbus和Java转移程序RPC通信传输数据失败
+
+解决：增加程序中的最大传输字节数，Java设置：maxInboundMessageSize(100*1024*1024)
+
+4. **启动时报错：plugin [parser] start failed: fork/exec /bin/sh: bad file descriptor**
+
+原因：由于插件编译器兼容性问题当前无法在mac环境运行
+
+解决：需在linux / windows环境运行