otel-cli完全指南：如何在Shell脚本中轻松发送OpenTelemetry追踪数据

【免费下载链接】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无法正常工作时也能继续运行。

快速安装otel-cli的三种方式

Go安装（推荐）

如果你已经安装了Go环境，只需一行命令即可安装otel-cli：

go install github.com/equinix-labs/otel-cli@latest

安装完成后，otel-cli会被放置在你的GOPATH中。如果GOPATH已添加到系统PATH，你就可以直接在终端中使用otel-cli命令了。

Docker方式

对于喜欢使用容器的用户，官方提供了Docker镜像：

docker pull ghcr.io/equinix-labs/otel-cli:latest docker run ghcr.io/equinix-labs/otel-cli:latest status

Homebrew安装（macOS用户）

macOS用户可以通过Homebrew安装：

brew tap equinix-labs/otel-cli brew install otel-cli

基础配置：让otel-cli正常工作

otel-cli可以零配置添加到你的脚本中，即使没有配置，它也会正常运行而不影响脚本执行。不过，为了将追踪数据发送到OpenTelemetry后端，你需要设置OTLP端点。

环境变量配置

最简便的方式是通过环境变量配置：

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

配置文件

你也可以使用JSON配置文件来配置otel-cli。项目中提供了example-config.json作为配置参考。

核心功能：otel-cli的四大用法

1. 基本Span创建：otel-cli span

创建一个简单的Span非常直观：

otel-cli span --service my-service --name "simple-span"

你还可以指定开始和结束时间：

otel-cli span --start 1616620946 --end 1616620950.241980634

2. 执行命令并追踪：otel-cli exec

otel-cli exec命令可以在执行命令的同时创建Span，非常适合追踪脚本中的关键操作：

otel-cli exec --service my-service --name "curl-google" curl https://google.com

otel-cli会自动注入{{traceparent}}，让子进程也能继承追踪上下文：

otel-cli exec --name "parent-command" -- otel-cli exec --name "child-command" sleep 1

3. 后台Span：otel-cli span background

对于需要长时间运行的操作，可以使用后台Span：

otel-cli span background \ --service my-service \ --name "long-running-operation"

后台Span运行时，你可以添加事件：

otel-cli span event --name "progress-update" --attrs "status=in-progress"

完成后结束Span：

otel-cli span end

4. 本地测试服务器：otel-cli server

开发时，你可以使用otel-cli内置的服务器来查看追踪数据：

otel-cli server tui

这个命令会启动一个终端界面，实时显示接收到的追踪数据，帮助你调试和验证追踪是否正常工作。

实用示例：otel-cli在实际场景中的应用

示例1：简单脚本追踪

下面是一个简单的脚本示例，使用otel-cli追踪关键操作：

#!/bin/bash # 开始一个Span otel-cli span background --service backup-script --name "daily-backup" # 执行备份操作并追踪 otel-cli exec --name "database-dump" mysqldump -u root mydb > backup.sql # 添加事件标记备份完成 otel-cli span event --name "backup-completed" --attrs "file=backup.sql,size=$(du -h backup.sql | cut -f1)" # 结束Span otel-cli span end

示例2：嵌套Span追踪

otel-cli支持创建嵌套的Span，以展示操作之间的关系：

#!/bin/bash # 生成追踪上下文 carrier=$(mktemp) otel-cli span -n "parent-operation" --tp-carrier $carrier # 在父Span下执行子操作 otel-cli exec --tp-carrier $carrier --name "child-operation" \ otel-cli exec --name "grandchild-operation" sleep 2

常见问题与解决方案

问题：otel-cli无法连接到OTLP端点

解决方案：确保OTLP端点已正确配置且可访问。可以使用otel-cli status命令检查连接状态：

otel-cli status

问题：后台Span在脚本退出时被中断

解决方案：使用--background-skip-parent-pid-check选项让otel-cli在父进程退出后继续运行：

otel-cli span background --background-skip-parent-pid-check --name "long-operation"

问题：需要在非交互式环境中使用otel-cli

解决方案：确保正确设置所有必要的环境变量，特别是OTLP端点和服务名称：

export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 export OTEL_SERVICE_NAME=my-service otel-cli span --name "non-interactive-span"

总结：提升Shell脚本可观测性的利器

otel-cli为Shell脚本提供了简单而强大的OpenTelemetry追踪能力。通过它，你可以轻松地为现有脚本添加分布式追踪，而无需复杂的配置或代码修改。无论是简单的命令执行还是复杂的后台任务，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