NGINX のモニター

NGINX センサーと NGINX トレースでは、必要なOSの要件が異なります。

NGINX センサーについて、対応OSは各ホストエージェントの要件に準じています。詳細は、各ホストエージェントの「対応OS」セクション（例： Linux の対応OS ）でご確認いただけます。

NGINX のトレース機能については、以下のオペレーティングシステムがサポートされています：

CPPセンサー（ 1.12.0 以降）は、 Debian 10および Ubuntu 20.04 のサポートを終了します。

CPPセンサー（ 1.11.0 以降）は、 CentOS 7、 CentOS 8、 CentOS Stream 8、 Alpine 3.10、および RHEL 7への対応を終了します。

NGINX センサーと NGINX トレースには、それぞれ異なるバージョンおよびプラットフォームの要件があります。 詳細については、 「 NGINX の対応バージョンとプラットフォーム」 をご覧ください。

以下の表は、最新のサポート対象バージョンとサポート方針を示しています：

サポートポリシーに関する詳細については、 「センサーのサポート戦略」 を参照してください。

NGINX のトレース機能では、以下の Docker コンテナイメージがサポートされています：

CPPセンサー（ 1.12.0 以降）では、コンテナイメージのサポートが openresty/openresty CentOS based終了します。

Instana に NGINX のプロセスを自動的に収集・監視させるには、次のようにメトリクスの収集を有効にする必要があります：

• PID
• ワーカー・プロセス数
• ワーカー接続数
• 開始時刻
• バージョン
• ビルド (*)
• アドレス (*)
• 生成 (*)
• PID (*)

• 要求
• 接続数
• プロセス (*)
• SSL (*)
• キャッシュ (*)
• サーバー・ゾーン (*)
• アップストリーム (*)

各センサーには、着信メトリックに対して継続的に評価され、ユーザーの影響に依存する問題またはインシデントを発生させるために使用される、キュレートされたヘルス・シグネチャーの知識ベースがあります。

組み込みイベントは、エンティティのヘルスシグネチャの異常に基づいて課題やインシデントをトリガーし、 カスタムイベントは、特定のエンティティの個々のメトリクスのしきい値に基づいて課題やインシデントをトリガーします。

NGINX センサーの組み込みイベントに関する詳細については、「 組み込みイベントのリファレンス 」を参照してください。

NGINX のトレース機能を使用するには、以下の設定値を指定する必要があります：

• NGINX Ingressの ConfigMap に、以下の項目を追加してください：

    data:
      enable-opentracing: "true"
      zipkin-collector-host: $HOST_IP
      zipkin-collector-port: "42699"
   

• NGINX のPod Specに、次のように環境変数を追加してください（すでに POD_NAME と が含まれている POD_NAMESPACEはずです）：

  env:
     - name: HOST_IP
       valueFrom:
       fieldRef:
           fieldPath: status.hostIP
   

注:

• Ingressの NGINX は、環境変数`$ENV POD_NAMESPACE `と` POD_NAME $ENV`を自動的に設定します。 したがって、 NGINX のPod Specに および POD_NAMESPACE 環境 POD_NAME 変数を追加する必要はありません。

• この構成では、 Kubernetes DownwardAPI を使用して、ホスト IP を環境変数 (HOST_IP) として使用可能にします。これにより、 ConfigMap がこれを取得します。

• ポートは、 Instana エージェントのポートである42699に固定できます。

• サービスは、デフォルトの nginx として指定するか、パラメーター zipkin-service-nameで上書きする必要があります。このパラメーターは、 ConfigMapで構成できます。

NGINX Ingress の詳細については、 Kubernetes Ingress NGINX のドキュメントを参照してください。

セットアップに NGINX のトレース機能をインストールするには、以下の手順を実行してください：

1. お使いの NGINX のバージョンに合ったバイナリファイルを入手してください。
2. バイナリファイルを、 NGINX サーバーからアクセス可能な場所にコピーしてください。
3. NGINX の設定を編集します。
4. NGINX プロセスを再起動するか、コマンド reload を送信して設定の再読み込みを実行します

NGINX でサーバーレストレースを設定するには、以下の手順を実行してください：

1. お使いの NGINX のバージョンに合わせて、サーバーレストレースング用の Instana バイナリファイルをダウンロードしてください。 NGINX HTTP のトレースモジュールは、 モジュ nginx-opentracing ールを基盤としています。 Instana のこのバリエーションは、使いやすさの向上、独自のバグ修正、および機能の拡充を目的としてカスタマイズされています。 Instana のバイナリファイルについては、 NGINX Distributed Tracing Binaries を参照してください。

2. serverless-tracing用のバイナリファイルをコピーする：

   1. ステップ1でダウンロード・展開したバイナリファイルから、バージョンに応じて「libinstana_sensor.soモジュールのOpenSSLバリアントを選択する。 コマンド 'openssl version を使ってOpenSSLのバージョンを取得する。 OpenSSL 3.0.22の出力例を以下に示す：

      # openssl version
      OpenSSL 3.0.2 15 Mar 2022 (Library: OpenSSL 3.0.2 15 Mar 2022)
       

      OpenSSL 3.x.xの場合は、「libinstana_sensor_ssl3x.soモジュールを選択する。

      • OpenSSL 1.1.1fの出力例を以下に示す：

        # openssl version
        OpenSSL 1.1.1f  31 Mar 2020
         

        OpenSSL 1.1.xの場合は、「libinstana_sensor_ssl1.1x.soモジュールを選択する。

   2. NGINX プロセスがアクセスできるファイルシステムに配置してください。 NGINX プロセスには、. libinstana_sensor.soに対する読み取り権限が必要です。

   3. NGINX がコンテナ内で実行されているのではなく、ホストOS上で直接実行されている場合は、2つの Instana バイナリを、他の NGINX モジュールが格納されているディレクトリにコピーしてください。

   4. NGINX がモジュールを検索する場所を確認するには、コマンド nginx -V を実行し、設定 --modules-path オプションを探してください。

   5. 以下のステップのいずれかを実行します。

      • コンテナ環境では、これらのファイルをコンテナ・イメージに追加するか、コンテナにボリュームとしてマウントする。
      • docker のマウントポイントについては、 Docker のバインドマウントを参照してください。
      • 「 Kubernetes 」については、 『 Kubernetes 』の「ボリュームをポッドにマウントする」 を参照してください。

3. 環境変数を設定します。

   1. コマンド systemctl show -p FragmentPath nginx の出力に表示された NGINX サービスファイルを検索してください。 出力例を以下に示す：

      # systemctl show -p FragmentPath nginx
      FragmentPath=/lib/systemd/system/nginx.service
       

   2. NGINX のサービスファイルの セクション Service に、環境 INSTANA_AGENT_KEY 変数 INSTANA_ENDPOINT_URL と を追加します。 環境変数に関する詳細については、 「サーバーレス監視の環境変数」 を参照してください。

   3. 次の例のように、「INSTANA_ENDPOINT_URL」と「INSTANA_AGENT_KEY実際の値に置き換える：

      [Service]
      Environment="INSTANA_ENDPOINT_URL=https://XXX.instana.io/serverless/"
      Environment="INSTANA_AGENT_KEY=*****"
       

4. サーバーレストレースング用に NGINX の設定を編集します：

   1. libinstana_sensor_ssl1.1x.soまたは'libinstana_sensor_ssl3x.so名前を'libinstana_sensor.soに変更するか、'nginx.confファイル内の'opentracing_load_tracer /usr/local/lib/libinstana_sensor.so /etc/instana-config.json;行を、必要な抽出モジュール名に基づいて更新する。

   2. これらの環境変数を許可するために、'nginx.confファイルに'env INSTANA_ENDPOINT_URL;と'env INSTANA_AGENT_KEY;行を追加する。

      # The following line adds the basic module Instana uses to get tracing data.
      # It is required that you use the version of this module built by Instana,
      # rather than the one shipped in many NGINX distros, as there are some
      # modifications in the Instana version that are required for tracing to work
      load_module modules/ngx_http_opentracing_module.so;
      
      # Whitelists environment variables used for tracer configuration to avoid
      # that NGINX wipes them. This is only needed if instana-config.json
      # should contain an empty configuration with "{}" inside to do the
      # configuration via these environment variables instead.
      env INSTANA_SERVICE_NAME;
      env INSTANA_AGENT_HOST;
      env INSTANA_AGENT_PORT;
      env INSTANA_MAX_BUFFERED_SPANS;
      env INSTANA_DEV;
      # Serverless tracing:
      env INSTANA_ENDPOINT_URL;
      env INSTANA_AGENT_KEY;
      
      events {}
      
      error_log /dev/stdout info;
      
      http {
      error_log /dev/stdout info;
      
      # The following line loads the Instana libsinstana_sensor library, that
      # gets the tracing data from ngx_http_opentracing_module.so and converts
      # them to Instana AutoTrace tracing data.
      # The content of instana-config.json is discussed as follows.
      opentracing_load_tracer /usr/local/lib/libinstana_sensor.so /etc/instana-config.json;
       

5. NGINX プロセスを再起動するか、コマンドを実行して reload 設定の再読み込みを実行してください。

Instana （ AutoTrace ）の Webhook を使用すると、 Kubernetes および Red Hat OpenShift 上の NGINX に対して分散トレーシングを自動的に設定できます。ただし、以下の制限事項があります：

• Instana AutoTrace Webhookは、 NGINX 1.19 以降のみに対応しています。
• Instana AutoTrace Webhookは、現時点では OpenResty に対応していません。
• Instana AutoTrace Webhookは、スタンドアロンの NGINX での ConfigMap の使用をサポートしていません。

詳細については、 「 NGINX および ingress-nginx での Webhook 計測の有効化」 を参照してください。

Instana のWebhook （ AutoTrace ）を使用すると、 Kubernetes および Red Hat OpenShift 上のIngress（ NGINX および NGINX ）に対して、分散トレーシングを自動的に設定できます。 NGINX の自動トレースが有効になっている場合、Webhookは、前述の設定スニペットとトレース用バイナリを、 NGINX およびIngress NGINX のコンテナの設定に自動的に組み込みます。

Kubernetes のIngress（ NGINX ）は、 OpenTracing プロジェクトを通じて分散トレーシングを実現します。 Instana エージェントは、Jaeger および Zipkin トレースも取り込むことができるため、トレースが Instana に転送されるように NGINX Ingress を構成することができます。

NGINX のトレース機能を無効にするには、 NGINX の設定ファイルから、, opentracing_load_tracer, および opentracing_propagate_context load_moduleディレクティブに加え、 Instana に関連する環境変数（ INSTANA_AGENT_HOSTINSTANA_SERVICE_NAME や など）を削除してください。 さらに、対応するディレクトリからトレース用ライブラリと ファイルを instana-config.json 削除してください。

load_module modules/ngx_http_opentracing_module.so;

env INSTANA_SERVICE_NAME;
env INSTANA_AGENT_HOST;
env INSTANA_AGENT_PORT;
env INSTANA_MAX_BUFFERED_SPANS;
env INSTANA_DEV;

opentracing_load_tracer /usr/local/lib/libinstana_sensor.so /etc/instana-config.json;

opentracing_propagate_context;

Instana のトレーサーは、 NGINX の標準エラー出力にログ行を出力します。 これらの行には、接頭部 [lis]が付きます。

autotrace-mutating-webhook を使用した自動トレースの場合、問題のトラブルシューティングには、 NGINX の自動トレースに関与するバイナリファイルのログを利用してください。 さらに詳細な情報や状況を伝えるために、これらのログを IBM サポートチームに共有することも可能です。 自動インスツルメンテーションには、ライブラ libinstana_init リと実行ファイルという2つのバイナリ watcher_nginxファイルが関係しています。

• libinstana_sensor のログ・ファイルは /tmp/instana/lii_logs/$PID.logにあります。
• watcher_nginx のログ・ファイルは /tmp/instana/iwn_logs/$PID.logにあります。

ここで、 $PID は、関連するプロセスのプロセス ID を表します。

デフォルトでは、ログ・レベルは error に設定されています。 NGINX を異なるログレベルでデプロイするには、環境変数を設定してログレベルを変更してください。

libinstana_init ライブラリーの場合は、以下の環境変数を設定します。

INSTANA_LII_LOG_LEVEL=debug
 

watcher_nginx 実行可能ファイルの場合は、以下の環境変数を設定します。

INSTANA_IWN_LOG_LEVEL=debug
 

NGINX センサーの警告およびエラーは、 Instana エージェントサービスのログで確認できます。 最新のログ項目を表示するには、次のコマンドを実行します。

systemctl status instana-agent
 

Instana エージェントサービスの完全なログを表示するには、次のコマンドを実行してください：

sudo journalctl -xeu instana-agent.service
 

観察結果：AutoTrace の計測機能を有効にした後、 Kubernetes のIngress「 NGINX 」に属するポッドで、1回の再起動が確認されました：

NAME READY STATUS RESTARTS AGE ingress-nginx-controller-xxxxx 1/1 Running 1 (2m ago) 5m  

原因： この再起動は想定された動作です。 既存のIngress（ NGINX ）デプロイメントに計測機能を追加する場合、Podと ConfigMap は個別に計測対象となります。 Podは、まず既存の ConfigMap, から開始され、その後、 ConfigMap が OpenTracing の設定で更新されます。 NGINX これらの変更はホットリロードできず、新しいトレース設定を適用するには再起動が必要です。

問題：NGINX または Kubernetes Ingress NGINX に Instana を設定した AutoTrace の Webhook のログに、以下のエラーメッセージが表示されています：

dlopen() "/opt/instana/instrumentation/nginx/tracing/ngx_http_opentracing_module.so" failed (Error loading shared library /opt/instana/instrumentation/nginx/tracing/ngx_http_opentracing_module.so: No such file or directory) in /tmp/nginx/nginx-cfg33744904:20 nginx: [emerg] dlopen() "/opt/instana/instrumentation/nginx/tracing/ngx_http_opentracing_module.so" failed (Error loading shared library /opt/instana/instrumentation/nginx/tracing/ngx_http_opentracing_module.so: No such file or directory) in /tmp/nginx/nginx-cfg33744904:20 nginx: configuration file /tmp/nginx/nginx-cfg33744904 test failed  

原因： これは、 ConfigMap がデプロイの準備が完全に整う前に更新された場合に発生する可能性のある、まれなレースコンディションです。 CrashLoopBackOffこの状態では、 NGINX がファイルシステム上にまだ存在しないトレースファイルを読み込もうとするため、コントローラーポッドがクラッシュするか、. 状態に入る原因となります。

解決策： ポッドを削除して、ポッドを再起動します。

kubectl delete pod <pod-name> -n <namespace>

デプロイメント・コントローラーがポッドを再作成すると、ポッドは正常に起動します。

監視対象の種類： nginx_api_not_accessible

この問題を解決するには、「 メトリクスの収集を有効にする 」セクションに記載されている手順に従い、 Instana エージェントがすべての NGINX メトリクスを収集するように設定してください。

監視対象の種類： nginx_status_not_accessible

この問題を解決するには、「 メトリクスの収集を有効にする 」セクションに記載されている手順に従い、 Instana エージェントがすべての NGINX メトリクスを収集するように設定してください。

監視対象の種類： nginx_api_not_found

この問題を解決するには、「 メトリクスの収集を有効にする 」セクションに記載されている手順に従い、 Instana エージェントがすべての NGINX メトリクスを収集するように設定してください。

監視対象の種類： nginx_status_not_found

この問題を解決するには、「 メトリクスの収集を有効にする 」セクションに記載されている手順に従い、 Instana エージェントがすべての NGINX メトリクスを収集するように設定してください。

監視対象の種類： nginx_config_location_not_discovered

この問題を解決するには、「 メトリクスの収集を有効にする 」セクションに記載されている手順に従い、 Instana エージェントがすべての NGINX メトリクスを収集するように設定してください。

問題： Luaコードから発行されるカスタム HTTP リクエストは、自動的にトレースすることができません。

$http_traceparent解決策： トレースの連続性を確保するには、送信側の W3Ctraceparent ヘッダーを、対応する NGINX 変数から引き継ぐ必要があります。 NGINX のTracerは、スパンIDを自動的に更新します。

lua-resty-http などの Lua 版 ` HTTP ` クライアントコードを修正し、ヘッダーがまだ設定されておらず、かつ ` NGINX ` 変数が利用可能な場合に、 ngx.var.http_traceparent `outbound traceparent ` ヘッダーを含めるようにしてください。 詳細については、 lua-resty-http の PR 340、 lua-resty-http の README、 ngx_core_module の README、および lua-nginx-module の README を参照してください。

以下の Lua コード例を参照してください。

local http = require "resty.http"
local http_c = http.new()
local response, error = http_c:request_uri(request_url, {
    method = "GET",
})

/usr/local/openresty/luajit/share/lua/5.1/resty/http.lua以下の lua-resty-http 関数 send_request() （例えば、にあるもの）を次のように修正すれば、このコードは変更せずにそのままにしておくことができます：

--- a/http.lua
+++ b/http.lua
@@ -738,6 +738,10 @@ function _M.send_request(self, params)
     if params.version == 1.0 and not headers["Connection"] then
         headers["Connection"] = "Keep-Alive"
     end
+    -- OpenTelemetry support with NGINX tracer in propagation mode
+    if not headers["traceparent"] and ngx.var.http_traceparent then
+        headers["traceparent"] = ngx.var.http_traceparent
+    end

     params.headers = headers
 

お使いの Lua HTTP クライアントがプロプライエタリであり、この機能に対応していない場合は、以下の代替手段をご利用ください：

local http = require "resty.http"
local http_c = http.new()
local req_headers = {}
if ngx.var.http_traceparent then
    req_headers["traceparent"] = ngx.var.http_traceparent
end
local response, error = http_c:request_uri(request_url, {
    method = "GET",
    headers = req_headers,
})

問題：NGINX センサーが、サポートされていない ngx.var.http_traceparent ファイルを http.lualua-resty-http 検出した。

解決策： 前のドキュメントセクションに記載されているパッチを lua-resty-http 適用し、Lua コード内でヘッダーを設定 X-INSTANA-T/-S/-L するために以前に適用した回避策を削除してください。

問題：NGINX への呼び出しがトレースされず、 NGINX のエラーファイルに以下のエラーが表示されています：

/etc/nginx/modules/ngx_http_opentracing_module.so: failed to map segment from shared object: Permission denied

解決策： SELinuxは、 NGINX プロセスが、共有オブジェクトである OpenTracing モジュールからメモリを読み込み、マッピングすることを阻止しています。 SELinux がエラーの原因であることを確認するには、以下のようにしてスモーク・テストを行うことができます。

1. SELinux を一時的に無効にする
2. NGINX を再起動する

SELinuxを無効にして NGINX を再起動すると、 NGINX のエラーログからエラーメッセージが消え、 Instana が呼び出しを追跡できるようになります。

SELinux を無効にすることは、長期的な解決策ではありません。 正しいかつ安全な方法は、 NGINX プロセスが OpenTracing モジュールからメモリを読み取り、マッピングできるようにするSELinuxポリシーを作成することです。 ` NGINX ` 設定ディレクトリを確認すると、 OpenTracing モジュールを見つけることができます。 NGINX の設定ディレクトリが の場合 /etc/nginx、モジュールは /etc/nginx/modules ディレクトリにあります。 DevOps またはIT部門がSELinuxを設定する必要があります。 詳細については、 Instana でサポートされている一部の Linux ディストリビューションのSELinux設定について解説した、以下のオンラインリソースを参照してください：

• Red Hat における SELinux
• Debian での SELinux
• Ubuntu上の SELinux

NGINX とSELinuxの統合に関する詳細については、 『 NGINX および NGINX PlusのSELinuxとの併用』 を参照してください。

問題 ： NGINX で設定された FastCGI に対して、 OpenTracing のコンテキスト伝播が機能していません。

解決策: すべての FastCGI 構成ブロックで opentracing_propagate_context ディレクティブを opentracing_fastcgi_propagate_context ディレクティブに置き換えます。

nginx:1.24.0問題 ： docker.io などの一部の NGINX 画像は、 restricted-v2 セキュリティコンテキストを使用する OpenShift 環境では互換性がありません。

原因 ：

OpenShift restricted-v2 これらの環境には、以下の制限があります：

• グループへの書き込み権限がありません： NGINX は一般ユーザー（root以外）として実行されています（例：ユーザーID 1000650000 およびグループID 0）。 したがって、変更が必要なすべてのファイルおよびディレクトリには、 グループ書き込み権限が必要です。 watcher_nginx これには、autotracing コンポーネントによってパッチが適用されるファイル /etc/nginx/nginx.conf が含まれます。

• 権限昇格はブロックされています ： OpenShiftrestricted-v2 環境では、権限昇格は許可されていません。 NGINX ポッドはすでに一般ユーザーとして実行されているため、 NGINX の設定から、ユーザーID 101 を指定する NGINX ディレクティブ user nginx; を削除する必要があります。

• CAP_NET_BIND_SERVICELinux のすべての機能が無効化されます。その結果、ポート80など1024未満のポートをリッスンしようとすると、が欠落しているため、 bind() error 13: permission denied が発生します。

解決策 ： NGINX の自動トレースが正しく機能するようにするには：

• nginx.conf実行時データおよび に対して chmod -R g+w 、グループへの書き込み権限を付与します。
• userNGINX ディレクティブは使用しないでください。
• 1024未満のポートは使用しないでください。