logbook 简介

logbook 是一款面向 ToB 业务的服务端埋点方案

概念介绍

1. 业务系统

支撑业务正常运转的软件系统体系，统称为业务系统。

2. 业务事件

单个业务系统中发生的事件，叫业务事件。 业务事件可能影响到0个或多个实体。

3. 上报

业务系统把自己感知到的业务事件提交给 logbook 的过程。

4. 准入

logbook 接收业务系统的业务事件，业务事件的格式和内容由业务系统和logbook双方共同约定。 在 logbook 接收事件时、会对约定格式/内容做校验，校验的过程叫做准入。

5. 实体事件

单一实体视角发生的事件，叫实体事件。 实体事件只涉及到单个实体，由业务事件加工后得到。

6. 翻译

logbook 把业务事件翻译成实体事件的过程。

7. 数据使用方

需要使用实体事件作为输入，来支撑自身业务的系统。

8. 分发

logbook 把实体事件处理后发送给对应的数据使用方的过程。

---

logbook 核心能力

1. 定义了 业务事件-实体事件 的数据输出和转发规范
2. 提供了 业务事件准入、翻译，实体事件过滤、分发的基础能力

实施标准

1. 业务事件

标准格式：

• biz_event_type，Integer业务事件类型
• biz_event_id，Long，业务事件id、是业务事件的唯一标识
• biz_event_info，Json String，业务事件的上下文信息
• biz_entity_info_before，Json String，业务事件影响到的实体、在事件发生前的实体信息
• biz_entity_info_after，Json String，业务事件影响到的实体、在事件发生后的实体信息

2. 实体事件

标准格式：

• entity_type，Integer，实体类型
• entity_id String，实体id
• entity_info_before_event，Json Object，实体在事件发生前的数据快照
• entity_info_after_event，Json Object，实体在事件发生后的数据快照
• event_type，Integer，事件类型
• event_id，String，事件id
• event_time，String，事件时间
• event_report_caller，String，事件上报方
• event_info，Json Object，实体事件相关的上下文信息

3. 准入

对业务事件的准入方案，目前支持 jsonSchema 校验，可扩展。

4. 翻译

将业务事件翻译为实体事件的方案，目前支持 groovy 翻译，可扩展。

5. 过滤

将实体事件分发给具体某个使用方前，可以进行简单的过滤，目前支持 groovy 过滤，可扩展。

6. 消息队列

业务事件翻译为实体事件后，会存入消息队列，目前支持 kafka 消息队列，暂不支持扩展。 实体事件也是通过 kafka 分发给数据使用方，暂不支持扩展。

---

快速开始

1. 阅读 api 接口

文档位置：```docs/ApiDocs.md``

2. 修改 yml配置

修改 application.yml 配置文件，路径：logbook-server/src/main/resources/application.yml

• 必须修改的是 spring.datasource 开头的数据库配置
• 其他配置可以使用默认值，也可以视情况进行调整

3. 修改数据库配置

logbook 内部需要用到 12 张表，其中：

• 配置侧需要 10 张表，建表语句路径：logbook-server/sql/config.sql
• 执行侧需要 2 张表，建表语句路径：logbook-server/sql/run.sql

4. 添加 mysql 驱动

• 可以通过 maven 引入

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>${mysql-connector.version}</version>
        </dependency>

5. 二次开发

logbook 没有提供默认的消息队列实现，需要使用方选型完成后进行二次开发。

• 二次开发需要完成的逻辑统一收敛在：logbook/logbook-server/src/main/java/com/didiglobal/mq/MQCustomizedUtil.java
• 代码注释里给出了 kafka-clients 2.8.1 的示例代码，如需使用需要在 pom 文件里添加相应的依赖：

        <dependency>
            <groupId>org.apache.kafka</groupId>
            <artifactId>kafka-clients</artifactId>
            <version>${kafka-client.version}</version>
        </dependency>

6. demo

• 部署好 kafka 环境
• 创建好 demo 中用到的 4个 topic：inner_worksheet_events、inner_user_events、destinate_downstream1、destinate_downstream2
• 修改 docs/logbookDemoSql.sql 中的 "你的kafka地址" 为真实的 kafka 地址
• 执行修改后的 docs/logbookDemoSql.sql 将 demo 的配置侧数据写入到数据库
• 执行 docs/ApiDemo.md 中的请求，进行 demo 测试