{"id":28729787,"url":"https://github.com/didi/logbook","last_synced_at":"2025-06-15T17:11:03.194Z","repository":{"id":44897023,"uuid":"447135279","full_name":"didi/logbook","owner":"didi","description":null,"archived":false,"fork":false,"pushed_at":"2023-06-05T13:11:36.000Z","size":530,"stargazers_count":107,"open_issues_count":0,"forks_count":10,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-04-14T13:44:08.445Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/didi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-01-12T08:29:01.000Z","updated_at":"2024-03-31T14:25:32.000Z","dependencies_parsed_at":"2024-01-29T10:10:00.010Z","dependency_job_id":"ecef935c-f597-4e16-9a7e-a09d78b62e3d","html_url":"https://github.com/didi/logbook","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/didi/logbook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didi%2Flogbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didi%2Flogbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didi%2Flogbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didi%2Flogbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/didi","download_url":"https://codeload.github.com/didi/logbook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didi%2Flogbook/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260016055,"owners_count":22946321,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-15T17:11:01.558Z","updated_at":"2025-06-15T17:11:03.180Z","avatar_url":"https://github.com/didi.png","language":"Java","funding_links":[],"categories":["分布式跟踪"],"sub_categories":[],"readme":"# logbook 简介\nlogbook 是一款面向 ToB 业务的服务端埋点方案\n\n![logbook架构简图](docs/system-structure-1.png)\n\n\n# 概念介绍\n\n#### 1. 业务系统\n支撑业务正常运转的软件系统体系，统称为业务系统。\n\n#### 2. 业务事件\n单个业务系统中发生的事件，叫业务事件。 \n业务事件可能影响到0个或多个实体。\n\n#### 3. 上报\n业务系统把自己感知到的业务事件提交给 logbook 的过程。\n\n#### 4. 准入\nlogbook 接收业务系统的业务事件，业务事件的格式和内容由业务系统和logbook双方共同约定。\n在 logbook 接收事件时、会对约定格式/内容做校验，校验的过程叫做准入。\n\n#### 5. 实体事件\n单一实体视角发生的事件，叫实体事件。 \n实体事件只涉及到单个实体，由业务事件加工后得到。\n\n#### 6. 翻译\nlogbook 把业务事件翻译成实体事件的过程。\n\n#### 7. 数据使用方\n需要使用实体事件作为输入，来支撑自身业务的系统。\n\n#### 8. 分发\nlogbook 把实体事件处理后发送给对应的数据使用方的过程。\n\n---\n\n\n# logbook 核心能力\n1. 定义了 业务事件-实体事件 的数据输出和转发规范\n2. 提供了 业务事件准入、翻译，实体事件过滤、分发的基础能力\n\n![logbook架构详图](docs/system-structure-2.png)\n\n\n# 实施标准\n\n### 1. 业务事件\n标准格式：\n- biz_event_type，Integer业务事件类型\n- biz_event_id，Long，业务事件id、是业务事件的唯一标识\n- biz_event_info，Json String，业务事件的上下文信息\n- biz_entity_info_before，Json String，业务事件影响到的实体、在事件发生前的实体信息\n- biz_entity_info_after，Json String，业务事件影响到的实体、在事件发生后的实体信息\n\n\n### 2. 实体事件\n标准格式：\n- entity_type，Integer，实体类型\n- entity_id\tString，实体id\n- entity_info_before_event，Json Object，实体在事件发生前的数据快照\n- entity_info_after_event，Json Object，实体在事件发生后的数据快照\n- event_type，Integer，事件类型\n- event_id，String，事件id\n- event_time，String，事件时间\n- event_report_caller，String，事件上报方\n- event_info，Json Object，实体事件相关的上下文信息\n\n### 3. 准入\n对业务事件的准入方案，目前支持 jsonSchema 校验，可扩展。\n\n### 4. 翻译\n将业务事件翻译为实体事件的方案，目前支持 groovy 翻译，可扩展。\n\n### 5. 过滤\n将实体事件分发给具体某个使用方前，可以进行简单的过滤，目前支持 groovy 过滤，可扩展。\n\n### 6. 消息队列\n业务事件翻译为实体事件后，会存入消息队列，目前支持 kafka 消息队列，暂不支持扩展。\n实体事件也是通过 kafka 分发给数据使用方，暂不支持扩展。\n\n---\n\n# 快速开始\n\n### 1. 阅读 api 接口\n文档位置：```docs/ApiDocs.md``\n\n### 2. 修改 yml配置\n修改 application.yml 配置文件，路径：```logbook-server/src/main/resources/application.yml```\n- 必须修改的是 spring.datasource 开头的数据库配置\n- 其他配置可以使用默认值，也可以视情况进行调整\n\n### 3. 修改数据库配置\nlogbook 内部需要用到 12 张表，其中：\n- 配置侧需要 10 张表，建表语句路径：```logbook-server/sql/config.sql```\n- 执行侧需要 2 张表，建表语句路径：```logbook-server/sql/run.sql```\n\n### 4. 添加 mysql 驱动\n- 可以通过 maven 引入\n```\n        \u003cdependency\u003e\n            \u003cgroupId\u003emysql\u003c/groupId\u003e\n            \u003cartifactId\u003emysql-connector-java\u003c/artifactId\u003e\n            \u003cversion\u003e${mysql-connector.version}\u003c/version\u003e\n        \u003c/dependency\u003e\n```\n\n### 5. 二次开发\nlogbook 没有提供默认的消息队列实现，需要使用方选型完成后进行二次开发。\n- 二次开发需要完成的逻辑统一收敛在：`logbook/logbook-server/src/main/java/com/didiglobal/mq/MQCustomizedUtil.java`\n- 代码注释里给出了 kafka-clients 2.8.1 的示例代码，如需使用需要在 pom 文件里添加相应的依赖：\n```\n        \u003cdependency\u003e\n            \u003cgroupId\u003eorg.apache.kafka\u003c/groupId\u003e\n            \u003cartifactId\u003ekafka-clients\u003c/artifactId\u003e\n            \u003cversion\u003e${kafka-client.version}\u003c/version\u003e\n        \u003c/dependency\u003e\n```\n\n### 6. demo\n- 部署好 kafka 环境\n- 创建好 demo 中用到的 4个 topic：inner_worksheet_events、inner_user_events、destinate_downstream1、destinate_downstream2\n- 修改 ```docs/logbookDemoSql.sql``` 中的 \"你的kafka地址\" 为真实的 kafka 地址\n- 执行修改后的 ```docs/logbookDemoSql.sql``` 将 demo 的配置侧数据写入到数据库\n- 执行 ```docs/ApiDemo.md``` 中的请求，进行 demo 测试\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdidi%2Flogbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdidi%2Flogbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdidi%2Flogbook/lists"}