Logging

日志与脱敏 (Logging)

English Version | 简体中文

---

SDK 通过 Go 标准库的 log/slog 记录日志。默认情况下，SDK 不会输出任何日志：若未配置 WithLogger 且未设置环境变量 TYPESAFE_LOG_LEVEL，所有日志记录都将被静默丢弃，符合优秀 Go 库的通用实践。

// 方式 1：通过环境变量快速启用（输出 info/debug 至终端）
// export TYPESAFE_LOG_LEVEL=debug

// 方式 2：代码中配置带有凭证脱敏处理的 Handler
logger := slog.New(typesafe.NewRedactingHandler(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
	Level: slog.LevelDebug,
})))
client, err := typesafe.NewClient(typesafe.WithLogger(logger))

---

日志级别

typesafe.ParseLogLevel(name) 可将字符串名称解析为对应的 slog.Level：

名称	对应级别	说明
debug	slog.LevelDebug	记录完整的网络链路流量（标头与消息体）
info	slog.LevelInfo	记录请求生命周期、耗时、状态码与重试事件
warn, warning	slog.LevelWarn	记录未知答案类型警告等非阻断性异常
error	slog.LevelError	记录严重错误
off	高于所有级别	完全关闭任何日志输出

若环境变量中的日志级别无法识别，SDK 会输出格式警告并保持静默。

---

日志事件清单

消息 (msg)	级别	属性 (Attributes)
response	info	method, url, status, elapsed_ms, request_id
request.retry	info	method, url, attempt
request.failed	info	method, url, error
request.wire	debug	method, url, headers, body
response 标头与报文体	debug	在开启 debug 时附加在 response 记录中

一条典型的 Info 响应日志示例：

time=2026-09-19T11:29:48.457+08:00 level=INFO msg=response method=POST url=https://api.typesafe.ai/v1/systemone status=200 elapsed_ms=484 request_id=req_01a0b7b6...

---

敏感凭证自动脱敏

SDK 在记录日志时，会自动对涉及敏感凭据的 HTTP 标头进行脱敏。typesafe.NewRedactingHandler 可以将这一安全保障扩展至你通过该 Logger 输出的所有日志记录。

logger := slog.New(typesafe.NewRedactingHandler(slog.NewJSONHandler(os.Stdout, nil)))
client, err := typesafe.NewClient(typesafe.WithLogger(logger))

脱敏规则

标头名称属于以下任一情况时将被识别为敏感信息并将其值替换为 ***：

• 精确匹配：Authorization、Proxy-Authorization、X-API-Key、API-Key、Cookie、Set-Cookie；
• 名称中包含子串 token 或 secret（不区分大小写）；
• map[string]string 形式的标头属性会被逐 key 检查。

脱敏效果：

msg=request.wire headers="map[Accept:application/json Authorization:*** User-Agent:typesafe-sdk-go/0.13.0]"

Warning

标头会自动脱敏，但 Body 报文体不会被自动脱敏。 请避免在 state 中存放密码或私钥，并在生产环境中将日志级别设置为 info 或更高，避免在 debug 级别下将业务内容输出至日志。