自动仪表很神奇：将 OpenTelemetry Python 与 Lightstep 结合使用

Bumblebee pollinating a flower. Photo by 阿德里维莱拉.

在我的 上一篇 OpenTelemetry 博客文章 ，我讲了如何发送 开放遥测 (OTel) 数据到 光步 使用 Golang。如果您是 Golang 开发人员，这一切都很好，但是如果您使用 Python 怎么办？好吧，我的朋友，你很幸运，因为今天，我将研究如何使用 Python 将 OpenTelemetry 数据发送到 Lightstep。

与 OTel Golang 帖子一样，我们可以将 OTel 数据发送到 Lightstep（或任何其他支持 开放遥测协议 (OTLP) ，就此而言）以三种方式之一：

1. 直接从应用程序
2. 开放遥测收集器
3. 发射器

在这篇文章中，我将详细研究这三种方法中的每一种，并通过代码片段解释如何将数据导入 Lightstep 可观察性 .我们开工吧！

Lightstep Observability 支持原生 开放遥测协议 (OTLP) .它可以通过以下方式接收 OTLP 格式的数据 HTTP 或者 gRPC .您需要指定希望在代码中使用的方法，我们将在接下来的代码片段中看到。

如果您对在 OpenTelemetry 中使用 gRPC 与 HTTP 感到好奇，请查看 这些文档 .

笔记： 其他支持 OTLP 的可观察性工具包括 蜂窝 , 格拉法纳 ， 和 积家 .

使用 OTel 检测 Python 代码非常酷的一件事是 Python 提供了自动（自动）检测。这是什么意思？从高层次上讲，这意味着您可以运行一个 Python OpenTelemetry 代理来包装您的 Python 应用程序，以自动检测它。

更具体地说，自动检测使用 shims 或字节码检测代理在运行时或编译时拦截您的代码，以将跟踪和指标检测添加到您所依赖的库和框架中。自动仪表的美妙之处在于它需要最少的努力。坐下来，放松，享受表演。许多流行的 Python 库都是自动检测的，包括 烧瓶 和 姜戈 .您可以找到完整列表 这里 .

手动检测需要向您的代码添加跨度、上下文传播、属性等。这类似于评论您的代码或编写测试。

这是否意味着您不应该手动检测？一点也不！如果可用，请从自动仪表开始。如果自动检测不足以满足您的用例（通常不是），则添加手动检测。例如，自动检测不知道您的业务逻辑——它只知道框架和语言——在这种情况下，您需要手动检测您的业务逻辑，以便获得这种可见性。

先决条件

在我们开始我们的教程之前，这里有一些你需要的东西：

• 一个基本的了解 Python 和 Python 虚拟环境
• 一个基本的认识 开放遥测收集器
• 基本了解如何使用 Lightstep 可观察性

如果您想运行完整的代码示例，您还需要：

• 一个 Lightstep 可观察性帐户
• 一个 Lightstep 访问令牌 告诉 Lightstep 要将跟踪发送到哪个项目
• 的工作安装 Python
• Docker（在本地运行 OTel 收集器）

直接从应用程序

如果您开始使用 OpenTelemetry 检测您的应用程序，这可能是大多数初学者最常用的方法。顾名思义，我们直接从我们的应用程序代码向给定的 Observability 后端发送数据。

Application sending OpenTelemetry data directly to Lightstep. Diagram by 阿德里维莱拉.

我们的示例应用程序是一个 Flask 应用程序。我们将利用自动和手动仪器。

让我们在下面更详细地了解这一点。

1-设置你的环境

让我们设置我们的工作目录和我们的 Python 虚拟环境

 mkdir hotel_python  
 cd otel_python  
  
 python3 -m venv 。  
 来源 ./bin/activate  
 触摸服务器.py

打开 服务器.py ，并粘贴以下内容：

2- 安装所需的 OTel 库

这些是将数据发送到 ** 可观察性后端** （例如 Lightstep）。

 # OTel 特定  
 pip install opentelemetry-distro  
 pip install opentelemetry-instrumentation-flask  
 pip install opentelemetry-exporter-otlp  
  
 # 特定应用  
 点安装烧瓶  
 pip 安装请求

几个值得注意的项目：

• 安装 开放遥测发行版 将安装许多其他依赖包来检测代码，包括 opentelemetry-api 和 opentelemetry-sdk
• 这 opentelemetry-instrumentation-flask 包用于自动检测 Flask 应用程序
• 这 opentelemetry-exporter-otlp-proto-grpc 包用于通过 gRPC 将 OTel 数据发送到您的 Observability 后端（例如 Lightstep）。

3-安装自动仪表

在上面的步骤中，我们添加了 opentelemetry-instrumentation-flask 用于自动检测我们的 Python Flask 应用程序的库；但是，我们仍然缺少一块拼图。您可能还记得本文前面的内容，Python 自动检测使用一个代理来包装我们的 Python 应用程序并自动为我们添加一些高级检测。这与 opentelemetry-instrumentation-flask 图书馆使这种魔法成为可能。

我们像这样安装代理：

 opentelemetry-bootstrap -a 安装

这会安装一个名为 开放式遥测仪器 ，这就是所有魔法发生的地方。

4-运行应用程序

这就是有趣的地方！通常要运行这个应用程序，我们会这样运行它：

 蟒蛇服务器.py

但如果我们这样做，我们就不会向 Lightstep 发送任何 OTel 数据。所以我们必须改为这样做：

 出口 OTEL_EXPORTER_OTLP_TRACES_HEADERS="lightstep-access-token=<LS_ACCESS_TOKEN> " 开放遥测仪器/  
 --traces_exporter 控制台，otlp_proto_grpc /  
 --metrics_exporter 控制台，otlp_proto_grpc /  
 --service_name test-py-auto-otlp-grpc-server /  
 --exporter_otlp_traces_endpoint "ingest.lightstep.com:443" /  
 蟒蛇服务器.py

一些值得注意的项目：

• 代替 <LS_ACCESS_TOKEN> 用你自己的 Lightstep 访问令牌 .
• --traces_exporter 告诉我们将踪迹发送到哪里。在这种情况下，我们希望将其发送到 安慰 （标准输出）和 otlp_proto_grpc .这 otlp_proto_grpc 选项告诉 开放式遥测仪器 我们希望将其发送到通过 gRPC 接受 OTLP 的端点。你也可以使用 otlp 相反，因为它是 otlp_proto_grpc .可用选项的完整列表 --traces_exporter 可以被找寻到 这里 .
• --exporter_otlp_traces_endpoint 告诉 开放式遥测仪器 OTLP 端点将我们的跟踪直接发送到 Lightstep，在 摄取.lightstep.com:443 .
• - 服务名称 设置我们服务的名称。这是我们将在 Lightstep 服务资源管理器中看到的值。
• 注意最后一行是 蟒蛇服务器.py ，这是我们运行我们的应用程序的地方。这里 开放式遥测仪器 正在包装调用 蟒蛇服务器.py

样本输出：

Screen capture of server.py startup sequence output. Screenshot by 阿德里维莱拉.

想要使用 HTTP 而不是 gRPC？首先，您需要确保 pip 包 opentelemetry-exporter-otlp-proto-http 已安装（应作为安装的一部分自动安装 opentelemetry-exporter-otlp ）。

接下来，您的 开放式遥测仪器 命令如下所示：

 开放遥测仪器/  
 --traces_exporter 控制台，otlp_proto_http /  
 --metrics_exporter 控制台，otlp_proto_http /  
 --service_name test-py-auto-otlp-server /  
 --exporter_otlp_traces_endpoint "https://ingest.lightstep.com/traces/otlp/v0.9" /  
 蟒蛇服务器.py

注意 HTTP 端点是如何不同的，我们正在使用 otlp_proto_http 代替 otlp_proto_grpc 在我们的 --traces_exporter 旗帜。

5- 调用 /rolldice 服务

打开一个新的终端窗口，然后运行以下命令：

 卷曲[ http://localhost:8082/rolldice](http://localhost:8082/rolldice)

运行上面的行将返回一个介于 1 和 6 之间的随机数。那里没什么特别的。但是，如果您查看终端窗口 服务器.py ，您会在输出中注意到一些内容：

Screen capture of server.py output after calling /rolldice endpoint. Screenshot by 阿德里维莱拉.

我们看到从 服务器.py ！为什么我们会在这里看到这个？因为我们设置 --traces_exporter 标记为 控制台，otlp_proto_grpc ，通过 OTLP 导出到 Lightstep 和 到控制台。

6- 在 Lightstep 中查看

Screen capture of test-py-auto-otlp-server service in Lightstep. Screenshot by 阿德里维莱拉.

开放遥测收集器

将数据发送到 Observability 后端的下一种方法是通过 OpenTelemetry (OTel) 收集器 .对于非开发设置，这是将 OpenTelemetry 数据发送到 Observability 后端的推荐方法。

Application sending OpenTelemetry data to Lightstep via OTel Collector. Diagram by 阿德里维莱拉.

通过 OTel 收集器发送 OTel 数据是 几乎相同 与我们在上面的 Direct from Application 示例中所做的一样。唯一的区别是：

• 我们需要运行一个 OTel 收集器
• 当我们跑 开放式遥测仪器 , 我们的选择略有不同

让我们在下面更详细地了解这一点。

1- 按照“直接来自应用程序”示例中的步骤 1-3

2-运行收集器

首先，我们需要配置我们的收集器以将数据发送到 Lightstep。我们通过抓取来做到这一点 收集器.yml 来自光步的 opentelemetry-示例 回购。

 git clone [[email protected]](/cdn-cgi/l/email-protection):lightstep/opentelemetry-examples.git

打开一个新的终端窗口。首先，您需要编辑 收集器.yaml 文件。务必更换 ${LIGHTSTEP_ACCESS_TOKEN} 用你自己的 Lightstep 访问令牌 .

现在您可以启动收集器：

 cd opentelemetry-examples/collector/vanilla 码头工人运行 -it --rm -p 4317:4317 -p 4318:4318 /  
 -v $(pwd)/collector.yaml:/otel-config.yaml /  
 --name otelcol otel/opentelemetry-collector-contrib:0.53.0 /  
 “/otelcol-contrib”/  
 “--config=otel-config.yaml”

样本输出：

Screen capture OTel Collector startup sequence. Screenshot by 阿德里维莱拉.

3-运行应用程序

 开放遥测仪器/  
 --traces_exporter 控制台，otlp /  
 --metrics_exporter 控制台，otlp /  
 --service_name test-py-auto-collector-server /  
 python server_uninstrumented.py

一些值得注意的项目：

• 上面的命令和我们的很相似 直接从应用程序 例如，除了我们缺少我们的 --exporter_otlp_endpoint 选项。这是因为如果我们把它排除在外，那么 开放式遥测仪器 假设它连接到一个 OTel Collector 端点 本地主机:4317 .
• 我们不需要设置 OTEL_EXPORTER_OTLP_TRACES_HEADERS ，因为已经在 Collector 中配置了 配置.yml 文件。
• 如果您希望使用 HTTP 而不是 gRPC，则需要替换 --traces_exporter 控制台，otlp 和 --traces_exporter 控制台，otlp_proto_http .注意 otlp 是一个别名 otlp_proto_grpc .

样本输出：

Screen capture of server.py startup sequence output. Screenshot by 阿德里维莱拉.

4- 调用 /rolldice 服务

打开一个新的终端窗口，然后运行以下命令：

 卷曲[ http://localhost:8082/rolldice](http://localhost:8082/rolldice)

样本输出：

Screen capture of server.py output after calling /rolldice endpoint. Screenshot by 阿德里维莱拉.

再次，我们看到了 服务器.py 因为我们将 –traces_exporter 标志设置为 console,otlp，它通过 OTLP 导出到 Collector 和 到控制台。

5- 在 Lightstep 中查看

Screen capture of test-py-auto-collector-server service in Lightstep. Screenshot by 阿德里维莱拉.

启动器

如果您认为将 OTel 数据发送到 Lightstep à la auto-instrumentation 代理很容易，那么通过 OTel Python 启动器 ！把它想象成一个 OTel 包装器，通过预先配置一堆东西来降低进入门槛，从而使向 Lightstep 发送数据变得更加容易。

通过 Launcher 发送 OTel 数据是 几乎相同 与我们在上面的 Direct from Application 示例中所做的一样，有一些细微差别：

• 我们有更少的包裹（耶！）
• 当我们跑 开放式遥测仪器 , 我们的选择略有不同

让我们看看它的实际效果好吗？

1- 按照“直接来自应用程序”示例中的步骤 1-3

小改动：将步骤 2 中的库替换为：

 # OTel 特定  
 pip install opentelemetry-launcher  
 pip install protobuf==3.20.1  
  
 # 特定应用  
 pip 安装请求  
 点安装烧瓶

我们需要强制一个特定的版本 protobuf 因为 Launcher 与较新版本的兼容性问题。这是 已经修好了 在 opentelemetry-python .

2-运行应用程序

务必更换 <LS_ACCESS_TOKEN> 用你自己的 Lightstep 访问令牌 .

 导出 LS_ACCESS_TOKEN="<LS_ACCESS_TOKEN> "  
  
 开放遥测仪器/  
 --service_name test-py-auto-launcher-server /  
 蟒蛇服务器.py

看起来我们的选择更少了，不是吗？让我们深入挖掘一些值得注意的项目：

• 我们不需要指定 --exporter_otlp_traces_endpoint ，因为这已经为我们隐含地完成了，并且设置为 摄取.lightstep.com:443 .
• 而不是为我们的环境设置一个看起来凌乱的环境变量 Lightstep 访问令牌 ( 出口 OTEL_EXPORTER_OTLP_TRACES_HEADERS="lightstep-access-token=<LS_ACCESS_TOKEN> " )，我们只需要这样做： 导出 LS_ACCESS_TOKEN="<LS_ACCESS_TOKEN> " ，看起来更干净。

如果您希望首先通过收集器实例发送您的 OTel 数据，而不是直接从您的应用程序发送，您可以这样做：

 开放遥测仪器/  
 --service_name test-py-auto-launcher-server /  
 --exporter_otlp_traces_endpoint "0.0.0.0:4317" /  
 --exporter_otlp_traces_insecure true /  
 蟒蛇服务器.py

请注意我们如何不必设置 LS_ACCESS_TOKEN ，因为已经在 Collector 中配置了 配置.yml 文件。只需确保您有一个正在运行的 OTel 收集器实例！

另外，一定要设置 --exporter_otlp_traces_insecure 真 .如果您使用收集器并隐式配置它，这是必需的，就像我们在这里所做的那样。仅当未在收集器中配置证书时才需要这样做。

样本输出：

Screen capture of server.py startup sequence output after calling /rolldice endpoint. Screenshot by 阿德里维莱拉.

3- 调用 /rolldice 服务

打开一个新的终端窗口，然后运行以下命令：

 卷曲[ http://localhost:8082/rolldice](http://localhost:8082/rolldice)

样本输出：

Screen capture of server.py output (Launcher version). Screenshot by 阿德里维莱拉.

请注意，由于我们的 开放式遥测仪器 调用未指定 --traces_exporter , 相当于说 --traces_exporter otlp_proto_grpc .我还意味着控制台（stdout）没有跟踪输出。

4- 在 Lightstep 中查看

Screen capture of test-py-auto-launcher-server service in Lightstep. Screenshot by 阿德里维莱拉.

我应该始终使用自动仪表代理吗？

是 开放式遥测仪器 即使您没有使用未自动检测的 Python 库，仍然有帮助吗？个人觉得是这样！考虑这个文件， 客户端.py ：

让我们使用自动检测代理运行上述程序。务必更换 <LS_ACCESS_TOKEN> 用你自己的 Lightstep 访问令牌 .

 出口 OTEL_EXPORTER_OTLP_TRACES_HEADERS="lightstep-access-token=<LS_ACCESS_TOKEN> "  
  
 开放遥测仪器/  
 --traces_exporter 控制台，otlp /  
 --service_name test-py-auto-client /  
 --exporter_otlp_endpoint "ingest.lightstep.com:443" /  
 python client.py 测试

请注意，除了在 客户端.py ，那里没有OTel配置。您无需配置服务名称、导出器或端点。当你跑步时，这一切都得到了照顾 开放式遥测仪器 .另外，如果您的代码碰巧使用了自动检测的库，则您无需执行任何其他操作。

笔记： 如果你想知道我们为什么要执行命令 _python client.py 测试_ ， 这是因为 _客户端.py_ 接受一个参数，在这种情况下称为 _测试_ .

gRPC 调试

你有没有想过你的 gRPC 调用是否会进入黑洞？我一定会的！当我为 Golang OTel 库使用 gRPC 时，我了解了一些 gRPC 调试标志，它们可以让我更轻松地解决 gRPC 连接问题。这当然让我想知道是否有 Python 等价物。原来有。在运行你的应用程序之前设置这些环境变量，你就很成功了：

 导出 GRPC_VERBOSITY=debug  
 导出 GRPC_TRACE=http,call_error,connectivity_state

这意味着当我们启动我们的 服务器.py ，我们得到这样的结果：

Screen capture of server.py startup sequence output with gRPC debugging enabled. Screenshot by 阿德里维莱拉.

然后当我们通过 卷曲 ，我们得到这个：

Screen capture of server.py output after calling /rolldice endpoint showing successful gRPC call. Screenshot by 阿德里维莱拉.

上面突出显示的部分告诉我，我们的 gRPC 调用成功了！

最后的想法

Python 中的自动检测非常棒，它确实降低了 OpenTelemetry 的进入门槛。正如我们在 Direct from Application 和 Collector 示例中看到的那样，代码几乎保持不变。唯一的区别是您需要更改一些标志，以便自动检测代理知道将您的跟踪发送到哪里。好，易于！

如果您想知道，有一种完全纯正的 OTel Python 手动检测方法，我将在以后的博文中介绍，敬请期待！现在，沉浸在你今天学到了一些关于 OTel Python 自动仪表的超酷知识的事实中！

现在，我会奖励你一张我的老鼠菲比正在拥抱的照片。

Phoebe the rat getting some nice cuddles from her humans. Photo by 阿德里维莱拉.

和平、爱和代码。

对使用 Python 进行 OTel 检测有疑问？跟我说话！随意连接 电子邮件 ，或者打我 推特 或者 领英 .希望收到大家的来信！

最初发表于 https://lightstep.com .

版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明

本文链接：https://www.qanswer.top/23552/26091001