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つのインスタンスにセットアップしています。以下の図でご確認いただけます。
図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動的モジュールのインストール手順を説明します。
- NGINX Plusをインストールします。対象は、サポート対象のオペレーティングシステムです。
- Install
ngx_otel_moduleをインストールします。OpenTelemetryを有効にするには、NGINXの設定ディレクトリにダイナミックモジュールを追加します：
load_module modules/ngx_otel_module.so;
- モジュールを有効にするため、NGINXを再読み込みします：
nginx -t && nginx -s reload
Jaegerとechoアプリケーションをデプロイ
トレースを表示する方法には、さまざまな選択肢があります。このチュートリアルでは、Jaegerを使用してOpenTelemetryデータを収集、分析します。Jaegerは、トレースデータを効率的かつ簡単に収集、可視化できるインターフェースを提供します。データを収集した後、シンプルなDockerアプリケーションであるmendhak/http-https-echoをデプロイします。このアプリケーションは、JavaScriptのリクエスト属性をJSON形式で返します。
- Use
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"- Jaeger all-in-oneトレーシングと
http-echoアプリケーションをインストールするには、次のコマンドを実行します。
'docker-compose up -d'
- コンテナがインストールされているか確認するには、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 documentation」をご覧ください。
OpenTelemetryのディレクティブと変数
NGINXには、特定のニーズに合わせてOpenTelemetryの導入をさらに最適化するのに役立つ新しいディレクティブが用意されています。これらのディレクティブは、アプリケーションのパフォーマンスを向上させ、これまで以上に効率化できるよう設計されています。
モジュールディレクティブ：
otel_exporter– OpenTelemetryデータのパラメーターを設定します。これには、endpoint、interval、batch size、batch countが含まれます。これらのパラメーターは、データを正常にエクスポートするうえで重要であり、正確に定義する必要があります。otel_service_name– OpenTelemetryリソースの整理と追跡を改善するために、サービス名属性を設定します。otel_trace– 変数を指定することで、OpenTelemetryトレーシングを有効または無効にできるようになりました。これにより、トレーシング設定を柔軟に管理できます。otel_span_name– OpenTelemetryスパンの名前には、デフォルトでリクエストのlocation名が設定されます。この名前はカスタマイズでき、必要に応じて変数を含めることができます。
設定例
NGINX Plusのキー・バリューストアを使用して、NGINXでOpenTelemetryを構成する方法の例を紹介します。NGINX Plusのキー・バリューストアモジュールを活用すると、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のスパン属性設定の例です。
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でスパン属性を追加する方法を示します。
curl -X POST -d '{"otel.span.attr": "<span attribute name>"}' http://localhost:4000/api/6/http/keyvals/<zone name>
設定をテストする
これで、以下の手順に従って構成をテストできます。
- トレースデータを生成するには、まずターミナルウィンドウを開きます。次に、以下のコマンドを入力してデータを作成します。
$ 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": {}- 次に、OTLPエクスポーターが正しく機能し、トレースにアクセスできることを確認します。まず、ブラウザーを開き、Jaeger UI（
http://localhost:16686）にアクセスします。ページが読み込まれたら、タイトルバーにある［Search］ボタンをクリックします。次に、［Service］フィールドのドロップダウンメニューから、名前が「NGINX」で始まるサービスを選択します。続いて、［Operation］ドロップダウンメニューから「Otel」という名前のオペレーションを選択します。問題を特定しやすくするため、［Find Traces］ボタンをクリックしてトレースを可視化します。
図2：Jaegerダッシュボード
- 特定のトレースをより詳細かつ包括的に分析するには、表示されている個々のトレースのいずれかをクリックします。選択したトレースに関する有用な情報を確認できます。以下のトレースでは、OpenTelemetryディレクティブのスパン属性と、トレースの非ディレクティブ部分の両方を確認でき、対象データへの理解を深めることができます。
demo – OTel– OpenTelemetryスパン属性名http.status_codeフィールド – 200– 正常に作成されたことを示しますotel.library.name – nginx– OpenTelemetryサービス名
図3：OpenTelemetryトレースの詳細分析
［Tags］には、次の属性が表示されます。
まとめ
NGINXはOpenTelemetryを標準でサポートするようになりました。これは、複雑なアプリケーション環境でリクエストとレスポンスをトレースするうえで大きな進展です。この機能によりプロセスが効率化され、シームレスな統合が実現するため、開発者はアプリケーションの監視と最適化をより簡単に行えます。
NGINX Plus R18で導入されたOpenTracingモジュールは現在非推奨となっており、NGINX Plus R34以降で削除されますが、それまではすべてのNGINX Plusリリースで引き続き利用できます。ただし、NGINX Plus R29で導入されたOpenTelemetryモジュールの使用を推奨します。
NGINX Plusを初めてご利用になる場合は、今すぐ30日間の無料トライアルを開始するか、ユースケースについてご相談ください。
著者について
関連するブログ記事
チュートリアル：NGINXを使用してアプリケーション向けにOpenTelemetryを構成する
OpenTelemetryを使用してNGINXサーバーの状態と健全性をより明確に把握することで、問題のトラブルシューティングを行い、Webアプリケーションのパフォーマンスを向上できます。
AkitaのNGINX Plus認定モジュールでAPIエンドポイントの問題を特定・修正
Akita SoftwareのAPIオブザーバビリティ向け新しいNGINX Plus Certified Moduleを活用して、APIエンドポイントの問題をより迅速に特定し、修正できます。
JavaプロジェクトをスキャフォールディングしてKubernetesネイティブアプリを構築する方法
Red HatのシニアプリンシパルデベロッパーアドボケイトであるDaniel Oh氏が、Javaプロジェクトをゼロから構築するためのひな形を作成し、Kubernetesネイティブアプリケーションとしてビルドする方法を解説します。
F5 NGINXaaS for Azureのご紹介：Microsoft Azureでネイティブに利用できるSaaS型ロードバランシング
NGINXaaS for Azureは、NGINX PlusをAzureネイティブのSaaSとして利用できるサービスです。NGINXの設定を容易にリフト＆シフトできるため、クラウド導入とモダンアプリの展開を加速できます。
SELinuxでNGINXおよびNGINX Plusを使用する
Red Hat Enterprise Linux（RHEL）および関連ディストリビューションでSecurity-Enhanced Linux（SELinux）を有効にすると、デフォルト設定によりNGINXとNGINX Plusの一部の操作が制限されます。この記事では、すべての機能を利用できるようにSELinuxの設定を変更する方法について説明します。
NGINX PlusによるAWS Auto Scalingグループの負荷分散
新しいnginx-asg-sync統合ソフトウェアにより、NGINX PlusはAWS Auto Scalingグループの負荷を直接分散できるため、クラウドでの負荷分散がさらに柔軟になります