チュートリアル: 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 がどのように役立つかを調べることを強くお勧めします。
注記： nginx_otel_moduleをインストールして開始する方法の詳細な手順については、 GitHub ページをご覧ください。
チュートリアルの概要
このブログでは、NGINX Plus で OpenTelemetry を設定し、Jaeger ツールを使用してトレースを収集および視覚化する方法について、ステップバイステップのガイドに従って説明します。 OpenTelemetryは、レイテンシ、リクエストの詳細、応答データなどの貴重な情報を含む、リクエストのパスの包括的なビューを提供する強力なツールです。 これは、パフォーマンスを最適化し、潜在的な問題を特定するのに非常に役立ちます。 簡素化のため、OpenTelemetry モジュール、アプリケーション、Jaeger をすべて 1 つのインスタンスに設定しました。下の図をご覧ください。
チュートリアルを完了するには、次のセクションの手順に従ってください。
- 前提条件
- NGINX Plus をデプロイし、OpenTelemetry モジュールをインストールする
- Jaegerと
echoアプリケーションをデプロイする - トレース用に NGINX で OpenTelemetry を構成する
- 構成をテストする
前提条件
- Linux/Unix環境、または互換性のある環境
- NGINX Plusサブスクリプション
- Linux コマンドラインと JavaScript に関する基本的な知識
- ドッカー
- Node.js 19.x 以降
- カール
NGINX Plus をデプロイし、OpenTelemetry モジュールをインストールする
NGINX インスタンスを正常にデプロイするには、適切な環境を選択することが重要です。 このチュートリアルでは、NGINX Plus のデプロイと NGINX 動的モジュールのインストールについて説明します。
- サポートされているオペレーティング システムにNGINX Plus をインストールします。
ngx_otel_moduleをインストールします。 OpenTelemetry を有効にするには、NGINX 構成ディレクトリに動的モジュールを追加します。- モジュールを有効にするには、NGINX をリロードします。
モジュールモジュール/ngx_otel_module.soをロードします。
nginx -t && nginx -s リロード
Jaegerとechoアプリケーションをデプロイする
トレースを表示するにはさまざまなオプションがあります。 このチュートリアルでは、 Jaeger を使用して OpenTelemetry データを収集および分析します。 Jaeger は、トレース データを収集して視覚化するための効率的でユーザー フレンドリーなインターフェイスを提供します。 データ収集後、シンプルな Docker アプリケーションであるmendhak/http-https-echo をデプロイします。 このアプリケーションは、JavaScript のリクエスト属性を JSON 形式で返します。
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"- Jaeger オールインワン トレースおよび
http-echoアプリケーションをインストールします。 次のコマンドを実行します: - docker
ps -aコマンドを実行して、コンテナがインストールされているかどうかを確認します。
'docker-compose up -d'
$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) 形式でエクスポートすることで、この問題をすぐに解決できます。 次のセクションで、トレースを Jaeger に送信するように NGINX を設定するときに、これを行う方法を学習します。
トレース用に NGINX で OpenTelemetry を構成する
このセクションでは、キー値ストアを使用して NGINX Plus で OpenTelemetry ディレクティブを設定する方法を段階的に説明します。 この強力な構成により、トラフィックの正確な監視と分析が可能になり、アプリケーションのパフォーマンスを最適化できます。 このセクションの終わりまでに、NGINX OpenTelemetry モジュールを利用してアプリケーションのパフォーマンスを追跡する方法をしっかりと理解できるようになります。
NGINX 構成ファイルを使用すると、テレメトリ収集のセットアップと構成が簡単になります。 ngx_otel_moduleを使用すると、ユーザーは、アプリケーションの問題を迅速に特定して解決するのに役立つ、堅牢でプロトコル対応のトレース ツールにアクセスできます。 このモジュールは、アプリケーション開発および管理ツールセットに貴重な追加機能として追加され、アプリケーションのパフォーマンスを向上させるのに役立ちます。 その他の OpenTelemetry サンプル構成の構成の詳細については、ドキュメントngx_otel_moduleドキュメントを参照してください。
OpenTelemetry ディレクティブと変数
NGINX には、特定のニーズに合わせてさらに最適化された OpenTelemetry 展開を実現するのに役立つ新しいディレクティブがあります。 これらのディレクティブは、アプリケーションのパフォーマンスを向上させ、これまで以上に効率化するために設計されました。
モジュールディレクティブ:
otel_exporter–エンドポイント、間隔、バッチ サイズ、バッチ カウントなど、OpenTelemetry データのパラメータを設定します。 これらのパラメータはデータのエクスポートを成功させるために非常に重要であり、正確に定義する必要があります。otel_service_name– 組織化と追跡を改善するために、OpenTelemetry リソースのサービス名属性を設定します。otel_trace– OpenTelemetry トレースを有効または無効にするには、変数を指定できるようになりました。 これにより、トレース設定を柔軟に管理できるようになります。otel_span_name– OpenTelemetry スパンの名称は、デフォルトでリクエストの場所名として設定されます。 名前はカスタマイズ可能であり、必要に応じて変数を含めることができることに注意してください。
設定例
NGINX Plus キー値ストアを使用して NGINX で OpenTelemetry を構成する方法の例を次に示します。 NGINX Plus キー値ストア モジュールは、OpenTelemetry スパンやその他の 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 トレースを動的に無効にする例を示します。
場所 /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;
アップストリーム 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 リロード
最後に、NGINX Plus API に span 属性を追加する方法は次のとおりです。
curl -X POST -d '{"otel.span.attr": "<span 属性名>"}' http://localhost:4000/api/6/http/keyvals/<ゾーン名>
構成をテストする
以下の手順に従って設定をテストできます。
- トレース データを生成するには、まずターミナル ウィンドウを開きます。 次に、次のコマンドを入力してデータを作成します。
$ curl -i ローカルホスト:4000/都市出力は次のようになります。
HTTP/1.1 200 OK サーバー: nginx/1.25.3 日付: 2023 年 11 月 29 日水曜日 20:25:04 GMT コンテンツ タイプ: application/json; charset=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": {} - ここで、OTLP エクスポーターが正しく機能しており、トレースにアクセスできることを確認します。 まず、ブラウザを開いて、
http://localhost:16686で Jaeger UI にアクセスします。 ページが読み込まれたら、タイトルバーにある「検索」ボタンをクリックします。 そこから、 [サービス]フィールドのドロップダウン メニューからNGINXで始まるサービスを選択します。 次に、 「操作」というドロップダウン メニューから「Otel」という操作を選択します。 問題を簡単に特定できるようにするには、 「トレースの検索」ボタンをクリックしてトレースを視覚化します。 - 特定のトレースのより詳細で包括的な分析にアクセスするには、利用可能な個々のトレースのいずれかをクリックします。 これにより、選択したトレースに関する貴重な洞察が得られます。 以下のトレースでは、OpenTelemetry ディレクティブの span 属性とトレースの非ディレクティブの両方を確認できるため、手元のデータをよりよく理解できます。
デモ – OTel– OpenTelemetry span 属性名http.status_code フィールド – 200– 作成が成功したことを示しますotel.library.name – nginx– OpenTelemetry サービス名
タグの下には、次の属性が表示されます。
結論
NGINX には現在、複雑なアプリケーション環境でのリクエストと応答をトレースするための重要な開発である OpenTelemetry の組み込みサポートがあります。 この機能によりプロセスが合理化され、シームレスな統合が保証されるため、開発者はアプリケーションを監視および最適化することがはるかに容易になります。
NGINX Plus R18 で導入された OpenTracing モジュールは現在非推奨となっており、NGINX Plus R34 以降では削除されますが、それまではすべての NGINX Plus リリースで引き続き利用できます。 ただし、 NGINX Plus R29 で導入されたOpenTelemetry モジュールを使用することをお勧めします。
NGINX Plus を初めてご利用になる場合は、今すぐ30 日間の無料トライアルを開始するか、お問い合わせの上、使用事例についてご相談ください。
「このブログ投稿には、入手できなくなった製品やサポートされなくなった製品が参照されている場合があります。 利用可能な F5 NGINX 製品およびソリューションに関する最新情報については、 NGINX 製品ファミリーをご覧ください。 NGINX は現在 F5 の一部です。 以前の NGINX.com リンクはすべて、F5.com の同様の NGINX コンテンツにリダイレクトされます。"