博客 | NGINX

教程： 使用 NGINX 为你的applications配置 OpenTelemetry

NGINX-F5-horiz-black-type-RGB 的一部分
阿卡什·阿南塔纳拉亚南 缩略图
阿卡什·阿南塔纳拉亚南
2024 年 1 月 18 日发布

如果您正在寻找一种更有效地跟踪 Web应用和基础设施的工具，OpenTelemetry 可能正是您所需要的。 通过使用现有的OpenTelemetry NGINX 社区模块来检测您的 NGINX 服务器，您可以收集指标、跟踪和日志，并更好地了解服务器的运行状况。 反过来，这使您能够解决问题并优化您的 Web应用以获得更好的性能。 但是，由于跟踪所需的性能开销，此现有的社区模块也会减慢服务器的响应时间。 此过程还会消耗额外的资源，增加 CPU 和内存的使用率。 此外，设置和配置模块可能会很麻烦。

NGINX 最近开发了原生的 OpenTelemetry 模块ngx_otel_module ，它彻底改变了请求处理性能的跟踪。 该模块利用遥测调用来监控应用请求和响应，从而增强跟踪功能。 该模块可以在 NGINX 配置文件中方便地设置和配置，从而具有高度的用户友好性。 这个新模块满足了 NGINX OSS 和 NGINX Plus 用户的需求。 它支持W3C上下文传播和OTLP/gRPC导出协议，使其成为优化性能的全面解决方案。

NGINX 原生 OpenTelemetry 模块是一个动态模块，不需要使用 NGINX Plus 进行任何额外的打包。 它提供一系列功能，包括 API 和键值存储模块。 这些功能协同工作，为监控和优化 NGINX Plus 实例的性能提供了完整的解决方案。 通过使用ngx_otel_module ，您可以深入了解 Web 应用程序的性能并采取措施进行改进。 我们强烈建议您探索ngx_otel_module以了解它如何帮助您获得更好的结果。

笔记： 您可以前往我们的GitHub 页面获取有关如何安装nginx_otel_module并开始使用的详细说明。

教程概述

在此博客中，您可以按照分步指南在 NGINX Plus 中配置 OpenTelemetry 并使用 Jaeger 工具收集和可视化跟踪。 OpenTelemetry是一个功能强大的工具，可以提供请求路径的全面视图，包括延迟、请求详细信息和响应数据等有价值的信息。 这对于优化性能和识别潜在问题非常有用。 为了简化，我们在一个实例中设置了 OpenTelemetry 模块、应用和 Jaeger，您可以在下图中看到。

打开遥测模块图
图 1： NGINX OpenTelemetry 架构概述

按照以下部分中的步骤完成本教程：

  • 先决条件
  • 部署 NGINX Plus 并安装 OpenTelemetry 模块
  • 部署 Jaeger 和echoapplication
  • 在 NGINX 中配置 OpenTelemetry 进行跟踪
  • 测试配置

先决条件

  • Linux/Unix 环境或任何兼容环境
  • NGINX Plus 订阅
  • 基本熟悉 Linux 命令行和 JavaScript
  • Docker
  • Node.js 19.x 或更高版本
  • 卷曲

部署 NGINX Plus 并安装 OpenTelemetry 模块

选择合适的环境对于成功部署 NGINX 实例至关重要。 本教程将引导您部署 NGINX Plus 并安装 NGINX 动态模块。

  1. 在支持的操作系统上安装 NGINX Plus 。
  2. 安装ngx_otel_module 。 将动态模块添加到 NGINX 配置目录以激活 OpenTelemetry：

    3. 加载模块/ngx_otel_module.so；

  3. 重新加载 NGINX 以启用该模块：

    4. nginx -t && nginx -s 重新加载

部署 Jaeger 和echoapplication

有多种选项可用于查看跟踪。 本教程使用Jaeger收集和分析 OpenTelemetry 数据。 Jaeger 提供了一个高效且用户友好的界面来收集和可视化跟踪数据。 数据收集后，您将部署一个简单的 Docker应用mendhak/http-https-echo 。 该应用以 JSON 格式返回 JavaScript 的请求属性。

  1. 使用docker-compose部署 Jaeger 和http-echo应用。 您可以通过复制以下配置并将其保存在您选择的目录中来创建一个docker-compose文件。

     

    版本： '3'

服务：
jaeger：
图像：jaegertracing/all-in-one:1.41
容器名称：jaeger
端口：
- “16686:16686”
- “4317:4317”
- “4318:4318”
环境：
      COLLECTOR_OTLP_ENABLED：true

http-echo：
图像：mendhak/http-https-echo
环境：
- HTTP_PORT=8888
- HTTPS_PORT=9999
端口：
- “4500:8888”
- “8443:9999”
  2. 安装 Jaeger 一体化跟踪和http-echo应用。 运行此命令：

    3. ‘docker-compose up -d’

  3. 运行docker ps -a命令来验证容器是否已安装。
    4. $docker ps -a
容器 ID 图像 命令 创建状态
端口名称

5cb7763439f8 jaegertracing/all-in-one:1.41 "/go/bin/all-in-one-…" 30 小时前 启动 30 小时 5775/udp、5778/tcp、14250/tcp、0.0.0.0:4317-4318->4317-4318/tcp、:::4317-4318->4317-4318/tcp、0.0.0.0:16686->16686/tcp、:::16686->16686/tcp、6831-6832/udp、14268/tcp jaeger

e55d9c00a158 mendhak/http-https-echo "docker-entrypoint.s…" 11 天前 启动 30 小时 8080/tcp, 8443/tcp, 0.0.0.0:8080->8888/tcp, :::8080->8888/tcp, 0.0.0.0:8443->9999/tcp, :::8443->9999/tcp ubuntu-http-echo-1

    现在，您只需在浏览器中输入http://localhost:16686端点即可访问 Jaeger。 请注意，您可能无法立即看到任何系统跟踪数据，因为它当前正在被发送到控制台。 但别担心！ 我们可以通过以 OpenTelemetry Protocol (OTLP) 格式导出跟踪来快速解决这个问题。 当我们配置 NGINX 将跟踪发送到 Jaeger 时，您将在下一节中学习如何执行此操作。

在 NGINX 中配置 OpenTelemetry 进行跟踪

本节将逐步向您展示如何使用键值存储在 NGINX Plus 中设置 OpenTelemetry 指令。 这种强大的配置可以实现对流量的精确监控和分析，从而让您优化应用程序的性能。 在本节结束时，您将对如何使用 NGINX OpenTelemetry 模块来跟踪应用程序的性能有深入的了解。

使用 NGINX 配置文件可以轻松设置和配置遥测收集。 通过ngx_otel_module ，用户可以访问一个强健的、协议感知的跟踪工具，该工具可以帮助快速识别和解决应用中的问题。 该模块是您的应用开发和管理工具集的一个宝贵补充，并将帮助您提高应用的性能。 要了解有关配置其他 OpenTelemetry 示例配置的更多信息，请参阅文档ngx_otel_module文档。

OpenTelemetry 指令和变量

NGINX 有新的指令，可以帮助您实现更加优化的 OpenTelemetry 部署，以满足您的特定需求。 这些指令旨在增强应用程序的性能并使其比以往更高效。

模块指令：

  1. otel_exporter – 设置 OpenTelemetry 数据的参数，包括端点、间隔、批次大小和批次数量。 这些参数对于成功导出数据至关重要，必须准确定义。
  2. otel_service_name – 设置您的 OpenTelemetry 资源的服务名称属性以改善组织和跟踪。
  3. otel_trace – 要启用或禁用 OpenTelemetry 跟踪，您现在可以通过指定变量来实现。 这为管理您的跟踪设置提供了灵活性。
  4. otel_span_name – OpenTelemetry 跨度的名称默认设置为请求的位置名称。 值得注意的是，该名称是可定制的，并且可以根据需要包含变量。

配置示例

以下是使用 NGINX Plus 键值存储在 NGINX 中配置 OpenTelemetry 的方法示例。 NGINX Plus 键值存储模块提供了一个有价值的用例，可以动态配置 OpenTelemetry 跨度和其他 OpenTelemetry 属性，从而简化跟踪和调试过程。

这是使用键值存储动态启用 OpenTelemetry 跟踪的示例：

http {
keyval "otel.trace" $trace_switch zone=name;

服务器 {
位置 / {
otel_trace $trace_switch;
otel_trace_context 注入;
proxy_pass http://backend;
}

位置 /api {
api write=on;
} 
}
}

接下来，下面是一个使用键值存储动态禁用 OpenTelemetry 跟踪的示例：

位置 /api {
api write=off;
}

以下是 NGINX OpenTelemetry 跨度属性配置的示例：

用户 nginx；
worker_processes 自动；
加载模块/ngx_otel_module.so；
错误日志/var/log/nginx 调试；
pid /var/run/nginx.pid;


事件 {
工作者连接1024；
}

http {
键值“otel.span.attr”$trace_attr zone=demo;
keyval_zone 区域=demo：64k 状态=/var/lib/nginx/state/demo.keyval；

log_format 主要'$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"'；
包括 mime.types；
默认类型应用/json；
上行回声 {
服务器本地主机：4500；
区域回声64k；
}
otel_服务名称 nginx；
otel_出口商 {
端点本地主机：4317；
}

服务器 {
听4000；
otel_trace 开启；
otel_span_name 酒店；
位置/城市{
proxy_set_header "连接" "" ;
proxy_set_header 主机 $host;
otel_span_attr 演示 $trace_attr；
otel_trace_context 注入；
代理密码<a href="http://echo;">http://echo;</a>
}
位置/api {
api写入=开启；
}
位置 = /dashboard.html {
根目录/usr/share/nginx/html；
}

}

}

要保存配置并重新启动 NGINX，请输入以下代码：

nginx -s 重新加载

最后，以下是在 NGINX Plus API 中添加 span 属性的方法：


curl -X POST -d '{"otel.span.attr": "<span 属性名称>"}' http://localhost:4000/api/6/http/keyvals/<区域名称>

测试配置

现在，您可以按照以下步骤测试您的配置。

  1. 要生成跟踪数据，首先打开终端窗口。 接下来，输入此命令来创建数据：

     

    $ curl -i 本地主机：4000/城市

    输出将如下所示：

                          HTTP/1.1 200 OK
服务器：nginx/1.25.3
日期： 2023 年 11 月 29 日星期三 20:25:04 GMT
内容类型：应用/json；字符集=utf-8
内容长度： 483
连接：保持活动
X-Powered-By： 快递
ETag： W/“1e3-2FytbGLEVpb4LkS9Xt+KkoKVW2I”

{
“path”：“/city”，
“headers”：{
“host”：“localhost”，
“connection”：“close”，
“user-agent”：“curl/7.81.0”，
“accept”：“*/*”，
“traceparent”： “00-66ddaa021b1e36b938b0a05fc31cab4a-182d5a6805fef596-00”
},
“方法”： “GET”，
“body”：“”，
“fresh”：false，
“hostname”：“localhost”，
“ip”：“::ffff:172.18.0.1”，
“ips”：[]，
“protocol”：“http”，
“query”：{}，
“subdomains”：[]，
“xhr”：false，
“os”：{
“hostname”：“e55d9c00a158”
}，
“connection”：{}
  2. 现在您要确保 OTLP 导出器正常运行并且您可以访问跟踪。 首先打开浏览器并通过http://localhost:16686访问 Jaeger UI。 页面加载后，单击标题栏中的“搜索”按钮。 从那里，从服务字段的下拉菜单中选择以NGINX启动的服务。 然后从名为Operation的下拉菜单中选择名为Otel的操作。 为了更容易识别任何问题，请单击“查找跟踪”按钮以可视化跟踪。
    3. Jaeger 仪表板
    图 2： Jaeger 仪表板
  3. 要获取特定跟踪的更详细、更全面的分析，请单击其中一个可用的单个跟踪。 这将为您提供有关所选跟踪的宝贵见解。 在下面的跟踪中，您可以查看 OpenTelemetry 指令 span 属性和跟踪的非指令，从而让您更好地了解手头的数据。
    • 演示 – OTel – OpenTelemetry 跨度属性名称
    • http.status_code 字段 – 200 – 表示创建成功
    • otel.library.name – nginx – OpenTelemetry 服务名称
    4. 图 3： OpenTelemetry 跟踪的详细分析

    在标签下您可以看到以下属性：

结论

NGINX 现在内置了对 OpenTelemetry 的支持，这对于在复杂的应用环境中跟踪请求和响应来说是一个重大的进展。 此功能简化了流程并确保了无缝集成，使开发人员更容易监控和优化他们的应用。

虽然 NGINX Plus R18 中引入的 OpenTracing 模块现在已被弃用，并将从 NGINX Plus R34 开始被删除，但在此之前它仍将在所有 NGINX Plus 版本中可用。 不过，建议使用NGINX Plus R29 中引入的OpenTelemetry 模块。

如果您是 NGINX Plus 新手，您可以立即开始30 天免费试用，或者联系我们讨论您的用例。

阅读有关 F5 NGINX 的更多博客文章 ›

“这篇博文可能引用了不再可用和/或不再支持的产品。 有关 F5 NGINX 产品和解决方案的最新信息，请探索我们的NGINX 产品系列。 NGINX 现在是 F5 的一部分。 所有之前的 NGINX.com 链接都将重定向至 F5.com 上的类似 NGINX 内容。”