otel-cli高级用法：后台Span管理、事件添加与自定义时间戳实战

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

OpenTelemetry command-line tool（otel-cli）是一款专为Shell脚本及类似环境设计的事件发送工具，能够帮助开发者轻松实现分布式追踪。本文将深入探讨otel-cli的高级用法，包括后台Span管理、事件添加与自定义时间戳等实战技巧，让你快速掌握分布式追踪的核心技能。

一、后台Span管理：轻松处理长时间运行任务 🚀

后台Span管理是otel-cli的核心功能之一，特别适用于处理长时间运行的任务。通过将Span置于后台运行，你可以避免阻塞当前脚本的执行流程，同时持续收集追踪数据。

1.1 简单后台Span示例

以下是一个简单的后台Span示例，展示了如何在后台启动一个Span并设置超时时间：

../otel-cli span background \ --service otel-cli-demo \ --name "executing $0" \ --timeout 2 &

在这个示例中，--timeout 2参数设置了Span的超时时间为2秒，&符号将命令置于后台运行。当脚本退出时，otel-cli也会随之退出，因此总运行时间会略超过1秒。

1.2 分层后台Span管理

对于更复杂的场景，你可以使用分层后台Span管理。以下示例展示了如何创建一个后台Span，添加事件，并创建子Span：

carrier=$(mktemp) # traceparent propagation via tempfile sockdir=$(mktemp -d) # a unix socket will be created here export OTEL_SERVICE_NAME="otel-cli-demo" # 启动后台Span服务器 ../otel-cli span background \ --verbose --fail \ --tp-carrier $carrier \ --sockdir $sockdir \ --tp-print \ --name "$0 script execution" \ --timeout 10 & # 添加事件到后台Span ../otel-cli span event \ --verbose \ --name "did a thing" \ --sockdir $sockdir \ --attrs "data1=$data1" # 创建子Span ../otel-cli exec \ --verbose --fail \ --name "sleep 0.2" \ --tp-required \ --tp-carrier $carrier \ --tp-print \ sleep 0.2 # 结束后台Span ../otel-cli span end --sockdir $sockdir

在这个示例中，我们使用了--tp-carrier参数来传递追踪上下文，--sockdir参数指定了Unix socket的目录，用于与后台Span进行通信。

二、事件添加：丰富Span信息 📝

事件是Span的重要组成部分，能够提供关于Span执行过程的详细信息。otel-cli允许你在Span运行过程中动态添加事件，并为事件添加属性。

2.1 添加基本事件

以下命令展示了如何为后台Span添加一个基本事件：

../otel-cli span event \ --verbose \ --name "slept 1 second" \ --sockdir $sockdir

在这个命令中，--name参数指定了事件的名称，--sockdir参数指定了与后台Span通信的Unix socket目录。

2.2 添加带属性的事件

你还可以为事件添加属性，以提供更丰富的信息。以下示例展示了如何添加一个带有属性的事件：

data1=$(uuidgen) ../otel-cli span event \ --verbose \ --name "did a thing" \ --sockdir $sockdir \ --attrs "data1=$data1"

在这个示例中，我们使用--attrs参数为事件添加了一个名为data1的属性，其值为一个随机生成的UUID。

三、自定义时间戳：精确控制事件时间 ⏱️

虽然otel-cli默认使用当前时间作为事件的时间戳，但在某些情况下，你可能需要使用自定义时间戳。例如，当你需要回溯性地添加事件时，自定义时间戳就非常有用。

3.1 设置自定义时间戳

otel-cli提供了--timestamp参数，允许你为事件设置自定义时间戳。时间戳的格式为Unix时间戳（秒级或毫秒级）。以下示例展示了如何使用自定义时间戳：

# 获取当前时间戳（毫秒级） timestamp=$(date +%s%3N) # 模拟延迟 sleep 1 # 添加带有自定义时间戳的事件 ../otel-cli span event \ --verbose \ --name "delayed event" \ --sockdir $sockdir \ --timestamp $timestamp

在这个示例中，我们首先获取了当前时间戳（毫秒级），然后模拟了1秒的延迟，最后使用--timestamp参数将事件的时间戳设置为延迟前的时间。

四、实战案例：构建完整的追踪流程 🏗️

为了更好地理解otel-cli的高级用法，我们来看一个完整的实战案例。这个案例将展示如何使用后台Span、添加事件、创建子Span以及使用自定义时间戳。

4.1 案例脚本

以下是一个完整的示例脚本，展示了如何构建一个完整的追踪流程：

#!/bin/bash set -e set -x carrier=$(mktemp) sockdir=$(mktemp -d) export OTEL_SERVICE_NAME="otel-cli-demo" # 启动后台Span ../otel-cli span background \ --verbose --fail \ --tp-carrier $carrier \ --sockdir $sockdir \ --tp-print \ --name "full demo execution" \ --timeout 20 & # 等待后台Span启动 sleep 0.5 # 添加开始事件 start_time=$(date +%s%3N) ../otel-cli span event \ --verbose \ --name "demo started" \ --sockdir $sockdir \ --attrs "start_time=$start_time" \ --timestamp $start_time # 执行任务1 task1_start=$(date +%s%3N) sleep 1 task1_end=$(date +%s%3N) ../otel-cli span event \ --verbose \ --name "task1 completed" \ --sockdir $sockdir \ --attrs "duration=$((task1_end - task1_start))ms" \ --timestamp $task1_end # 创建子Span执行任务2 ../otel-cli exec \ --verbose --fail \ --name "task2 execution" \ --tp-required \ --tp-carrier $carrier \ --attrs "task=task2" \ sleep 0.5 # 添加结束事件 end_time=$(date +%s%3N) ../otel-cli span event \ --verbose \ --name "demo completed" \ --sockdir $sockdir \ --attrs "total_duration=$((end_time - start_time))ms" \ --timestamp $end_time # 结束后台Span ../otel-cli span end --sockdir $sockdir # 清理临时文件 rm $carrier rm -rf $sockdir

4.2 案例解析

在这个案例中，我们首先创建了一个后台Span，并设置了超时时间为20秒。然后，我们添加了开始事件，并使用自定义时间戳记录了开始时间。接着，我们执行了两个任务，每个任务完成后都添加了相应的事件，并记录了任务的持续时间。在执行第二个任务时，我们创建了一个子Span，以展示Span的嵌套关系。最后，我们添加了结束事件，并清理了临时文件。

通过这个案例，你可以看到otel-cli如何帮助你构建一个完整的分布式追踪流程，从而更好地理解和优化你的应用程序。

五、总结

otel-cli是一款功能强大的命令行工具，能够帮助开发者轻松实现分布式追踪。通过本文介绍的后台Span管理、事件添加与自定义时间戳等高级用法，你可以更加灵活地收集和分析追踪数据，从而提高应用程序的可靠性和性能。

如果你想深入了解otel-cli的更多功能，可以参考项目中的演示脚本，如demos/10-span-background-simple.sh和demos/15span-background-layered.sh，这些脚本提供了更多实际应用场景的示例。

希望本文能够帮助你更好地掌握otel-cli的高级用法，为你的分布式追踪之旅提供有力的支持！

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