logz

1. 简介

logz是通用日志记录器，符合NETSTARS日志规范要求，默认支持NETSTARS 日志规范 v1.3。在1.3版本规范下，logz以JSON格式输出日志信息，示例如下：

{"compliance":"1.3","log_app_id":"test_app_id","log_app_version":"0.1","log_category":"srv-exception-log","log_event_id":"","log_event_time":"2022-01-21T10:53:21.774+09:00","log_level":"fatal","log_time":"2022-01-21T10:53:21.774+09:00","message":"this is a test message"}

JSON格式日志信息可以嵌套JSON，键值内容里换行符以及双引号会被自动转义。示例如下：

{"Company":{"Address":"茅場町","Name":"NSS"},"Person":"{\n  \"Name\": \"Alice\",\n  \"Age\": 23\n}","compliance":"1.3","log_app_id":"test_app_id","log_app_version":"0.1","log_category":"srv-biz-process-log","log_event_id":"a1b2c3","log_event_time":"2022-01-22T10:53:21.775+09:00","log_level":"info","log_time":"2022-01-21T10:53:21.775+09:00","message":"this is a test message"}

在开发调试阶段，也可以设置规范级别为0，输出简单的以分号分隔的日志信息：

2022-01-21T10:56:43.901+09:00 [INF] item_1: 23; log_event_time: 2022-01-21T10:56:43.901+09:00; message: this is a test message

注意： 规范v1.3符合SLA要求，可以被Elasticsearch解析；规范0仅可用于开发测试阶段。

2. 日志级别

logz日志级别是整数，符合日志规范v1.3的定义。取值范围[0,6]，0是不输出任何日志，1-6分别对应fatal, error, warn, info, debug, trace。数值越大则输出信息越丰富。在logz.Init()初始化方法里可以指定最大输出的日志级别，控制输出信息的详细程度。也可以通过logz.SetMaxLevel()方法动态调整最大日志输出级别。

3. 使用方法

完整使用示例

package main

import (
	"time"
	"github.com/0xNetx/logz"
)

func main() {
	// 初始化日志
	logz.Init(logz.DebugLvl, "my_app", "1.0.0", "1.3") // 设置为调试级别以显示所有日志

	// 简单日志输出
	logz.Errorf("用户登录失败: %s", "密码错误")

	// 自定义日志项
	logz.Log(logz.InfoLvl, "用户操作",
		logz.CustomItem("user_id", "12345"),
		logz.CustomItem("action", "login"),
		logz.EventTime(time.Now()))

	// 使用Loggerz对象
	logger := logz.New(
		logz.CustomItem("service", "user-service"),
		logz.CustomItem("version", "1.0.0"),
	)
	logger.Printf("处理用户请求: %s", "GET /api/users")
}

输出结果

运行上述代码会输出以下JSON格式的日志：

{"compliance":"1.3","log_app_id":"my_app","log_app_version":"1.0.0","log_category":"srv-exception-log","log_event_id":"","log_event_time":"2025-10-22T19:58:30.785+08:00","log_level":"error","log_time":"2025-10-22T19:58:30.785+08:00","message":"用户登录失败: 密码错误"}
{"compliance":"1.3","log_app_id":"my_app","log_app_version":"1.0.0","log_category":"srv-biz-process-log","log_event_id":"","log_event_time":"2025-10-22T19:58:30.785+08:00","log_level":"info","log_time":"2025-10-22T19:58:30.785+08:00","message":"用户操作","user_id":"12345","action":"login"}
{"compliance":"1.3","log_app_id":"my_app","log_app_version":"1.0.0","log_category":"srv-biz-process-log","log_event_id":"","log_event_time":"2025-10-22T19:58:30.785+08:00","log_level":"info","log_time":"2025-10-22T19:58:30.785+08:00","message":"处理用户请求: GET /api/users","service":"user-service","version":"1.0.0"}

详细说明

• 初始化。在程序启动时调用logz.Init()方法，设置输出的最大日志级别。通常这个方法在main()函数里调用，各个参数的值可以通过应用程序的配置文件来提供。

  • logz.DebugLvl：设置日志级别为调试级别，会输出所有级别的日志
  • "my_app"：应用程序ID
  • "1.0.0"：应用程序版本号
  • "1.3"：日志规范版本号，如果指定"0"则输出简单信息，建议只在调试阶段使用

• 简单日志输出。可以使用logz.Printf(), logz.Errorf()等方法输出简单日志信息：

logz.Errorf("用户登录失败: %s", "密码错误")

• 自定义日志项。使用logz.Log()和logz.CustomItem()方法，可以实现最大灵活度的日志信息定制输出：

logz.Log(logz.InfoLvl, "用户操作",
	logz.CustomItem("user_id", "12345"),
	logz.CustomItem("action", "login"),
	logz.EventTime(time.Now()))

• 使用Loggerz对象。使用logz.New()方法可以创建新的Loggerz对象，保存一些通用的日志信息，从而不必在每次调用时都手工传递这些信息：

logger := logz.New(
	logz.CustomItem("service", "user-service"),
	logz.CustomItem("version", "1.0.0"),
)
logger.Printf("处理用户请求: %s", "GET /api/users")

4. 项目引用方法

使用go get命令（推荐）

go get github.com/0xNetx/logz@v0.0.1

手动添加到go.mod

在要使用logz的项目的 go.mod 文件中添加：

require github.com/0xNetx/logz v0.0.1

实际生成的go.mod和go.sum示例

使用go get github.com/0xNetx/logz@v0.0.1命令后，会自动生成类似以下的内容：

go.mod:

module your-project-name

go 1.25.1

require github.com/0xNetx/logz v0.0.1

go.sum:

github.com/0xNetx/logz v0.0.1 h1:y+PEOYErqOnDCpGGAAxc6FwSJLw7PB5LNOrTjGIiRHM=
github.com/0xNetx/logz v0.0.1/go.mod h1:siMQ17Hpw/t7u9O/gVODyFYRRpQNhUlS5TewA0Cjsbs=

版本说明

• v0.0.1: 初始发布版本，包含完整的日志格式化功能
• 支持NETSTARS v1.3规范JSON格式输出
• 支持简单文本格式输出（规范0）
• 包含Hook机制和Loggerz对象功能

注意： 使用语义化版本号（如v0.0.1）比pseudo-version更清晰，建议在项目中始终使用具体的版本号。