日志中心实践-日志模型设计

此数据模型定义了独立日志记录是什么，需要记录、传输、存储和解释那些数据。

1 设计思路

数据模型的设计满足以下要求:

（1）应该能够明确地将现有日志格式映射到此数据模型。理想情况下将日志数据从任意日志格式转换到此数据模型，然后再转换回来，应该得到相同的数据。

（2）数据模型必须保留现有日志格式的特定元素的语义，其他日志格式到此数据模型的映射应该在语义上有意义。

（3）将日志数据从任意日志格式A转换为此数据模型，然后从数据模型转换为另一种日志格式B，理想情况下，必须产生有意义的日志数据转换，其效果不差于将日志格式A合理地直接转换为日志格式B。

（4）在需要存储或传输数据的具体实现中有效地表示数据模型，主要关心效率的两个方面:序列化/反序列化的CPU使用量和序列化形式的空间需求。这是一个间接的需求，它受数据模型的具体表示而不是数据模型本身的影响。

数据模型旨在成功地表示3种类型的日志和事件:

（1）操作系统生成的日志和事件，我们无法控制它们——我们不能改变格式或影响包含的信息(除非数据是由我们可以修改的应用程序生成的)。系统格式的一个例子是Syslog。

（2）第三方应用程序。这些是由第三方应用程序生成的。我们可能对包含的信息有一定的控制，例如自定义格式。例如Apache日志文件。

（3）自身的应用程序。这些是开发的应用程序，可以在一定程度上控制如何生成日志和事件，以及在日志中包含哪些信息。如果需要，可能会修改应用程序的源代码。

此数据模型为日志记录定义了一个逻辑模型(与记录的物理格式和编码无关)。每条记录包含2种字段:

（1）具有特定类型和含义的命名顶级字段。

该字段需要对所有记录都是强制性的，如时间戳，TraceId等。

（2）map，可以包含不同类型的任意值。允许使用该字段的所有各方对数据有相同的解释。参见附录A中资源和属性字段的语义约定和示例。

2 具体设计

2.1 概述

字段名称	描述
Timestamp	事件发生时间	可能为空
ObservedTimestamp	事件被观测到的时间	必填
TraceId	Request trace id.	可选
SpanId	Request span id.	可选
TraceFlags	W3C trace flag.	可选
SeverityText	日志级别（如：info，error，warn等）	必填
SeverityNumber	日志级别，例如数字来代指日志级别	必填
Body	日志内容	必填
Resource	描述日志的源。来自同一事件源的多个事件可以在不同时间发生，并且它们都具有相同的Resource值	可选
InstrumentationScope	表示事件发生的所属领域，如logger name
Attributes	附加信息。	可选

2.2 字段详述

字段名称：Timestamp

类型：Timestamp, uint64 nanoseconds since Unix epoch.

描述：事件发生的时间。这个字段是可选的，如果源时间戳未知，它可能会丢失。

字段名称：ObservedTimestamp

类型: Timestamp, uint64 nanoseconds since Unix epoch.

描述：采集时间。

字段名称：TraceId

类型：byte sequence.

描述：在W3C跟踪上下文中定义的请求跟踪id（调用链）。可以为作为请求处理的一部分并具有指定跟踪id的日志设置。该字段可选。

字段名称：SpanId

类型：byte sequence.

描述：在W3C跟踪上下文中定义的spanid（调用链）。该字段可选。

字段名称：TraceFlags

类型：byte.

描述：W3C跟踪上下文规范中定义的跟踪标志。在编写规范时定义了一个标志——SAMPLED标志,表示trace是不是被采样了。该字段可选。

字段名称：SeverityText

类型：string

描述：日志级别，这是严重程度的原始字符串表示形式，因为它在源代码中是已知的。如果该字段缺失且存在SeverityNumber，则可以使用与SeverityNumber对应的短名称[1]作为替代。该字段可选。

字段名称：SeverityNumber

类型：num

描述：日志级别的数值，标准化为本文档中描述的值。该字段可选。

SeverityNumber为整数。较小的数值对应较不严重的事件(如调试事件)，较大的数值对应较严重的事件(如错误和关键事件)。SeverityNumber值含义如下表所示:

数字范围	范围名称	含义
1-4	TRACE	细粒度调试事件。通常在默认配置中禁用。
5-8	DEBUG	一个debugging事件.
9-12	INFO	指代一个信息事件的发生，表示一个一般情况的发生。
13-16	WARN	警告事件。不是错误，但可能比信息事件更重要。
17-20	ERROR	错误事件
21-24	FATAL	致命错误，如应用程序或系统崩溃。

在每个范围中，数值越小，事件就越不重要(不那么严重)。每个范围的数值越大，表示事件越重要(越严重)。例如，SeverityNumber=17描述的错误比SeverityNumber=20的错误更严重。

字段名称：Body

类型：any

包含日志记录主体的值(请参阅上面任何类型的描述)。例如，可以是可读的字符串消息(包括多行)，以自由形式描述事件，也可以是由数组和其他值的映射组成的结构化数据。应用程序应该使用字符串消息。但是，应该使用结构化主体来保存第三方应用程序发出的结构化日志的语义。来自同一来源的事件的每次发生都可能有所不同。该字段可选。

字段名称：Resource

类型：map

描述日志的源。来自同一事件源的多个事件可以在不同时间发生，并且它们都具有相同的Resource值。例如，可以包含关于发出记录的应用程序的信息，或者关于运行应用程序的基础设施的信息。表示此数据模型的数据格式可以设计为允许Resource字段仅记录来自同一源的每批日志记录一次。该字段可选。参考resource的定义

字段名称：InstrumentationScope

类型：(Name,Version) tuple of strings.

表示事件发生的所属领域，如logger name

字段名称：Attributes

类型：map.

附加信息。不同于Resource字段(针对特定源是固定的)，Attributes可以根据来自同一源的事件的每次发生而变化。可以包含关于请求上下文的信息(除了TraceId/SpanId)。

附录：

[1] SeverityNumber对应的短名称

SeverityNumber	Short Name
1	TRACE
2	TRACE2
3	TRACE3
4	TRACE4
5	DEBUG
6	DEBUG2
7	DEBUG3
8	DEBUG4
9	INFO
10	INFO2
11	INFO3
12	INFO4
13	WARN
14	WARN2
15	WARN3
16	WARN4
17	ERROR
18	ERROR2
19	ERROR3
20	ERROR4
21	FATAL
22	FATAL2
23	FATAL3
24	FATAL4

参考：

[1] https://opentelemetry.io/docs/reference/specification/logs/data-model/

[2] https://www.bilibili.com/read/cv18609680?from=search&spm_id_from=333.337.0.0