抢先体验仅限邀请,SDK 尚未发布。申请邀请
跳到正文
文档

Go

从你的 Go 服务发送结构化日志,自带 log/slog handler。只依赖标准库。

服务器,提供 slog handler

模块是 go.lyrelog.com/lyrelog。需要 Go 1.24 或更高版本,没有任何依赖。

内部预览:这个包尚未发布。在发布之前,go get go.lyrelog.com/lyrelog 会失败,因为仓库是私有的,也还没有任何发布版本。

安装

go get go.lyrelog.com/lyrelog

开始使用

import "go.lyrelog.com/lyrelog"

client, err := lyrelog.New(lyrelog.Config{
	APIKey:   "lyr_srv_...", // a server key, or read it from your own config
	Platform: "api",
})
if err != nil {
	log.Fatal(err) // only for a bad config: logging itself never fails
}
defer client.Close() // sends what is left (waits at most 5 s)

使用服务器密钥 lyr_srv_...,在项目的 API keys 页面(Send events from a server)创建。它是机密:放在服务器的环境变量中,绝不能放进应用或网页。它发送的事件是已验证的,而且不受单个地址每日配额的限制。采集密钥 lyr_ing_... 也能用,但它发送的事件不是已验证的。

只有 APIKey 是必填的:没有它,New 会返回一个错误和一个 nil 客户端。nil 的 *Client 什么都不做,所以在客户端创建之前(或者根本没有客户端时)代码也可以照常记录日志。Endpoint 默认为 https://ingest.lyrelog.com;它是基础 URL,粘贴的 /v1/events:batch 路径会被去掉。

log.Fatal 和 os.Exit 会跳过 defer 的调用,所以在它们之后 defer client.Close() 永远不会执行。在 main 中,把实际工作放进一个返回退出码的函数:

func main() { os.Exit(run()) }

func run() int {
	client, err := lyrelog.New(lyrelog.Config{APIKey: os.Getenv("LYRELOG_KEY")})
	if err != nil {
		fmt.Fprintln(os.Stderr, err) // client is nil and does nothing: carry on without it
	}
	defer client.Close() // runs before os.Exit
	// ...
	return 0
}

在 serverless 函数(AWS Lambda)中,请在 handler 返回前调用 client.Flush(ctx):运行时可能在下一次发送之前就冻结进程。

记录事件

每个级别一个方法:Trace、Debug、Info、Notice、Warning、Error、Critical,或者 Log(level, message, ...)。细节通过选项传入:lyrelog.Category、lyrelog.Attrs、lyrelog.Payload 和 lyrelog.User。

client.Info("checkout_done", lyrelog.Attrs{"plan": "pro", "latency_ms": 412})
client.Error("payment_failed",
	lyrelog.Category("billing"),
	lyrelog.Attrs{"code": "card_declined"},
	lyrelog.Payload(map[string]any{"response": body}),
)

属性可以是字符串、数字、布尔值、nil、字符串切片和嵌套的 map(最多 4 层)。名称中的点会被改写为 _。多个 Attrs 选项会合并,键重复时以后面的为准。Payload 用 encoding/json 编码:如果字节本身已经是 JSON,请传 json.RawMessage(普通的 []byte 到达时会是 base64 字符串)。

按分类划分的 logger

billing := client.Logger("billing")
billing.Warning("invoice_retry", lyrelog.Attrs{"attempt": 2})

用户

client.SetUser("u_123") // attached to every following event
client.SetUser("")      // clear it

服务器同时处理很多用户的请求:请用 lyrelog.User(id) 在每个事件上设置用户,它会在该事件上替换 SetUser 设置的用户。

slog handler

把 log/slog 记录发送到 Lyrelog:

logger := slog.New(lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}))
logger.Info("order_shipped", "order_id", id, "category", "fulfillment")
  • 记录的消息就是事件的消息,记录的时间就是事件的时间;属性和分组会变成嵌套属性。
  • 顶层的 category 字符串属性用来设置分类(不会作为属性发送);没有它时,使用 handler 的 Category。
  • 级别:Debug-4 及以下是 trace,Debug 是 debug,Info 是 info,介于 Info 和 Warn 之间的是 notice,Warn 是 warning,Error 是 error,Error+4 及以上是 critical。
  • SlogOptions.Level 在客户端的最低级别之上再加一道最低级别;AddSource 会添加一个 source 属性,包含调用方的函数、文件和行号。请用 go build -trimpath 构建,这样文件路径是模块路径,而不是构建机器上的目录。

如果还想继续在终端输出,就把每条记录同时发给两个 handler。在 Go 1.26 及以上版本中,slog.NewMultiHandler 可以做到:

logger := slog.New(slog.NewMultiHandler(
	slog.NewTextHandler(os.Stderr, nil),
	lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}),
))
slog.SetDefault(logger)

net/http 中间件

SDK 没有内置中间件。下面这个中间件把每个请求记录为 http 分类下的 http_request_served:正常为 info,4xx 为 warning,5xx 为 error;记录的是路由模式而不是路径,这样 id 就不会让基数暴涨:

func logRequests(client *lyrelog.Client, next http.Handler) http.Handler {
	httpLog := client.Logger("http")
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()
		recorder := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
		next.ServeHTTP(recorder, r)
		level := lyrelog.LevelInfo
		switch {
		case recorder.status >= 500:
			level = lyrelog.LevelError
		case recorder.status >= 400:
			level = lyrelog.LevelWarning
		}
		httpLog.Log(level, "http_request_served", lyrelog.Attrs{
			"method":      r.Method,
			"route":       r.Pattern, // set by http.ServeMux (Go 1.23+), e.g. "GET /users/{id}"
			"status":      recorder.status,
			"duration_ms": time.Since(start).Milliseconds(),
		})
	})
}

type statusRecorder struct {
	http.ResponseWriter
	status int
}

func (s *statusRecorder) WriteHeader(code int) {
	s.status = code
	s.ResponseWriter.WriteHeader(code)
}

// Unwrap lets http.ResponseController reach the original writer (Flush, deadlines).
func (s *statusRecorder) Unwrap() http.ResponseWriter { return s.ResponseWriter }

// http.ListenAndServe(":8080", logRequests(client, mux))

没有匹配到任何路由的请求,r.Pattern 为空。

错误

if err := charge(ctx, order); err != nil {
	client.CaptureError(err, lyrelog.Category("billing"), lyrelog.Attrs{"order_id": order.ID})
}

事件为 exception,级别 error,属性中带有 error_type 和 error_message,payload 中带有错误链(每一层被包装的错误)和堆栈。nil 错误不会记录任何内容。Logger.CaptureError 的作用相同,但使用该 logger 的分类。级别始终是 error:想用其他级别,请自己用 Log 记录这个错误。

panic

SDK 不会 recover panic。net/http 会 recover handler 中的 panic,但只是把它打印出来,所以请在中间件里记录,放在上面那个中间件的外层:

func recoverPanics(client *lyrelog.Client, next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			v := recover()
			if v == nil {
				return
			}
			if v == http.ErrAbortHandler {
				panic(v)
			}
			err, ok := v.(error)
			if !ok {
				err = fmt.Errorf("panic: %v", v)
			}
			client.CaptureError(err, lyrelog.Category("http"),
				lyrelog.Attrs{"handled": false, "mechanism": "panic", "route": r.Pattern})
			http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
		}()
		next.ServeHTTP(w, r)
	})
}

// http.ListenAndServe(":8080", recoverPanics(client, logRequests(client, mux)))

payload 中的堆栈是在 recover panic 的地方获取的,所以仍然包含发生 panic 的那些栈帧。你自己启动的 goroutine 中发生 panic,程序会在发送任何内容之前就崩溃:请用同样的方式在那个 goroutine 中 recover。

环境和平台

Environment 默认取环境变量 LYRELOG_ENVIRONMENT(转为小写),否则为 production。Platform 默认为 go。两者都可以在配置中设置:

client, err := lyrelog.New(lyrelog.Config{
	APIKey:      "lyr_srv_...",
	Environment: "staging",
	Platform:    "worker",
})

两者都只能包含小写字母、数字、- 和 _,最多 32 个字符,并以字母或数字开头。Config.Environment 或 Config.Platform 无效时,New 会返回错误;$LYRELOG_ENVIRONMENT 无效时,会报告给 ErrorLog 并替换为 production,所以部署时的拼写错误永远不会让服务停下来。Release 默认取构建信息中主模块的版本,AppID 默认取主模块的路径。

用户同意针对的是运行在用户设备上的应用。服务器 SDK 收到什么就发送什么。

立即发送(flush)和停止

err := client.Flush(ctx) // send what's queued now
client.Close()           // flush (up to CloseTimeout) and stop

Flush 发送调用之前已入队的所有事件,并等待发送完成或 ctx 结束。它返回:

  • 全部到达服务器时返回 nil;
  • context 先结束时返回 ctx.Err();
  • 收到 401 或 403 后返回 ErrUnauthorized(客户端停止发送,直到进程重启,队列保留);
  • 一个错误,说明某个批次被拒绝并丢弃(其余的仍已发送);
  • 一个错误,说明发送失败、将会重试,事件保留。在服务器要求的 Retry-After 期间,Flush 会立即返回这个错误,什么都不发送;
  • Close 之后返回 ErrClosed。

Close 最多等待 CloseTimeout 完成最后一次 flush,返回值相同;届时仍未发送的事件会被丢弃,并计入 Stats().Dropped。调用 Close 之后,日志调用不再起作用。

client.Stats() 返回 Queued(等待中,包括正在重试的批次)、Sent(服务器已接收)、Rejected(服务器拒收的行,永不重发)和 Dropped(被客户端丢弃:队列溢出、批次被拒绝,或在 Close 时还没发出)。

开发和测试

没有 APIKey 时,New 返回一个错误和一个 nil 客户端,而 nil 客户端什么都不做:同一份代码在测试中、在没有密钥的笔记本电脑上都能运行,就像上面的 run 示例那样。基于 nil 客户端的 slog handler 会丢弃所有记录。

想看测试记录了什么,可以传入一个 HTTPClient,用它的 Transport 记录请求;或者把 Endpoint 指向一个 httptest.Server(回环地址允许使用纯 http://)。

已验证事件

已验证事件是指不可能由从应用或网页中复制了公开采集密钥的人发出的事件。它能证明什么、不能证明什么,请看已验证事件。

用服务器密钥 lyr_srv_... 发送。它发出的每个事件都是已验证的(verified_by 为 server),并且不计入单个地址的每日配额。服务器密钥由所有者在项目的 API keys 页面,通过 Send events from a server 创建,需要近期登录过(10 分钟以内),而且只显示一次。它是机密:不要放进代码仓库,从服务器的环境变量或机密存储中读取。

client, err := lyrelog.New(lyrelog.Config{
	APIKey: os.Getenv("LYRELOG_KEY"), // lyr_srv_..., set in the server's environment
})

要检查,打开 explorer:在 Filter 中选择 Verified by 和 Server key(另外两个值是 App Attest 和 Not verified)。打开一个事件,在 Context 下的 Sender 一行会显示:Verified, server key 或 Not verified, public key。

用采集密钥 lyr_ing_... 或完全访问密钥 lyr_adm_... 发送的事件到达时是未验证的:任何持有公开密钥的人都可能发出同样的事件,而且这些事件计入每日配额。已验证事件证明的是谁发送了它,而不是它的内容属实。

谁验证什么,以及每日配额,请看已验证事件。

配置

字段默认值说明
Endpointhttps://ingest.lyrelog.com基础 URL;粘贴的 /v1/... 路径会被去掉。纯 http:// 仅限 localhost
APIKey必填项目的服务器密钥(lyr_srv_...)或采集密钥
Environment$LYRELOG_ENVIRONMENT,否则为 production任何有效名称
Platformgoapi、worker……
Release模块版本作为 resource.app_version 发送
AppID模块路径作为 resource.app_id 发送
MinimumLevelLevelDebug低于这个级别的事件在入队前就被丢弃
FlushInterval5 秒后台 goroutine 多久发送一次
MaxQueue10,000超出后丢弃最旧的,计入 Stats().Dropped
MaxQueueBytes16 MiB同一个上限,按字节计
CloseTimeout5 秒Close 等待最后一次 flush 的时长
HTTPClient30 秒超时发送批次的客户端。永远不跟随重定向,即使用的是你自己的客户端
ErrorLogstderr,只输出一次接收 SDK 自身的诊断信息,每条都以 lyrelog: 开头。不设置时,只有第一次密钥被拒绝或批次被丢弃,以及配额警告会打印到 stderr。不要把它指向一个会把日志再送进这个客户端的 logger

发送和限制

  • 由一个后台 goroutine 打包批次,每批最多 500 个事件或 512 KiB,gzip 压缩;批次满了立即发送。可以安全地并发使用。
  • 重试采用带完全抖动(full jitter)的退避(从 1 秒开始翻倍,最长 5 分钟),遵守 Retry-After(秒数或日期),重发相同的字节。其他任何 4xx 都会丢弃该批次;3xx 会丢弃该批次并记录一条警告。
  • 键名等于或以 authorization、cookie、password、token、secret、apikey 以及共享列表中其余名称结尾的值,在入队前会变成 "[redacted]":无论在属性还是 payload 中,无论多深(map、按 JSON 名称处理的 struct、切片、http.Header),都在任何裁剪之前完成。Config.RedactKeys 会替换这个列表,传一个空的非 nil 切片会关闭脱敏;要在默认列表上追加,用 RedactKeys: append(lyrelog.DefaultRedactKeys(), "pin")。
  • Free 组织用完当月事件配额后,服务器返回 429。事件留在内存中,等服务器重新接收时再发出,最多保留 MaxQueue 个。客户端会向 ErrorLog(或 stderr)输出一条警告,之后在有批次被接收之前不会再提示。
  • 上下文:os_name 是 runtime.GOOS,app_build 是二进制文件中的 VCS 修订版本(如果有的话),安装 id 和会话 id 按进程生成。
  • 限制在入队前生效:属性超过 200 个叶子节点(嵌套值逐个计数)时,多出的部分会被丢弃并计入 lyrelog_dropped_attrs,名称中的点变成 _(http.status 变成 http_status),error、时间、时长和 Stringer 变成字符串,struct 变成它的 JSON 形式,NaN 变成 null。超过 64 KiB 的 payload 变成 {"lyrelog_truncated": true, "bytes": N, "preview": "..."},带上它的前 1 KiB。单个事件的属性编码后最多 256 KiB,放不进 512 KiB 批次的事件会被丢弃并计数。
  • 用 fmt 打印 Config 或 *Client 时会隐藏 API 密钥。