教程：使用NGINX为应用配置OpenTelemetry

NGINX | 2024年1月18日
Akash Ananthanarayanan
Akash Ananthanarayanan技术营销经理 | F5 NGINX

如果希望更有效地追踪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和echo应用
  • 在NGINX中配置OpenTelemetry以进行跟踪
  • 测试配置

先决条件

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

部署NGINX Plus并安装OpenTelemetry模块

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

  1. 安装NGINX Plus，使用受支持的操作系统。
  2. 安装ngx_otel_module。将该动态模块添加到NGINX配置目录，以启用OpenTelemetry：

load_module modules/ngx_otel_module.so;

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

nginx -t && nginx -s reload

部署 Jaeger 和echo应用

可通过多种方式查看跟踪数据。本教程使用Jaeger收集和分析OpenTelemetry数据。Jaeger提供高效易用的界面，用于收集和可视化跟踪数据。数据收集完成后，将部署mendhak/http-https-echo，这是一个简单的Docker应用。该应用以JSON格式返回JavaScript请求的属性。

  1. 使用“docker-compose”部署Jaeger和“http-echo”应用。复制以下配置并将其保存到所选目录，即可创建“docker-compose”文件。
version: '3'

Services:
  jaeger:
    image: jaegertracing/all-in-one:1.41
    container_name: jaeger
    ports:
      - "16686:16686"
      - "4317:4317"
      - "4318:4318"
    environment:
      COLLECTOR_OTLP_ENABLED: true

  http-echo:
    image: mendhak/http-https-echo
    environment:
        - HTTP_PORT=8888
        - HTTPS_PORT=9999
    ports:
        - "4500:8888" 
        - "8443:9999"
  1. 要安装Jaeger一体化追踪和http-echo应用，请运行以下命令：

'docker-compose up -d'

  1. 运行docker ps -a命令，验证容器是否已安装。
$docker ps -a
CONTAINER ID   IMAGE                           COMMAND                  CREATED        STATUS
PORTS                                                                                                                                                                   NAMES

5cb7763439f8   jaegertracing/all-in-one:1.41   "/go/bin/all-in-one-…"   30 hours ago   Up 30 hours   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 days ago    Up 30 hours   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协议（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数据的参数，包括endpoint、interval、batch size和batch count。这些参数对于成功导出数据至关重要，必须准确定义。
  2. otel_service_name，设置OpenTelemetry资源的服务名称属性，以便更好地组织和跟踪资源。
  3. otel_trace：现在可以通过指定变量来启用或禁用OpenTelemetry跟踪，从而更灵活地管理跟踪设置。
  4. otel_span_name：默认情况下，OpenTelemetry span 的名称会设置为请求的 location 名称。该名称可自定义，并可根据需要包含变量。

配置示例

以下示例展示了如何使用NGINX Plus键值存储在NGINX中配置OpenTelemetry。NGINX Plus键值存储模块支持动态配置OpenTelemetry span及其他OpenTelemetry属性，从而简化跟踪和调试流程。

以下示例展示了如何使用键值存储动态启用OpenTelemetry跟踪：

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

      server {
          location / {
              otel_trace $trace_switch;
              otel_trace_context inject;
              proxy_pass http://backend;
          }

          location /api {
              api write=on;
          } 
      }
  }

接下来，以下示例展示了如何使用键值存储动态禁用OpenTelemetry跟踪：

location /api {
              api write=off;
          }

以下是一个NGINX OpenTelemetry span属性配置示例：

user  nginx;
worker_processes  auto;
load_module modules/ngx_otel_module.so;
error_log /var/log/nginx debug;
pid   /var/run/nginx.pid;


events {
    worker_connections  1024;
}

http {
    keyval "otel.span.attr" $trace_attr zone=demo;
    keyval_zone zone=demo:64k  state=/var/lib/nginx/state/demo.keyval;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    include       mime.types;
    default_type  application/json;
    upstream echo {
        server localhost:4500;
        zone echo 64k;
    }
    otel_service_name nginx;
    otel_exporter {
           endpoint localhost:4317;
        }

    server {
       listen       4000;
       otel_trace on;
       otel_span_name otel;
       location /city {
            proxy_set_header   "Connection" "" ;
            proxy_set_header Host $host;
            otel_span_attr demo $trace_attr;
            otel_trace_context inject;
            proxy_pass http://echo;
       }
       location /api {
           api write=on;
       }
       location = /dashboard.html {
        root /usr/share/nginx/html;
    }
       
  }

}

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

nginx -s reload

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


curl -X POST -d '{"otel.span.attr": "<span attribute name>"}' http://localhost:4000/api/6/http/keyvals/<zone name>

测试配置

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

  1. 要生成跟踪数据，请先打开终端窗口。然后输入以下命令来创建数据：$ curl -i localhost:4000/city输出将如下所示：
                      HTTP/1.1 200 OK
Server: nginx/1.25.3
Date: Wed, 29 Nov 2023 20:25:04 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 483
Connection: keep-alive
X-Powered-By: Express
ETag: W/"1e3-2FytbGLEVpb4LkS9Xt+KkoKVW2I"

{
"path": "/city",
"headers": {
"host": "localhost",
"connection": "close",
"user-agent": "curl/7.81.0",
"accept": "*/*",
"traceparent": "00-66ddaa021b1e36b938b0a05fc31cab4a-182d5a6805fef596-00"
},
"method": "GET",
"body": "",
"fresh": false,
"hostname": "localhost",
"ip": "::ffff:172.18.0.1",
"ips": [],
"protocol": "http",
"query": {},
"subdomains": [],
"xhr": false,
"os": {
"hostname": "e55d9c00a158"
},
"connection": {}
  1. 现在，需要确保OTLP导出器正常运行，并且可以访问该跟踪。首先打开浏览器并访问Jaeger UI：http://localhost:16686。页面加载后，单击标题栏中的“搜索”按钮。然后，从“服务”字段的下拉菜单中选择名称以“NGINX”开头的服务。接着，从“操作”下拉菜单中选择名为“Otel”的操作。为便于发现问题，单击“查找跟踪”按钮以可视化该跟踪。

图 2：Jaeger 仪表板

  1. 要查看特定跟踪的更详细、更全面的分析，请点击任一可用的单条跟踪。这有助于深入了解所选跟踪。在下方的跟踪中，可以查看OpenTelemetry指令的跨度属性以及跟踪中的非指令部分，从而更好地理解相关数据。
    • demo – OTel：OpenTelemetry跨度属性名称
    • http.status_code字段：200，表示创建成功
    • otel.library.name – nginx，OpenTelemetry服务名称

图3：OpenTelemetry跟踪的详细分析

在“标签”下，可以看到以下属性：

总结

NGINX现已内置支持OpenTelemetry，这一重要进展有助于在复杂的应用环境中跟踪请求和响应。此功能简化了相关流程并确保无缝集成，让开发人员能够更轻松地监控和优化应用。

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

如果您刚开始使用NGINX Plus，可以立即开始30天免费试用，也可以联系我们，讨论您的使用场景。

分享
精选博客文章
云原生技术、平台工程和AI的当前趋势使用F5 NGINX One对应用和API交付进行全生命周期管理简化现代应用交付：F5 NGINX One 九个月回顾
标签： OpenTelemetry (OTel), Visibility

关于作者

Akash Ananthanarayanan
Akash Ananthanarayanan技术营销经理 | F5 NGINX

Akash Ananthanarayanan 的更多博客文章

相关博客文章

NGINX Plus R26 正式发布
NGINX | 2022/02/15

NGINX Plus R26 正式发布

NGINX Plus R26通过缓存JSON Web密钥集加快JWT验证，并强化TLS握手，从而提升安全性。NGINX JavaScript的新功能包括增强对异步函数的支持，以及实现WebCrypto API。

使用NGINX App Protect DoS保护gRPC应用，抵御严重的DoS攻击
NGINX | 2022/02/10

使用NGINX App Protect DoS保护gRPC应用，抵御严重的DoS攻击

gRPC具备开发人员设计和部署现代应用所需的速度与灵活性，但其开放性也使其极易受到第7层DoS攻击。NGINX App Protect DoS可保护gRPC应用免受此类破坏性攻击。

Ingress Controller 选型指南（第 2 部分）：风险与面向未来的规划
NGINX | 2021/09/13

Ingress Controller 选型指南（第 2 部分）：风险与面向未来的规划

了解选择错误的Ingress控制器可能带来的风险，以及如何从关键方面着手，让您的选择更好地适应未来需求。

NGINX Plus R19 正式发布
NGINX | 2019/09/03

NGINX Plus R19 正式发布

NGINX Plus R19扩展了监控功能，不仅提供更多指标，还新增了指标分析方式；增加试运行模式，用于测试限速效果；增强键值存储，以支持IP地址范围；并使限速更加动态。

NGINX现已正式加入F5
NGINX | 2019/05/09

NGINX现已正式加入F5

NGINX现已正式成为F5的一部分。Gus Robertson现任F5 NGINX业务部门负责人。他阐述了两家公司在人才、文化和愿景方面融合的价值，以及双方将如何携手增强NGINX的开源产品和商业产品。

使用NGINX和NGINX Plus实现高性能缓存
NGINX | 2016/08/24

使用NGINX和NGINX Plus实现高性能缓存

我将介绍NGINX在内容缓存和性能方面的工作原理，并分享一些控制NGINX内容缓存方式的技巧。

交付和保护每一个应用
F5 应用交付和安全解决方案确保部署在任何位置的每个应用和 API 都快速、可用且安全。了解如何与我们合作，始终提供卓越体验。
关注我们