チュートリアル：NGINXを使用してアプリケーションにOpenTelemetryを設定する

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を使用することを強くお勧めします。

注：ngx_otel_moduleのインストールおよび使用方法については、当社のGitHubページをご覧ください。

チュートリアルの概要

このブログでは、NGINX PlusでOpenTelemetryを設定し、Jaegerツールを使ってトレースを収集および可視化するためのステップバイステップの手順を紹介します。OpenTelemetryは、遅延、リクエストの詳細、レスポンスデータなどの貴重な情報を含む、リクエストのパスに関する包括的なビューを提供する強力なツールです。これは、パフォーマンスの最適化と潜在的な問題の特定に非常に役立ちます。ここでは、わかりやすくするために、OpenTelemetryモジュール、アプリケーションおよびJaeger all-in-oneインスタンスを以下の図のように設定しています。

図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;

3. NGINXをリロードしてモジュールを有効化

nginx -t && nginx -s reload

Jaegerとechoアプリケーションの導入

トレースの表示には、さまざまなオプションを使用できます。このチュートリアルでは、Jaegerを使ってOpenTelemetryデータを収集および分析します。Jaegerはトレーシングデータを収集および可視化するための効率的で使いやすいインターフェースを提供します。データ収集後、シンプルなDockerアプリケーションであるmendhak/http-https-echoを導入します。このアプリケーションはJavaScriptのリクエスト属性をJSON形式で返します。

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"
   
   

2. Jaeger all-in-one tracingおよびhttp-echoアプリケーションをインストールするには、以下のコマンドを実行します。

'docker-compose up -d'

3. 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 Protocol（OTLP）フォーマットでトレースをエクスポートすることで、すぐに解決できます。次のセクションではトレースがJaegerに送信されるようにNGINXを設定する方法について説明します。

トレーシングのためのNGINXでのOpenTelemetryの設定

このセクションではキーバリューストアを使用してNGINX PlusでOpenTelemetryディレクティブを設定するためのステップバイステップの手順を紹介します。この強力な設定によりトラフィックの正確な監視と分析が可能になり、アプリケーションのパフォーマンスを最適化できます。このセクションを完了すると、NGINX OpenTelemetryモジュールを利用したアプリケーションパフォーマンスのトレースについてしっかりと理解できるようになります。

テレメトリ収集の設定と構成はNGINX設定ファイルで簡単に行うことができます。ngx_otel_moduleを使用することでアプリケーションの問題の迅速な特定と解決に役立つ堅牢なプロトコルアウェアのトレーシングツールにアクセスできます。このモジュールはアプリケーションの開発および管理ツールセットに貴重な付加価値を与え、アプリケーションのパフォーマンス向上に役立ちます。その他のOpenTelemetry設定例について詳しくは、ngx_otel_moduleに関するドキュメントを参照してください。

OpenTelemetryディレクティブと変数

NGINXの新しいディレクティブはOpenTelemetry導入を特定のニーズに合わせてさらに最適化するときに役立ちます。これらのディレクティブを使用することでアプリケーションのパフォーマンスを向上させ、これまで以上に効率化できます。

モジュールディレクティブ：

1. otel_exporter – endpoint、interval、batch sizeおよびbatch countなど、OpenTelemetryデータのパラメータを設定します。これらのパラメータは、データのエクスポートを成功させるために不可欠であり、正確に定義する必要があります。
2. otel_service_name – OpenTelemetryリソースのサービス名属性を設定して、編成やトレースを向上できます。
3. otel_trace – 変数を指定してOpenTelemetryトレーシングを有効/無効にすることができます。これにより、トレーシング設定を柔軟に管理できます。
4. otel_span_name – デフォルトではOpenTelemetryのspanの名前がリクエストのロケーション名として設定されます。この名前はカスタマイズ可能で、必要に応じて変数を含めることができます。

設定例

以下は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": {}
   
   

2. 次に、OTLPエクスポーターが正しく機能していて、トレースにアクセスできることを確認します。まずブラウザを開き、Jaeger UI（http://localhost:16686）にアクセスします。ページがロードされたら、タイトルバーにあるSearchボタンをクリックします。そこから、ServiceフィールドのドロップダウンメニューからNGINXで始まるサービスを選択します。次に、OperationドロップダウンメニューからOtelという名前のOperationを選択します。問題の特定を簡単にするために、Find Tracesボタンをクリックしてトレースを可視化します。

   図2：Jaegerダッシュボード

3. 特定のトレースに関するより詳しく、より包括的な分析にアクセスするには利用可能な個々のトレースのいずれかをクリックします。これにより選択したトレースに関する貴重なインサイトを得ることができます。以下に示すトレースでは、OpenTelemetryディレクティブのspan属性とトレースの非ディレクティブの両方を確認でき、対象のデータをより理解できます。

   [caption id="attachment_71107" align="aligncenter" href="/wp-content/uploads/2024/01/Screenshot-2024-01-08-at-4.14.05 PM-1.png"> 図3：OpenTelemetryトレースの詳細な分析[/caption]

   • demo – OTel（OpenTelemetryのspan属性の名前）
   • http.status_code field – 200（作成に成功したことを示します）
   • otel.library.name – nginx（OpenTelemetryサービス名）

 

Tagsの下で、以下の属性を確認できます。

 

まとめ

NGINXは複雑なアプリケーション環境におけるリクエストとレスポンスをトレーシングするために開発されたOpenTelemetryをサポートするようになりました。この機能により、プロセスが合理化され、シームレスな統合が保証されるので、開発者はアプリケーションをより簡単に監視および最適化できます。

NGINX Plus R18で導入されたOpenTracingモジュールは現在では非推奨となっていて、NGINX Plus R34から削除される予定ですが、それまではすべてのNGINX Plusリリースで利用できます。ただし、NGINX Plus R29で導入されたOpenTelemetryモジュールを使用することをお勧めします。

NGINX Plusをまだご利用いただいていない方は、30日間無料トライアルで今すぐ始めるか、弊社までお問い合わせいただき使用事例をお聞かせください。