平台设计——系统日志设计方案(一)(日志事件模型字段枚举)

本文主要讲解日志中心的整体架构、基本概念，以及如何使用日志中心进行写日志、查日志的操作。

日志中心以记录日志为核心功能，涵盖了日志配置、日志查询权限、日志写入等，实现了用户、组织之间的日志查询隔离，将日志记录的过程规范化、标准化。

日志中心后端业务主要涉及到MySQL、ElasticSearch、RocketMQ的使用。
其中，MySQL负责存储日志的配置信息，如日志项的格式、权限等；日志项的具体内容存储在ElasticSearch中；RocketMQ负责异步发送业务方的日志写入请求，起到解耦、削峰等作用。

日志中心的前端主要用于日志的配置和日志查询。
在前端，用户可以设计自己的日志格式，并与同组织下的其他用户进行分享，这些信息将存储在MySQL中。
同时，用户可以在前端对自己已经写入的日志项进行查询。

日志中心对外暴露SDK模块，需要使用日志中心的业务方，在前端注册好自己的日志格式后，调用SDK提供的Client即可进行日志写入。

该部分主要讲解日志中心配置过程中涉及到的概念。

资源是日志中心下的一个分组概念，其余所有元素都必须属于某个资源，不可单独存在。
用户可以根据自己的业务、应用等创建自己的资源，然后在该资源下创建其他元素。

事件是同一类日志项的集合，用户可以根据自己业务中的一个动作建立一个事件，当执行对应动作时，在事件下记录对应的日志项。

可以说，一个事件相当于一类日志项的模板。

模型规定了日志项的具体格式，

模型创建后即拥有系统内置字段，用来存放日志项的基础信息。
除此之外，还可以给模型添加自定义字段，以此规定用户自己模块的日志格式，从而可以根据用户需求定义日志项。

同时，模型可以被复用，以达到不同日志类型便捷使用不同字段的要求。

事件和模型的主要作用是对日志项进行格式上的约束，它们二者是紧密关联的。
用户可以创建一些模型，给这些模型各自添加字段，然后用这些模型组成一个事件，从而使事件拥有这些模型的字段。
事件和模型的关联关系可以自由变动，一个事件可以通过多个模型组装，这些模型上的字段规定了该事件下日志项的具体格式。
同时，一个事件可以绑定和解绑模型，以满足用户需要更改一类日志项格式的需求。

如果一个事件没有绑定任何模型，那这个事件将只拥有默认的系统字段。

一个模型也可以不设置任何自定义字段，将其预留为空模型。
模型的字段可以任意添加，一旦添加后就不可修改。

事件和模型都属于资源下的元素，每个事件和模型都必须依托于某个资源存在。
事件只能和同一资源下的模型建立关联，模型也只能被同一资源下的复用。

(三)数据模型1.数据库设计

日志中心的配置信息使用MySQL进行存储，日志内容使用ElasticSearch进行存储。

MySQL部分共计7张表，其中共4张主表，3张关联表。
4张主表分别为：资源信息表、日志事件信息表、数据模型信息表、模型配置信息表。

资源信息表对应资源的基础信息，其中有资源id、资源类型、资源编码、资源名称。

日志事件信息表对应事件的基础信息，其中有事件id、事件形态、事件名称、事件编码、事件来源、事件描述、事件性质。

数据模型信息表对应模型的基础信息，其中有模型id、模型编码、模型名称、模型描述。

模型配置信息对应模型的字段基础信息，其中有字段名称、字段编码、字段描述、字段类型、字段默认值、系统字段标记。

三张关联表负责关联资源、事件、模型。

MySQL的ER图如下图所示：

注：目前的关联表中，只有事件模型关联表中的启用状态可以自行设置开启关闭，其余两张关联表的启用状态无法修改

注：目前的关联表中，只有事件模型关联表中的启用状态可以自行设置开启关闭，其余两张关联表的启用状态无法修改

在ElasticSearch中，并不会提前创建Index或者Mapping，当事件被创建后，会根据事件编码在ElasticSearch中创建对应Index，并为其提供一个只包含系统字段的Mapping。
当建立事件与模型的关联关系后，再将模型上的字段作为增量补充到Mapping中去。

该部分解释日志中心除数据库PO类之外的其他重要类，如日志写入类、日志查询结果类、枚举类等

日志写入类中的属性分为两部分：系统字段和自定义字段。

系统字段包括模块code、业务类型、事件code、事件结果、操作人员编号、时间戳，共计6个字段，其中只有时间戳无需用户手动指定。

自定义字段对应事件绑定的模型中用户自行添加的字段，为了保证可扩展性，自定义字段需要使用Map的方式进行传入。

日志写入类的类图如下：

2.2 日志查询结果类

日志查询信息主要分为6部分：appCode、bizCode、操作人用户信息、日志事件信息、所属资源信息、自定义字段信息。

日志具体内容存储在ElasticSearch中，其中只有一些简单的基础信息，用户在查询时，服务端首先会将日志内容从ElasticSearch中查出，再根据其中的基础信息，到MySQL中查询详细信息，最终组装为一个结果类进行返回。

日志查询结果类的类图如下：

2.3 枚举类

日志中心目前针对一些可选值制定了枚举类，枚举类包含三个属性：枚举码code、枚举值value、枚举描述desc。

日志中心目前共计6个枚举类，它们的详细信息如下：

枚举

枚举码

枚举值

枚举描述

SENSITIVE

0

sensitive

敏感

INSENSITIVE

1

insensitive

非敏感（应用）

2.事件来源枚举类

枚举

枚举码

枚举值

枚举描述

CONSOLE

0

console

控制台

API

1

api

API

3.事件形态枚举类

枚举

枚举码

枚举值

枚举描述

READONLY

0

readOnly

只读

WRITEONLY

1

writeOnly

只写

4.字段类型枚举类

枚举

枚举码

枚举值

枚举描述

TEXT

0

text

文本

INTEGER

1

integer

数字

DATETIME

2

datetime

时间

BOOLEAN

3

boolean

布尔型

5.资源类型枚举类

枚举

枚举码

枚举值

枚举描述

MODULE

0

module

模块

APP

1

application

应用

进入日志中心后，默认进入资源管理页面，会显示当前用户有权限看到的资源列表，如下图所示：

如果要新增资源，点击右上角的新增按钮，右侧会弹出新增资源窗口，输入可配置的资源信息

点击右下角确定，若提示“保存成功”，即表示资源注册成功

可以在资源列表中看到新增的资源

1.2 资源查询

在资源管理页面，可根据“资源编码”、“资源名称”、“资源类型”三个条件对资源列表进行模糊查找。
如果查询条件留空，则默认查找所有资源。

下图表示筛选资源类型为“模块”的资源，输入好查询条件后，点击右侧查询即可进行筛选

1.3 资源修改

如果在新增时资源信息填写有误，或者在后续使用过程中需要修改资源信息，可进入资源管理页面，点击需要修改的资源项右侧的编辑按钮，会弹出资源修改页面。
目前仅允许修改资源名称和资源类型

信息填写完毕后，点击右下角的确定，提示“保存成功”即为修改完成

可以在资源管理页面看到修改之后的资源信息

2.事件注册与管理2.1 事件注册

事件必须从属于某个资源，因此注册事件时，需要先选择资源，未选择资源时无法注册事件。

事件编码需要符合规定：必须以小写字母开头，且内容只能为小写字母、数字、下划线

注：在绑定模型处可以设置此新增事件与同资源下模型的关联关系

如果事件编码不符合规定，会有相关提示：

2.2 事件查询

事件可以通过事件编码、事件名称模糊查询。
若为选中资源，则查询所有有权限的事件，若选中资源，则查询该资源下所有有权限的事件。

2.3 事件编辑

点击事件后的编辑可以对事件进行修改，其中事件编码无法修改。
但是可以在此处修改同资源下模型的关联关系。

3.模型注册与管理3.1 模型注册

模型注册与事件注册相似，需要选中资源后才能注册，其中模型编码只能小写字母加下划线，必须以小写字母开头，以便格式统一。

3.2 模型查询

模型查询与事件查询类似，可以通过模型编码和模型名称模糊查询，也可在资源下查询有权限的模型列表。

3.3 模型编辑

点击选中模型的编辑按钮，可以对模型基础信息进行修改。
同样地，模型编码不能改变。

3.4 添加或删除模型配置字段

切换到模型的模型配置页面，可以查看模型上添加的字段，其中系统内内置字段不可编辑。
在此处可以给模型绑定或移除自定义字段。

3.5 自定义字段配置

点击新增按钮，配置自定义字段后可以添加到模型上。
可以给模型逐个添加自定义配置字段，其中字段编码规则会在前端自动添加模型编码作为前缀，以此确保字段的唯一性。
填写的编码规则和模型的编码规则类似。
字段的类型目前有四种，分别为text、integer、boolean以及datetime。
在创建字段时，可以填写默认值，若后续写入日志时未传值，则会自动填写默认值。

注意，如果一个字段被移除后又新增了一个和此字段的字段编码一样的字段，字段类型需要保持一致，否则无法添加。

在事件新建及编辑处，可以设置此事件与同资源下模型的关联关系。
点击编辑事件时，以及启用的模型关联关系会自动带出。
选择模型时，最终出现在右框的为启用的关系。
一个事件和关联的任一模型禁用关联关系后，日志项中不会出现此模型下的字段。

5.权限配置

通过平台权限管理中的的管理对象来进行日志权限控制。

在管理对象中会注册 日志资源，日志事件，日志模型 三个管理对象，对应日志权限控制的三个维度。

如果要写入日志，在需要写日志的模块中引入udp-log-sdk模块即可，可以在maven和gradle对应的文件中进行引入。

udp-log-sdk中，用户需要关注的只有两个类：OperatorLogClient和LogWriteRequest

1. OperatorClient中提供了用户写入日志的方法

2. LogWriteRequest中规定了用户写入日志时，需要手动设定的字段，共计7个字段：模块编码appCode、业务类型bizCode、事件编码eventCode、操作人员编号operatorUserNo、时间戳timeStamp、自定义字段customFields。
其中，前5个字段为必填，即用户在写入日志时，必须手动指定appCode、bizCode、eventCode、operatorUserNo

下面以udp-basedata的查询用户接口为例，具体介绍如何使用：

注：请确保填入的eventCode已有对应的配置

如果有自定义字段需要填写，就新建一个Map进行填入

补充：API的使用

如果是测试阶段，可以不使用Client类，直接使用Http请求访问日志写入接口。
下面是接口文档：

以localhost为例：POST http://localhost:8080/udp-log/logging

无需指定User-Token

请求参数以json格式放在Body中：

请求参数

类型

参数名

是否必填

默认值

备注

logWriteRequest

Object

日志写入请求类

是

appCode

String

模块code

是

bizCode

String

业务类型

是

eventCode

String

事件code

是

需要事先注册事件

eventResult

String

事件执行结果

是

自定义，可以是响应码、字符串等

operatorUserNo

String

操作人员编号

是

userNo是主数据ID，不是用户id

customFields

Map

自定义字段

否

null

如果事件有绑定模型，可以用这个参数来制定自定义字段的值

响应数据封装在ApiResult中进行返回，其中的data为String类型，表示日志写入API是否调用成功

注：日志写入API使用的是RocketMQ异步消息发送，暂时无法同步得到消息发送结果

参数

类型

参数名

备注

code

int

响应码

message

String

响应消息

data

String

异步写入API调用结果

使用例

一个调用例子如下：

(三)日志的查询1.日志列表查询

点击左侧的日志操作标签，进入到日志查询页面。
默认显示当前用户有权限看到的所有日志项

目前支持按照日志写入、事件来源、事件形态、事件性质、事件编码、资源编码、操作人编码进行筛选

选中日志项，点击右侧详情后可以查看日志的详细信息，其中app编码、业务编码以及自定义字段部分以json形式显示。

注：如果写入时UserNo不存在，那么查询日志时无法获取到对应用户信息，将以未知信息进行代替，如下图所示