otelslog: 为 Go 应用带来无缝集成的结构化日志与分布式追踪

yakumioto
679 阅读3分钟

在当今云原生应用不断发展的背景下，可观测性已成为理解系统行为和排查问题的重要组成部分。otelslog 这个 Go 语言工具包，它通过将 Go 的 slog 包与 OpenTelemetry 集成，帮助开发者更好地连接结构化日志与分布式追踪。

可观测性的现状

现代分布式系统会产生大量的日志和追踪数据，在服务之间关联这些信息并理解操作的完整上下文往往具有挑战性。开发人员需要在不同的工具和上下文之间切换，拼凑请求或操作期间发生的具体情况。

otelslog：日志与追踪的集成方案

otelslog 提供了一种统一的日志和追踪方法。它在保持 Go 开发人员熟悉的简单性和性能的同时，为日志添加追踪上下文信息。

主要特性

1. 追踪上下文集成

  • 自动注入追踪 ID 和 Span ID 到日志记录中
  • 自动处理 slog 属性中的 Span 对象和 Context 中的属性对象
  • 支持将日志中的属性，转化为 Span 的事件记录
  • 支持具有父子关系的嵌套 Span

2. 配置选项

  • 可自定义追踪 ID 和 Span ID 的字段名称
  • 可配置的追踪级别阈值
  • 可选的 Span 事件记录
  • 支持忽略日志级别的追踪选项

3. 结构化数据支持

  • 支持日志和追踪中的嵌套属性分组
  • slog 和 OpenTelemetry 格式之间的属性转换
  • 保持分布式追踪中的属性层次结构

使用示例

package main

import (
    "context"
    "log/slog"
    "os"
    
    "github.com/yakumioto/otelslog"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
    // 初始化追踪器
    tp := trace.NewTracerProvider()
    otel.SetTracerProvider(tp)
    defer tp.Shutdown(context.Background())
    
    // 设置 otelslog handler
    slog.SetDefault(slog.New(
        otelslog.NewHandler(slog.NewJSONHandler(os.Stdout, nil)),
    ))

    // 创建 span 并记录日志
    span := otelslog.NewSpanContext("service", "process-request")
    slog.Info("处理请求", 
        "operation", span,
        slog.Group("user",
            slog.String("id", "123"),
            slog.String("role", "admin"),
        ),
    )
    defer span.End()
}

进阶用法

上下文传播

otelslog 支持在分布式系统中维护追踪上下文：

// 创建根 span
span1 := otelslog.NewSpanContext("parent-spanname")
slog.Info("开始父操作", "parent-operation", span1)
defer span1.End()

// 创建带上下文的子 span
span2Ctx := otelslog.NewSpanContextWithContext(span1, "child-operation", "child-spanname")
slog.InfoContext(span2Ctx, "处理子操作")
defer span2Ctx.Done()

性能表现

基准测试结果：

BenchmarkJSONSlog-12                   	  346534	      3367 ns/op
BenchmarkJSONOtelSlogWithAttr-12       	  238906	      5670 ns/op
BenchmarkTextOtelSlogWithContext-12    	  271627	      4346 ns/op

这些数据显示了在提供可观测性功能时的性能开销情况。

otelslog 的应用价值

  1. 便于调试：通过关联日志与追踪，帮助理解分布式系统中的操作流程。

  2. 易于使用：基于常见的 Go 模式和接口构建，可以较小改动集成到现有代码库。

  3. 技术选型：基于 OpenTelemetry 构建，有利于长期使用和维护。

与可观测性工具的集成

otelslog 可以与支持 OpenTelemetry 的可观测性平台配合使用，如 Jaeger、Zipkin 和云原生可观测性解决方案。通过 OpenTelemetry 集成，您可以：

  • 将追踪数据导出到所选后端
  • 在现有工具中关联日志和追踪
  • 使用 OpenTelemetry 的工具生态系统和导出器

开始使用

安装 otelslog：

go get github.com/yakumioto/otelslog

参与项目

otelslog 是一个开源项目，欢迎社区参与。无论是修复问题、添加功能还是改进文档，您的参与都很重要。

访问 GitHub 仓库：

  • 关注项目进展
  • 反馈使用问题
  • 提交代码贡献
  • 参与技术讨论

持续改进

otelslog 项目在持续维护和改进中。我们会关注可观测性领域的发展，同时保持代码的简洁性和效率。

欢迎尝试 otelslog，探索提升 Go 应用可观测性的新方案。

avatar
文章
阅读
粉丝