NGINX のモニター

NGINXセンサーとNGINXトレースでは、オペレーティングシステムの要件が異なります。

NGINXセンサーの場合、サポートされるオペレーティングシステムはホストエージェントの要件と一致しています。この要件は、各ホストエージェントのサポートされるオペレーティングシステムセクション（ Supported operating systems for Linux など）で確認できます。

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のバージョンとプラットフォームを参照してください。

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

サポート方針の詳細については、 センサーのサポート戦略を参照してください。

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

CPP センサー 1.12.0 以降は、コンテナ・イメージ openresty/openresty CentOS based のサポートを中止している。

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

• PID
• ワーカー・プロセス数
• ワーカー接続数
• 開始時刻
• バージョン
• ビルド (*)
• 住所 (*)
• 世代 (*)
• PPID (*)

• 要求
• 接続数
• プロセス (*)
• 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 は POD_NAME と POD_NAMESPACE 環境変数を自動的に設定します。 そのため、 POD_NAME と POD_NAMESPACE 環境変数を NGINX Pod Spec に追加する必要はありません。

• このコンフィギュレーションでは、 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.2 の出力例を以下に示す：

      # 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 がコンテナで実行されているのではなく、ホスト オペレーティング システムで直接実行されている場合は、2 つの Instana バイナリを他の NGINX モジュールを含むディレクトリにコピーします。

   4. NGINXがモジュールを検索する場所を決定し、 nginx -V コマンドを実行し、 --modules-path 設定オプションを探します。

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

      • コンテナ環境では、これらのファイルをコンテナ・イメージに追加するか、コンテナにボリュームとしてマウントする。
      • docker のマウントポイントについては、 Docker bind mounts を参照のこと。
      • 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_ENDPOINT_URL と INSTANA_AGENT_KEY を追加します。 環境変数の詳細については、 サーバーレス監視のための環境変数を参照。

   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. reload コマンドを実行して、NGINX プロセスを再起動するか、 構成のリロードをトリガします。

Instana AutoTrace webhook は、 Kubernetes および Red Hat OpenShift 上の NGINX に対して、以下の制限付きで分散トレースを自動的に設定できます：

• Instana AutoTrace ウェブフックは、NGINX 1.19 以降のみをサポートしています。
• Instana AutoTrace webhook はまだ OpenResty をサポートしていません。

詳細については、 NGINXおよびingress-nginxでWebhookインスツルメンテーションを有効にするを参照してください。

Instana AutoTrace ウェブフックは、Ingress NGINX および Kubernetes および Red Hat OpenShift 上の NGINX に対して分散トレースを自動的に設定できます。 この Webhook は、 NGINX の自動トレースが有効になっている場合に、前述の設定スニペットとトレースバイナリを NGINX と Ingress NGINX コンテナの設定に自動的に注入します。

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

Instana トレーサーは、ログ行を NGINX の標準エラーに書き込みます。 これらの行には [lis] という接頭辞がついている。

autotrace-mutating-webhookによる自動計測の場合、問題のトラブルシューティングにはNGINXの自動トレースに関与するバイナリファイルのログを使用します。 また、これらのログを共有することで、 IBM サポートに、より詳細な情報を提供し、より良いコンテキストを提供することができます。 自動計測には2つのバイナリファイル（ライブラリ libinstana_init と実行ファイル 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
 

モニタリングの問題タイプ： 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 リクエストを自動的にトレースできない。

解決方法送信される Instana ヘッダーは、それぞれの NGINX OpenTracing 変数から伝搬される必要があります。 そのため、 HTTP リクエストを送信する前に、NGINX 変数 opentracing_context_x_instana_t、 opentracing_context_x_instana_s、 opentracing_context_x_instana_l のヘッダ X-INSTANA-T、 X-INSTANA-S、 X-INSTANA-L を送信リクエストのヘッダ Lua 変数に追加します（ lua-resty-http 関数 request_uri() を使用するなど）。 詳細は lua-nginx-module readmeと lua-resty-http readmeを参照してください。

以下のLuaコード例を参照：

local http_c = http.new()
...
local req_headers = {}
req_headers["X-INSTANA-T"] = ngx.var.opentracing_context_x_instana_t
req_headers["X-INSTANA-S"] = ngx.var.opentracing_context_x_instana_s
req_headers["X-INSTANA-L"] = ngx.var.opentracing_context_x_instana_l

local response, error = http_c:request_uri(request_url, {
    method = "POST",
    headers = req_headers,
    body = req_body
  }
);
 

問題： 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 設定を文書化した以下のオンラインリソースを参照してください：

• 上のSELinux Red Hat
• 上のSELinux Debian
• 上のSELinux Ubuntu

NGINXとSELinuxの統合の詳細については、「 NGINXおよびNGINX PlusとSELinuxの使用 」を参照してください。

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

解決方法すべての FastCGI 設定ブロックの opentracing_propagate_context ディレクティブを opentracing_fastcgi_propagate_context ディレクティブに置き換える。