如何用otel-cli构建Shell脚本分布式追踪：父子Span与上下文传播技巧

【免费下载链接】otel-cliOpenTelemetry command-line tool for sending events from shell scripts & similar environments项目地址: https://gitcode.com/gh_mirrors/ot/otel-cli

otel-cli是一款专为Shell脚本环境设计的OpenTelemetry命令行工具，能够帮助开发者轻松实现分布式追踪功能。通过otel-cli，即使是复杂的嵌套脚本也能生成清晰的追踪链路，让你在命令行环境中也能拥有专业级的可观测性。

为什么选择otel-cli？

在现代分布式系统中，Shell脚本往往承担着关键的协调和执行角色，但传统上缺乏有效的追踪手段。otel-cli填补了这一空白，它允许你：

• 无需编写代码即可为Shell命令添加追踪能力
• 自动处理跨进程的上下文传播
• 与OpenTelemetry生态系统无缝集成
• 轻量级设计，不影响脚本性能

快速入门：创建你的第一个Span

最简单的追踪示例可以在demos/01-simple-span.sh中找到。这个脚本展示了如何创建一个基本的Span：

st=$(date +%s.%N) # 记录开始时间 # 执行一些操作... data1=$(uuidgen) data2=$(uuidgen) et=$(date +%s.%N) # 记录结束时间 # 创建Span ../otel-cli span \ --service "otel-cli-demo" \ --name "hello world" \ --kind "client" \ --start $st \ --end $et \ --tp-print \ --attrs "my.data1=$data1,my.data2=$data2"

这个示例演示了手动记录操作开始和结束时间，并使用otel-cli创建一个包含自定义属性的Span。--tp-print选项会输出TRACEPARENT环境变量，这是上下文传播的关键。

掌握父子Span：构建追踪树

在分布式系统中，操作往往是嵌套的。demos/05-nested-exec.sh展示了如何创建父子Span关系：

# 设置服务名称 export OTEL_SERVICE_NAME="otel-cli-demo" # 创建载体文件保存上下文 carrier=$(mktemp) ../otel-cli span -n "traceparent demo $0" --tp-print --tp-carrier $carrier # 创建子Span并执行命令 ../otel-cli exec \ --name "hammer the server for sweet sweet data" \ --kind "client" \ --tp-carrier $carrier \ --verbose \ --fail \ -- \ ../otel-cli exec -n fake-server -k server /bin/echo 500 NOPE

这个示例中，我们使用临时文件作为上下文载体，通过--tp-carrier参数在父子进程间传递追踪上下文。外层exec命令创建了一个"client"类型的Span，而内层exec则创建了一个"server"类型的子Span，形成完整的调用关系。

上下文传播的高级技巧

1. 环境变量传播

最直接的上下文传播方式是使用环境变量：

# 生成TRACEPARENT并导出到环境变量 eval $(../otel-cli span -n "parent" --tp-export) # 子进程会自动继承环境变量中的上下文 ../otel-cli span -n "child"

2. 文件载体传播

当无法通过环境变量传递时（如在不同的shell实例中），可以使用文件载体：

# 创建载体文件 carrier=$(mktemp) ../otel-cli span -n "parent" --tp-carrier $carrier # 在另一个进程中使用载体文件 ../otel-cli span -n "child" --tp-carrier $carrier

3. 后台进程追踪

对于后台运行的进程，demos/10-span-background-simple.sh提供了特殊的处理方式：

# 启动后台Span ../otel-cli span background \ --name "background job" \ --service "otel-cli-demo" \ --tp-print \ --attrs "type=background,delay=5" # 执行一些长时间运行的任务... sleep 5 # 结束后台Span ../otel-cli span end

最佳实践与常见问题

设置默认服务名称

为避免重复输入服务名称，可以设置环境变量：

export OTEL_SERVICE_NAME="my-app"

处理时间同步

确保系统时间同步，特别是在分布式环境中。otel-cli使用纳秒级时间戳，时间偏差会导致追踪数据不准确。

错误处理

使用--fail选项可以让otel-cli在发生错误时返回非零退出码，便于脚本错误处理：

../otel-cli span -n "critical-operation" --fail || { echo "Span creation failed!" exit 1 }

总结

otel-cli为Shell脚本提供了强大而灵活的分布式追踪能力。通过本文介绍的父子Span创建和上下文传播技巧，你可以轻松为复杂的脚本系统添加可观测性。无论是简单的单脚本追踪还是跨多系统的复杂调用链，otel-cli都能帮助你清晰地了解系统运行状况，快速定位问题。

开始使用otel-cli，让你的Shell脚本也拥有企业级的可观测性吧！

【免费下载链接】otel-cliOpenTelemetry command-line tool for sending events from shell scripts & similar environments项目地址: https://gitcode.com/gh_mirrors/ot/otel-cli